 |
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
|
Some declarations used internally only. More...
Go to the source code of this file.
Data Structures | |
| struct | object_state_prn |
| Printer state information for internal use. More... | |
| struct | object_state_job |
| Print job state information for internal use. More... | |
| struct | object_progression_job |
| Print job progression information. More... | |
| struct | caps_coordinator |
| struct | caps_printer_info |
Macros | |
| #define | DSO_VISIBLE |
| #define | ARRAY_SIZE(x) (sizeof(x)/sizeof(x[0])) |
| #define | caps_invalidate_pointer(pointer) |
| #define | caps_print_debug(fmt, ...) |
| #define | _(string) (string) |
| #define | NLS_(string) (string) |
| #define | CONFIG_TIMEOUT 30000 |
| #define | CAPS_RUNTIME_CONFIG_LEVEL "base" |
| #define DSO_VISIBLE |
| #define ARRAY_SIZE | ( | x | ) | (sizeof(x)/sizeof(x[0])) |
| #define caps_invalidate_pointer | ( | pointer | ) |
| #define caps_print_debug | ( | fmt, | |
| ... | |||
| ) |
| #define _ | ( | string | ) | (string) |
| #define NLS_ | ( | string | ) | (string) |
| #define CONFIG_TIMEOUT 30000 |
How long to wait for a CAPS printing coordinator answer via DBUS.
Some constraints:
| #define CAPS_RUNTIME_CONFIG_LEVEL "base" |
Define the INI file 'level', all run-time related settings should be at
This value is important to have all read and merged settings at the expected 'level' to make retrieving these settings successful.
| void caps_init_runtime_data | ( | struct caps_coordinator * | database | ) |
| void caps_exit_runtime_data | ( | struct caps_coordinator * | database | ) |
Clean up all run-time information
| [in,out] | database | Printer/job database |
| caps_identifier pc_provider_unique_printer_id_create | ( | struct caps_coordinator * | database, |
| unsigned | property | ||
| ) |
Create a printing provider instance with a unique identifier and add it to the list of active printers
| [in,out] | database | Printer data base |
| [in] | property | Provider's unique property for identification |
This provider's property will be used in every later RPC to identify the printing provider. The property will be used to check if the request matches the printing provider. The provider's property can be based on "something", a connection information for example. This information must be constant over the lifetime of the printing provider.
A printing provider can create and control more than one printer. Thus, it is allowed for one provider to create as much printers as it wants (think about an IPP service).
| int pc_provider_printer_id_free | ( | struct caps_coordinator * | database, |
| unsigned | property, | ||
| caps_identifier | pr_id | ||
| ) |
Free a printing provider description, e.g. remove it from the list of active printers
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| [in] | pr_id | In use 'Printer ID' to be freed |
| 0 | On success |
| -ENODEV | pr_id is invalid (should not happen, maybe related to -EPERM) |
| -EPERM | provider and pr_id don't match |
This function is triggered by the printing provider when it calls caps_pp_instance_unregister()
| caps_identifier pc_provider_id_by_property_get | ( | struct caps_coordinator * | database, |
| unsigned | property | ||
| ) |
Get the unique printer ID based on its property
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| Positive | The corresponding ID |
| CAPS_INVALID_IDENTIFIER | If the property has no printer anymore |
| void pc_provider_orphaned_printer_free | ( | struct caps_coordinator * | database, |
| unsigned | property | ||
| ) |
Free all orphaned printers from a printing provider, e.g. remove them from the active printer list
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
If a printing provider doesn't call caps_pp_instance_unregister() when it terminates, we do not get this event in a regular manner, e.g. it will not free its ID. We need a different method to remove no longer existing providers. This method uses the property to check if this provider is still registered here and remove its printers on demand.
If this provider has already unregistered its ID in a regular manner, we will not find its property anymore and nothing else happens.
Since a printing provider can own more than one printer, this routine loops until all related printers are removed.
| int pc_provider_printer_state_set | ( | struct caps_coordinator * | database, |
| unsigned | property, | ||
| caps_identifier | pr_id, | ||
| const struct object_state_prn * | newstate | ||
| ) |
Set a printer's new state
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| [in] | pr_id | In use 'Printer ID' to get a job for |
| [in] | newstate | The new state |
| 0 | On success |
| positive | Clients must be informed about this change |
| -EINVAL | state invalid |
| -ENODEV | pr_id is invalid (should not happen, maybe related to -EPERM) |
| -EPERM | provider and pr_id don't match |
Called by the printing provider to define a new state for its printer.
The provider can change the printer's state to one of the visible states, but never back to LIBCAPS_PP_STATE_INVISIBLE.
The provider can change the printer's state to one of the tear down states, but never back to the visible states.
Clients must be informed about a change if:
| int pc_provider_printer_info_set | ( | struct caps_coordinator * | database, |
| unsigned | property, | ||
| caps_identifier | pr_id, | ||
| const char * | name, | ||
| const char * | info, | ||
| const char * | location, | ||
| const char * | vendor, | ||
| const char * | model, | ||
| struct caps_supported_mime_list * | list | ||
| ) |
Setup the main printer information
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| [in] | pr_id | In use 'Printer ID' to get a job for |
| [in] | name | Printer name |
| [in] | info | Short info about the printer |
| [in] | location | Location info about the printer |
| [in] | vendor | Vendor name |
| [in] | model | Model name |
| [in] | list | MIME type list |
| 0 | On success |
| positive | Clients must be informed about this change |
| -BUSY | Information already set |
| -ENODEV | pr_id is invalid (should not happen, maybe related to -EPERM) |
| -EPERM | provider and pr_id don't match |
Called by the printing provider to define the main information for its printer.
| int pc_provider_ppd_set | ( | struct caps_coordinator * | database, |
| unsigned | property, | ||
| caps_identifier | pr_id, | ||
| int | fh | ||
| ) |
Add a PPD file to the printing provider data
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| [in] | pr_id | The 'Printer ID' to set its PPD |
| [in] | fh | The PPD file handle |
| 0 | On success |
| -ENODEV | pr_id is invalid (should not happen, maybe related to -EPERM) |
| -EPERM | provider and pr_id don't match |
| -EINVAL | fh seems invalid |
The content of the PPD file isn't transferred - only a filehandle of the PPD.
It's possible to set the PPD more than once. In this case the previous one will be closed. The libcapsprovider creates the PPD files as invisible temporary files. If the file close here is the last one the file gets removed from the filesystem.
| caps_identifier pc_provider_job_id_prepare | ( | struct caps_coordinator * | database, |
| unsigned | property, | ||
| caps_identifier | pr_id | ||
| ) |
Get the next available job identifier for the printing provider in question
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| [in] | pr_id | In use 'Printer ID' to get a job for |
| Positive | Job ID |
| 0 | No job available, e.g. queue empty |
| -ENODEV | pr_id is invalid (should not happen, maybe related to -EPERM) |
| -EPERM | provider and pr_id don't match |
Printer providers can poll for new jobs or wait for the new job broadcast signal.
| int pc_provider_job_get | ( | struct caps_coordinator * | database, |
| unsigned | property, | ||
| caps_identifier | pr_id, | ||
| caps_identifier | job_id, | ||
| int * | fh, | ||
| const char ** | parameter | ||
| ) |
Get the filehandle and printing parameter of the corresponding job
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| [in] | pr_id | In use 'Printer ID' to get a job for |
| [in] | job_id | The job to report the printing progression for |
| [out] | fh | File handle of the printing job data |
| [out] | parameter | Where to store a pointer to the printing parameter |
| 0 | On success (*fh and *parameter are valid) |
| -ENODEV | Printer is already gone (should not happen, maybe related to -EPERM) |
| -EPERM | provider and pr_id don't match |
| -EINVAL | job_id seems invalid (maybe the print job is already gone) |
| -EIO | Job not ready to print, call pc_provider_job_id_prepare() first |
| int pc_provider_job_state_set | ( | struct caps_coordinator * | database, |
| unsigned | property, | ||
| caps_identifier | pr_id, | ||
| caps_identifier | job_id, | ||
| const struct object_state_job * | state | ||
| ) |
Set a new state of a job
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| [in] | pr_id | In use 'Printer ID' to get a job for |
| [in] | job_id | The job to report it's finished |
| [in] | state | The new state the job is in |
| 0 | On success |
| -ENODEV | Printer is already gone (should not happen, maybe related to -EPERM) |
| -EPERM | provider and pr_id don't match |
| -EINVAL | job_id seems invalid or state ID is invalid |
| int pc_provider_printing_progression_report | ( | struct caps_coordinator * | database, |
| unsigned | property, | ||
| caps_identifier | pr_id, | ||
| caps_identifier | job_id, | ||
| const struct object_progression_job * | p | ||
| ) |
Report the printing progression for a specified job
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| [in] | pr_id | In use 'Printer ID' to get a job for |
| [in] | job_id | The job to report the printing progression for |
| [in] | p | The progression information |
| 0 | On success, do not send a job change signal to clients |
| 1 | On success, send a job change signal to clients |
| -ENODEV | Printer is already gone (should not happen, maybe related to -EPERM) |
| -EPERM | provider and pr_id don't match |
| -EINVAL | job_id seems invalid |
This information is provided by the printing provider and used by a client.
This function should be used by libcapsraster and should include the copies of a medium or document as well.
| caps_identifier pc_provider_job_drain | ( | struct caps_coordinator * | database, |
| caps_identifier | pr_id | ||
| ) |
Remove next job from the printing provider's queue and destroy it
| [in,out] | database | Printer data base |
| [in] | pr_id | The printing provider's identifier to add the job to |
| Positive | ID of the drained job |
| CAPS_INVALID_IDENTIFIER | No job to drain in the printing provider's queue |
Drain the queue one by one. This supports sending notification about each of it.
| int pc_provider_job_finished | ( | struct caps_coordinator * | database, |
| unsigned | property, | ||
| caps_identifier | pr_id, | ||
| caps_identifier | job_id | ||
| ) |
Report the job is finished
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| [in] | pr_id | In use 'Printer ID' to get a job for |
| [in] | job_id | The job to report it's finished |
| 0 | On success |
| -ENODEV | Printer is already gone (should not happen, maybe related to -EPERM) |
| -EPERM | provider and pr_id don't match |
| -EINVAL | job_id seems invalid |
Means the job will be removed from the printer's queue.
| int pc_client_job_cancel | ( | struct caps_coordinator * | database, |
| caps_identifier * | pr_id, | ||
| caps_identifier | job_id | ||
| ) |
Cancel the given printing job
| [in,out] | database | Printer data base |
| [out] | pr_id | Where to store the printing provider identifier (which belongs to the job_id) |
| [in] | job_id | The printing job identifier to cancel |
| 0 | Job removed from queue |
| positive | The provider must remove it |
| -EINVAL | There is no such job |
Job's state LIBCAPS_PJ_STATE_QUEUED means it is still in the coordinators printing queue and thus, we can just remove the job from the queue. pc_provider_job_get() can deal with it. In this case, the interested clients must be notified about this change.
If a job is still in the coordinators printing queue it will be removed only. If the job is already in processing state by the printing provider the job's description is only changed to "CANCEL" and all interested instances must be informed about this change.
| int pc_client_job_state_get | ( | struct caps_coordinator * | database, |
| caps_identifier | job_id, | ||
| const struct object_state_job ** | state | ||
| ) |
Get the job's current state it is in
| [in,out] | database | Printer data base |
| [in] | job_id | The printing job identifier to get the state from |
| [out] | state | Where to store the job's state |
| 0 | On success (*state is valid) |
| -ENOENT | Job is already gone |
state->message can be NULL | int pc_client_job_progression_get | ( | struct caps_coordinator * | database, |
| caps_identifier | job_id, | ||
| const struct object_progression_job ** | p | ||
| ) |
Get the job's current progression information
| [in,out] | database | Printer data base |
| [in] | job_id | The printing job identifier to get the state from |
| [in] | p | Where to store the pointer to the info |
| 0 | On success (returned pointer is valid) |
| -ENOENT | No such job |
| -EAGAIN | No progression yet, try again later |
| int pc_client_printer_state_get | ( | struct caps_coordinator * | database, |
| caps_identifier | pr_id, | ||
| const struct object_state_prn ** | state | ||
| ) |
Retrieve the current state from an active printer
| [in,out] | database | Printer/job data base |
| [in] | pr_id | The printing provider's identifier |
| [out] | state | Where to store the state information |
| 0 | On success (*state is valid) |
| -ENODEV | Printer is already gone |
Since a client can never query for an invisible printer, we assume here, the state is already set by the provider.
| void pc_client_printer_list_get | ( | struct caps_coordinator * | database, |
| caps_identifier ** | list, | ||
| unsigned * | cnt | ||
| ) |
Create a list of currently known printer IDs
| [in] | database | Printer/job data base |
| [out] | list | Where to store the array of printer IDs |
| [out] | cnt | Element count in list |
| int pc_client_printer_info_get | ( | struct caps_coordinator * | database, |
| caps_identifier | pr_id, | ||
| struct caps_printer_info * | info | ||
| ) |
Get the main printer info
| [in,out] | database | Printer/job data base |
| [in] | pr_id | The printing provider's identifier |
| [out] | info | Where to store the information |
| 0 | On success (*info is valid) |
| -ENODEV | Printer is already gone (*info is invalid) |
Should always work, since a client can query for this information only if the printer is already visible. And it is visible only, if this information is already set by the provider.
| caps_identifier pc_client_job_commit | ( | struct caps_coordinator * | database, |
| caps_identifier | pr_id, | ||
| int | fh, | ||
| const char * | params | ||
| ) |
Add a job to the printer's queue
| [in,out] | database | Printer data base |
| [in] | pr_id | The printing provider's identifier to add the job to |
| [in] | fh | File handle of the job |
| [in] | params | Printing parameter (can be NULL) |
| Positive | Job identifier |
| -ENODEV | Printer is already gone |
| -EPERM | Printer does not accept new print jobs |
| int pc_client_printer_ppd_get | ( | struct caps_coordinator * | database, |
| caps_identifier | pr_id | ||
| ) |
Returns a file descriptor of an individual copy of the PPD
| [in,out] | database | Printer/job data base |
| [in] | pr_id | The printing provider's identifier |
| positive | File descriptor to the PPD |
| -EAGAIN | PPD not available yet, try again later on (should not happen) |
| -ENODEV | Printer is already gone |
| -EPERM | Insufficient permissions in the CAPS Document Storage Directory |
| void runtime_configuration_base_read_in | ( | struct caps_inif_table * | runtime_config | ) |
Read-in the CAPS universe shared 'caps.ini' file for basic run-time configuration
| [out] | runtime_config | The configuration table to fill |
Expects the file in CAPS Configuration Directory (e.g. '/etc/caps/caps.ini' for example)
runtime_config must already be initialized and empty! Read-in the CAPS universe shared 'caps.ini' file for basic run-time configuration
| [out] | runtime_config | The configuration table to fill |
Expects the file in CAPS Configuration Directory (e.g. '/etc/caps/caps.ini' for example)
runtime_config must already be initialized but empty! | void runtime_configuration_class_merge_in | ( | struct caps_inif_table * | runtime_config, |
| enum caps_user_class | clss | ||
| ) |
Merge-in the shared service dependend INI file for basic run-time configuration
| [out] | runtime_config | The configuration table to merge more content to |
| [in] | clss | The class of the running program (used to identify the corresponding service dependend INI file) |
For clss refer layer for the corresponding service INI file.
runtime_config must already be initialized Currently the already collected configuration gets removed if it fails to merge the class INI content
The error message needs more details: Why/What/What now?
Merge-in the shared service dependend INI file for basic run-time configuration
| [out] | runtime_config | The configuration table to merge more content to |
| [in] | clss | The class of the running program (used to identify the corresponding service dependend INI file) |
For clss refer layer for the corresponding service INI file.
Currently the already collected configuration gets removed if it fails to merge the class INI content
The error message needs more details: Why/What/What now?
| void runtime_configuration_apply | ( | struct caps_inif_table * | runtime_config, |
| enum caps_user_class | clss, | ||
| const char * | package | ||
| ) |
Read in a fixed sequence of INI files as a base run-time configuration
| [out] | runtime_config | |
| [in] | clss | Application class (refer enum caps_user_class) |
| [in] | package | Used for the program's INI file (can be NULL) |
This function is intended for the printing coordinator internal tools and printing providers via libcapsprovider (not clients).
runtime_config must already be initialized Read in a fixed sequence of INI files as a base run-time configuration
| [out] | runtime_config | |
| [in] | clss | Application class (refer enum caps_user_class) |
| [in] | package | Used for the program's INI file (can be NULL) |
This function is intended for the printing coordinator internal tools and printing providers via libcapsprovider (not clients).
| void runtime_configuration_apply_verbosity | ( | const struct caps_inif_table * | runtime_config | ) |
Apply the verbosity setting if available
| [out] | runtime_config | The configuration to check for the verbosity setting |
This function is intended to be used whenever a run-time config is available. It is intended to apply the requested setting as early as possible.
The verbosity setting is always expected at
The new value from the INI file is only applied if it is higher than before. Else it gets ignored to give the application a change to overwrite it locally.
|
inlinestatic |
Check if the given file descriptor is still valid
| [in] | fd | File descriptor to check |
| true | File descriptor is valid |
| false | File descriptor is invalid |
