Be part of the whole thing

Connect to the Printing Coordinator. More...

Functions
struct caps_cl_handle *	caps_cl_instance_create (void)
int	caps_cl_instance_register (struct caps_cl_handle *instance, const struct caps_cl_notifier *notifier, void *data)
void	caps_cl_instance_unregister (struct caps_cl_handle *instance)
void	caps_cl_instance_destroy (struct caps_cl_handle *instance)

Detailed Description

In order to deal with printers and documents to print, a connection must be established to the Printing Coordinator first.

A simple use case contains the following steps:

In your program it looks like this:

struct caps_cl_handle *instance;
 
instance = caps_cl_instance_create();
caps_cl_instance_register(instance, NULL, NULL);
 
do {
 // […]all your work here[…]
} while (!done);
 
caps_cl_instance_unregister(instance);
caps_cl_instance_destroy(instance);

Refer Deal with printers and Print documents for what you can do in the Do all the hard work block.

Function Documentation

caps_cl_instance_create()

struct caps_cl_handle * caps_cl_instance_create

(

void

)

Create a client instance handle

Returns

New client instance handle

This is the first call to be done in order to connect to the Printing Coordinator from the client side. All further functions mentioned here depend on this client instance handle.

Note

Does not return in case of memory failure

Postcondition

The returned client instance handle needs to be freed after use via caps_cl_instance_destroy()

caps_cl_instance_register()

int caps_cl_instance_register	(	struct caps_cl_handle *	instance,
		const struct caps_cl_notifier *	notifier,
		void *	data
	)

Register your client instance handle to the Printing Coordinator

Parameters

[in,out]	instance	Client instance handle to register
[in]	notifier	Notifier definitions (can be NULL)
[in]	data	Some anonymous data to be forwarded to the notifier functions (as their parameter data, can be NULL)

Return values

0	Client instance handle successfully registered at the Printing Coordinator
-EIO	Real communication error with the Printing Coordinator
-EINVAL	Bad/unexpected reply from the Printing Coordinator (should not happen)
-ENOMSG	Notifiers aren't possible (should not happen)
-ENOSYS	Unsupported client version

After a successful call, the client instance handle is a registered client instance and can be used by all other functions from this library.

The notifier and data parameter are optional. Refer Receive state change notifiers for details how to use it.

Note

-EIO and -ENOMSG create readable error messages (refer caps_cl_error_messages_catch())

Precondition

instance must be a valid client instance handle returned by caps_cl_instance_create() call

Attention

Only call caps_cl_instance_unregister() on termination if this call was successful

caps_cl_instance_unregister()

void caps_cl_instance_unregister

(

struct caps_cl_handle *

instance

)

Unregister your client instance from the Printing Coordinator

Parameters

[in]

instance

Client instance to unregister

Attention

After this call, the client instance is invalid and cannot be used anymore by most of the other functions in this library. Only caps_cl_instance_destroy() still accepts this client instance handle.

Always call this function prior exiting your application and prior caps_cl_instance_destroy().

Precondition

instance must be a registered client instance

caps_cl_instance_destroy()

void caps_cl_instance_destroy

(

struct caps_cl_handle *

instance

)

Free all client instance handle resources

Parameters

[in]

instance

Client instance handle to destroy

Always call this function prior exiting your application and after caps_cl_instance_unregister().

Note

This call will also close error message catching. Refer Error message handling for details.

Precondition

instance must be a client instance handle returned by caps_cl_instance_create() call