 |
CAPS Universe documentation
1.0.4
All you need to know to be successful
|
|
CAPS Universe documentation
1.0.4
All you need to know to be successful
|
The regular user who wants to print something isn't the audience of this section. Here the user is the developer of a different CAPS component, which just use libcapsbase.
Don't try to be smart, use pkg-config instead to retrieve the information you need to compile and link your application against libcapsbase.
To compile your code, just include its header:
And ask pkg-config what include path is required to find this header file.
pkg-config --cflags libcapsbase
To link your application against libcapsbase ask pkg-config as well. Use the output of this command to parametrize the linker:
pkg-config --libs libcapsbase
--as-needed is in use (which is the default in the CAPS universe).Don't invent your own Makefile to build your package. Use the autotools or something similar to manage your buildsystem.
For the autotools just use the PKG_CHECK_MODULES m4 macro in your configure.ac to get the information you need to use libcapsbase:
PKG_CHECK_MODULES([LIBCAPSBASE], [libcapsbase >= 1])
And then just refer this information in your Makefile.am:
my_application_CPPFLAGS = \
@LIBCAPSBASE_CFLAGS@
my_application_LDADD = \
@LIBCAPSBASE_LIBS@
One API part of the library is the handling of messages. Other CAPS components should never output their messages by their own. Messages can be for plain informative purpose or for giving hints about the cause in the case of a failure.
All CAPS components always should use the libcapsbase API to emit their messages. This enables the enduser of CAPS to configure the message output at one central location.
The main message output function is caps_message_print. It carries a verbosity level and some other info, which makes the source code harder to read. That's why libcapsbase comes with some convenience macros. To emit an informative message you can use:
Or the convenience macro:
A summary of convenience macros can be found in Message macros.
The enduser can control the verbosity via caps_verbosity_level_set(), and can redirect the whole output by calling caps_message_stream_set() with its own stream handle.
In the examples above the National Language Support (NLS) was skipped. The correct call of caps_print_info() with NLS looks like:
The API summary regarding message handling can be found in Base functions.
A simple failure handling is also located in libcapsbase. Whenever you detect a bad usage of your functions, where a programming error is the cause, call caps_developers_failure_report() with a short message. After emitting the message, the program terminates with a stack trace (if debugging is enabled). Don't forbear the programmer this error, name it!
When the memory is exhausted don't try to be smart. Most of the time this is a hopeless moment for your program and miracles won't happen. Just terminate. Terminate by calling caps_memory_failure_report() in this case. Always. Don't think twice!
For both functions, libcapsbase can be configured to use exit() or abort() to terminate. Using abort() enables the enduser to get a core dump of the process for a port mortem analysis. Refer Abort or Exit Choice.
The API summary regarding failure handling can be found in Failure reporting/handling.
Various CAPS components need access to configuration files and other CAPS components. To avoid compiling in filesystem paths all over the place, libcapsbase provides this information at one location instead.
The API summary regarding file system paths can be found in Helper functions.
Here is the list of filesystem paths CAPS manages and for what reason:
CAPS Printer Device Database Directory
You can retrieve this directory via pkg-config:
pkg-config --variable=caps_config_path caps
In C you can retrieve this directory via caps_helper_device_db_path_create() and caps_helper_device_db_dir_fd().
CAPS Printer Driver Configuration Directory
You can retrieve this directory via pkg-config:
pkg-config --variable=caps_driver_runtime_config_path caps
In C you can retrieve this directory via caps_helper_driver_config_path_create() and caps_helper_driver_config_dir_fd().
CAPS Printer Driver Database Directory
For installing purposes you can retrieve this directory via pkg-config:
pkg-config --variable=caps_driverdatabase_path caps
In C you can retrieve this directory via caps_helper_driver_db_path_create() and caps_helper_driver_db_dir_fd().
CAPS Printer Driver Executables Directory
You can retrieve this directory via pkg-config:
pkg-config --variable=caps_driver_path caps
In C you can retrieve this directory via caps_helper_driver_path_create() and caps_helper_driver_dir_fd().
This directory contains unique subdirectories on a per printing device base. Each contains printing device specific configurations. These subdirectories were created at run-time when a new printing device is connected to the host the first time. When it happens, an INI file is also created inside the new subdirectory and contains some default configurations to be able to work with the specific printing device.
These default printing device specific configurations are intended to be changed by the user. Its also intended to have printing device specific location where the user can overwrite printing driver defaults (from the driver specific INI files in CAPS Printer Driver Configuration Directory). So its possible to use individual settings for each printing device.
You can retrieve this directory via pkg-config:
pkg-config --variable=caps_device_param_path caps
Since the printing device specific subdirectories are created at run-time and on demand, we cannot retrieve their full path with pkg-config. In this case the CAPS Device Database contains the links between the physical printing device, its corresponding printing driver executable (CAPS Printer Driver Executables Directory), the printing driver's default configuration INI file (CAPS Printer Driver Configuration Directory) and its unique subdirectory with the device parameters.
