6.3 Types and functions

6.3.1 Server interaction

Function: cca_client_t * cca_init (cca_args_t * args, const char * client_class, int client_flags, cca_protocol_t protocol)

Open a connection to the server. Returns NULL on failure.

The args argument must be obtained using cca_extract_args.

The client_class argument must be a string that will never change over invocations of the program. If using GNU automake, the best way to do this is to use the PACKAGE_NAME macro that is automatically defined.

The client_flags argument should be 0 or bitwise-OR'd values from this list:

CCA_Config_Data_Set

The client wishes to save its data use the LADCCA config system. See @xref{Configs} and section 6.4 Event protocol.

CCA_Config_File

The client saves its data to a file. See section 6.4 Event protocol.

CCA_Server_Interface

The client is a server interface. See section 6.4.2 Server interfaces.

CCA_No_Autoresume

This flag is set by the @command{--ladcca-no-autoresume} command line option and should not normally be set by clients themselves.

CCA_Terminal

The client is dependant on being run in a terminal.

The protocol argument should be the version of the high-level protocol that the client implements See @xref{Protocol versioning} for information on how to contruct a cca_protocol_t variable.

Function: cca_args_t * cca_extract_args (int * argc, char *** argv)

Extract LADCCA-specific arguments from argc/argv for use in cca_init. This should be done before the client checks the arguments.

Function: const char * cca_get_server_name (cca_client_t * client)

Get the hostname of the server.

Function: unsigned int cca_get_pending_event_count (cca_client_t * client)

Get the number of pending events.

Function: cca_event_t * cca_get_event (cca_client_t * client)

Retrieve an event. The event must be freed using cca_event_destroy. Returns NULL if there are no events pending.

Function: unsigned int cca_get_pending_config_count (cca_client_t * client)

Get the number of pending configs.

Function: cca_config_t * cca_get_config (cca_client_t * client)

Retrieve a config. The config must be freed using cca_config_destroy. Returns NULL if there are no configs pending.

Function: void cca_send_event (cca_client_t * client, cca_event_t * event)

Send an event to the server. The event must be created using cca_event_new or cca_event_new_with_type. The library takes over ownership of the memory and it should not be freed by the client.

Function: void cca_send_config (cca_client_t * client, cca_config_t * config)

Send some configuration data to the server. The config must be created using cca_config_new, cca_config_new_with_key or cca_config_dup. The library takes over ownership of the memory and it should not be freed by the client.

Macro: cca_enabled (client)

Check whether the cca_client_t pointer client is not NULL, and if it isn't, that the server is still connected.

Function: int cca_server_connected (cca_client_t * client)

Check whether the server is connected. Returns 1 if the server is still connected or 0 if it isn't

Function: void cca_jack_client_name (cca_client_t * client, const char * name)

Tell the server the client's JACK client name. This is a convenience function that just sends a CCA_Jack_Client_Name event to the server. @xref{Normal CCA_Jack_Client_Name}.

@anchor{cca_alsa_client_id}

Function: void cca_alsa_client_id (cca_client_t * client, unsigned char id);

Tell the server the client's ALSA client ID. This just is a convenience function that sends a CCA_Alsa_Client_ID event to the server. @xref{Normal CCA_Alsa_Client_ID}.

6.3.2 Protocol versioning

@anchor{Protocol versioning} The event protocol (See section 6.4 Event protocol,) is versioned with a major and minor component. The cca_protocol_t type represents a version number in a 32-bit unsigned integer split 16:16. A protocol is comptible with the server's protocol if the major numbers are the same and the minor number is less than, or equal to, the server's minor number (ie, 1.0 is compatible with a server using 1.0, 1.1 is compatible with a server using 1.3, but neither 2.0 or 1.6 are compatible with a server using 1.4. The minor component may be dropped in the future.

Macro: CCA_PROTOCOL (major, minor)

Contruct a protocol version with a major component major and a minor component minor.

Macro: CCA_PROTOCOL_GET_MAJOR (protocol)

Obtain the major component of a cca_protocol_t protocol version.

Macro: CCA_PROTOCOL_GET_MINOR (protocol)

Obtain the minor component of a cca_protocol_t protocol version.

Function: const char * cca_protocol_string (cca_protocol_t protocol)

Obtain a string representation of the protocol version protocol. String representations are of the form "major.minor".

6.3.3 Events

@anchor{Events}

Function: cca_event_t * cca_event_new (void)

Function: cca_event_t * cca_event_new_with_type (enum CCA_Event_Type type)

Function: void cca_event_destroy (cca_event_t * event)

Function: enum CCA_Event_Type cca_event_get_type (const cca_event_t * event)

Function: const char * cca_event_get_string (const cca_event_t * event)

Function: void cca_event_set_type (cca_event_t * event, enum CCA_Event_Type type)

Function: void cca_event_set_string (cca_event_t * event, const char * string);

6.3.3.1 Server interface events

@anchor{Server interface events}

All events have a LADCCA ID and project name property. They are only relevant to server interfaces, however, which need to refer to clients other than themselves and to projects (server interfaces are never assigned to a project.)

Function: void cca_event_get_client_id (const cca_event_t * event, uuid_t id)

The event's client ID property will be copied into id.

Function: const char * cca_event_get_string (const cca_event_t * event)

Function: void cca_event_set_client_id (cca_event_t * event, enum uuid_t id)

Function: void cca_event_set_project (cca_event_t * event, const char * project_name);

6.3.4 Configs

@anchor{Configs}

Function: cca_config_t * cca_config_new (void)

Function: cca_config_t * cca_config_dup (const cca_config_t * config)

Function: cca_config_t * cca_config_new_with_key (const char * key)

Function: void cca_config_destroy (cca_config_t * config)

Function: const char * cca_config_get_key (const cca_config_t * config)

Function: const void * cca_config_get_value (const cca_config_t * config)

Function: size_t cca_config_get_value_size (const cca_config_t * config)

Function: void cca_config_set_key (cca_config_t * config, const char * key)

Function: void cca_config_set_value (cca_config_t * config, const void * value, size_t value_size)

6.3.4.1 Semi-typed configs

With these functions, no type checking is done; you can call cca_config_get_value_int with a config that was set using cca_config_set_value_float. The integer values are converted to and from network byte order as appropriate.

Function: uint32_t cca_config_get_value_int (const cca_config_t * config)

Function: float cca_config_get_value_float (const cca_config_t * config)

Function: double cca_config_get_value_double (const cca_config_t * config)

Function: const char * cca_config_get_value_string (const cca_config_t * config)

Function: void cca_config_set_value_int (cca_config_t * config, uint32_t value)

Function: void cca_config_set_value_float (cca_config_t * config, float value)

Function: void cca_config_set_value_double (cca_config_t * config, double value)

Function: void cca_config_set_value_string (cca_config_t * config, const char * value)

Go to the first, previous, next, last section, table of contents.