 |
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
|
Printer and print job management routines. More...
Macros | |
| #define | PROGRESSION_TIMEOUT 2 |
These functions are used by the printing coordinator to handle the printers. All printing provider and printing client calls are ending here.
| #define PROGRESSION_TIMEOUT 2 |
How much time in seconds must be elapsed since the last report to generate the next job change signal on the DBUS Used in pc_provider_printing_progression_report() to reduce the noise on the DBUS.
|
static |
Lock the printer/job database for an atomic operation
| [in,out] | database | Printer/job data base |
|
static |
Unlock the printer/job database
| [in,out] | database | Printer/job data base |
|
static |
Setup a new state for a job
| [in,out] | state | The job's state to setup |
| [in] | state_id | Job's new state ID |
| [in] | reason_id | Job's new reason ID |
| [in] | message | An optional message for this state or reason (can be NULL) |
|
static |
Mark a job to reflect it is in "incoming" state
| [in,out] | job | The job to change its state |
"Incoming" means the job ID is committed to the client, and now we wait for the corresponding job's data
|
static |
Mark a job to reflect it is in "queued" state
| [in,out] | job | The job to change its state |
"Queued" means, the coordinator has received the job and put it into the printing provider's queue. The printing job is now ready for printing.
|
static |
Mark a job to reflect it is in "unqueued" state
| [in,out] | job | The job to change its state |
"Prepared" means, the printing provider has retrieved the job's identifier and now the retrieve of the job data (e.g. its filehandle) itself is awaiting in the next step.
|
static |
Check if a job description entry is valid
| [in] | job | Job to check |
| true | If job description is valid |
| false | If the job description is invalid |
"Valid" means: description is not in initialized state anymore
|
static |
Check if a job is ready for printing
| [in] | job | Job to check |
A ready for printing job entry is:
Keep the processing_state test in sync with job_mark_in_queued_state()
|
static |
Check if a job is prepared for printing
| [in] | job | Job to check |
| true | If prepared |
| false | Not yet prepared |
A prepared job entry is:
"Prepared" means: the printing provider has already retrieved the job's identifier, but not yet retrieved the printing data filehandle. Keep the processing_state test in sync with job_mark_in_prepared_state()
|
static |
Free all resources used by a job description
| [in,out] | job | The job to free |
This will remove everything entirely. If the job related file descriptor is of type "self removing", this will remove the document file as well.
|
static |
Remove a job from a printer's queue
| [in] | printer | The printer to remove the job from |
| [in,out] | job | The job to free |
|
static |
Get a specific job from a printing provider's queue
| [in] | printer | The printer to query the next job |
| [in] | job_id | Job identifier to find |
| Pointer | The Job |
| NULL | In case there is none |
|
static |
Get a job based on its identifier and get its corresponding printing provider identifier as well
| [in,out] | database | Printer data base |
| [out] | pr_id | Printing provider's identifier store |
| [in] | job_id | Job identifier to find |
| Pointer | Job on success (and *pr_id is valid) |
| NULL | If the job wasn't found (and *pr_id isn't touched) or if no printers are found (and *pr_id is CAPS_INVALID_IDENTIFIER) |
|
static |
Create a positive 64 bit number for a printer or job ID
|
static |
Create a unique identifier for a job
| [in,out] | database | Printer data base |
The generated job ID is unique for all currently known jobs and for the past jobs as well.
|
static |
Init a job description structure
| [in,out] | job | What to initialize |
|
static |
Create a new job description structure
|
static |
Init a printer description structure
| [in,out] | printer | What to initialize |
The printer is initialized to:
|
static |
Allocate a new printer structure
The new printer gets initialized via printer_init()
|
static |
Free printer's MIME type information
| [in,out] | printer | The printer to clean its MIME type info |
Same features like free_mime_types() in libcapsprovider.c
A copy function for the MIME types can be found in copy_mime_types() in libcapsprovider as well.
|
static |
Destroy a printer information collection, e.g. free all resources
| [in] | printer | The printer structure to free |
|
static |
Remove this printer from the list of active printers
| [in,out] | database | Printer data base |
| [in,out] | printer | The printer structure to remove/destroy |
|
static |
Get an active printer description based on its identifier
| [in,out] | database | Printer data base |
| [in] | pr_id | Printer Identifier to search for |
| Pointer | A printer description |
| NULL | In case the identifier does not exist |
|
static |
Get an active printer description based on its property
| [in,out] | database | Printer data base |
| [in] | property | Provider's property |
| Pointer | A printer description |
| NULL | In case the property doesn't exist |
| 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 |
|
static |
Create a numerical unique identifier for a printing provider
| [in,out] | database | Printer data base |
The generated printer ID is unique for all currently active printers.
| 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).
|
static |
Check if the requesting provider has access permissions
| [in] | printer | Printing provider's description |
| [in] | property | Provider's property to check for |
| true | If the provider has permission |
| false | If the provider has no permission |
| 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()
| 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.
|
static |
Get the next available job waiting for print from the printer's queue
| [in] | printer | The printer to unqueue the next job |
| Pointer | The Job |
| NULL | In case there is none |
"Available" means the job is ready, but its ID is not yet committed to the printing provider.
ensure the order of processing (first come, first serve)
Check here, if a different job is still in printing state. This would be a failure.
| 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_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.
| 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.
| 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_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.
| 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.
| 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 |
|
static |
Check if this printing provider entry is active
| [in] | printer | The entry to check |
| true | if entry is still active |
| false | else |
active means, the entry is in use and the printer is visible to the public
| 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_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.
| 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.
|
static |
Duplicate a file and its content
| [in] | fd | File descriptor to read from |
| positive | File descriptor with duplicated content |
| negative | errno on failure |
Since the PPD file descriptor stored here is a shared resource, we need to forward a copy of it instead. Else its racy like hell if a concurrent access happens at the client level.
| 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 |
| 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_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.
| 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 |
