6.3 Event protocol

This section describes version 2.0 of the event protocol.

6.3.1 Normal clients

This section deals with normal clients (as opposed to Server interfaces.)

CCA_Client_Name

To server, non-NULL string

Set the client's user-visible name.

To server, NULL string

Request the client's user-visible name.

From server

This will only be sent in response to a CCA_Client_Name with a NULL string. The string will be NULL if the client has not set a user-visible name, and the name itself if it has.

CCA_Jack_Client_Name

To server, non-NULL string

Tell the server what name the client is connected to JACK with. Clients should only ever send one non-NULL CCA_Jack_Client_Name event. Note that you must send this event after calling jack_activate(); otherwise, the server will not be able to connect the client's ports.

To server, NULL string

Request the client name that the server thinks the client is connected to JACK with.

From server

This will only be sent in response to a CCA_Jack_Client_Name with a NULL string. The string will be NULL if the client has not set a JACK client name, and the client name itself if it has.

CCA_Alsa_Client_ID

To communicate ALSA client IDs within events, use the first character of a two character string of the form { id, '\0' } as the event string. A convenience function, cca_alsa_client_id, exists to do this for you (see cca_alsa_client_id.)

To server, non-NULL string

Tell the server what ID the client is connected to ALSA with. Clients should only ever send one non-NULL CCA_Alsa_Client_ID event.

To server, NULL string

Request the client ID that the server thinks the client is connected to ALSA with.

From server

This will only be sent in response to a CCA_Alsa_Client_ID with a NULL string. The string will be NULL if the client has not set an ALSA client ID, and a string containing the ALSA client ID as described above if it has.

CCA_Save_File

From server

Tell the client to save all its data to files within a specific directory. The event string will never be NULL and will contain the name of the directory in which the client should save its data. Clients must always send a CCA_Save_File event back to the server when they have finished saving their data. The client should not rely on the directory existing after it has sent its CCA_Save_File event back. It is valid behaviour for a client to save no files within the directory. Files should always be overwritten (ie, using the "w" flag with fopen(),) preferably without user confirmation if you care for their sanity.

From client

Tell the server that the client has finished saving its data within the directory it was told to. The string is ignored.

CCA_Restore_File

From server

Tell the client to load all its data from files within a specific directory. The event string will never be NULL and will contain the name of the directory from which the client should load its data. Clients must always send a CCA_Restore_File event back to the server when they have finished restoring their data. The client should not rely on the directory existing after it has sent its CCA_Restore_File event back.

From client

Tell the server that the client has finished restoring its data from within the directory it was told to. The string is ignored.

CCA_Save_Data_Set

From server

Tell the client to send all its configuration data to the server with a number of configs. The client must always send a CCA_Save_Data_Set event back to the server when it has finished sending its configs. The event string will always be NULL.

From client

Tell the server that the client has finished sending its configs to the server. The event string is ignored.

CCA_Restore_Data_Set

From server

Tell the client to immediately expect a stream of configs from the server. This event will only be sent if there are one or more configs to be sent. The event string will always be NULL. The client must always send a CCA_Restore_Data_Set back to the server when it has recieved all of its configs.

From client

Tell the server that the client has finished recieving its configs from the server. The event string is ignored.

CCA_Save

From client

Tell the server to save the project that the client is attached to.

From server

Never occurs.

CCA_Quit

From client

Tell the server to close all clients in the project that the client is attached to.

From server

The client should immediately quit without saving. No more events will be sent by the server and the client's connection will be terminated.

6.3.2 Server interfaces

Server interfaces are treated very differently to normal interfaces. Events from and to server interfaces are, for the most part, in order to describe and manipulate existing projects and clients. For this reason, the cca_event_t type has project and client_id properties which facilitate this. See Server interface events. The project property contains the name of the project.

A server interface should start up with the default assumption that there are no projects. Upon connection, the server will send appropriate events (CCA_Project_Add, CCA_Client_Add, CCA_Client_Name, etc) that describe the current state of the system. From then on, events will be sent to keep the interface up to date with the server's state.

CCA_Project_Add

From interface

Restore a project from an existing directory. The event string should contain the directory's name.

project

Ignored.

client_id

Ignored.

From server

A new project has been added. The event string will contain the project's name.

project

NULL

client_id

Undefined.

CCA_Project_Remove

From interface

Close an open project. All of the project's clients will be told to quit and the project will be removed from the server's project list.

project

The project to remove.

client_id

Ignored.

From server

A project has been removed.

project

The project that has been removed.

client_id

Undefined.

CCA_Project_Dir

From interface, non-NULL string

Move a project to a different directory. The directory name should be contained in the event's string.

project

The project to move.

client_id

Undefined.

From interface, NULL string

Request a project's directory.

project

The project whose directory is being requested.

client_id

Undefined.

From server

A declaration of the project's directory; either because it has been requested or because the project has been moved. The directory name is contained in the event's string.

project

The project whose directory is being declared.

client ID

Undefined.

CCA_Project_Name

From interface

Change a project's name. The new project name should be contained in the event's string.

project

The project name to change.

client_id

Undefined.

From server

A project's name has changed. The new project name is contained in the event's string.

project

The project name that has changed.

client ID

Undefined.

CCA_Client_Add

From interface

Should not occur

From server

A new client has been added.

project

The project that the new client has been added to.

client ID

The new client's ID.

CCA_Client_Name

From interface, non-NULL string

Should not occur.

From interface, NULL string

Request a client's name.

project

The client's project.

client ID

The client's ID.

From server

A declaration of a client's name; either because it has been requested or because the client set the name. The name is contained in the event's string.

project

The client's project.

client ID

The client's ID.

CCA_Jack_Client_Name

From interface, non-NULL string

Should not occur.

From interface, NULL string

Request a client's JACK client name.

project

The client's project.

client ID

The client's ID.

From server

A declaration of a client's JACK client name; either because it has been requested or because the client set the name. The client name is contained in the event's string.

project

The client's project.

client ID

The client's ID.

CCA_Alsa_Client_ID

From interface, non-NULL string

Should not occur.

From interface, NULL string

Request a client's ALSA client ID.

project

The client's project.

client ID

The client's LADCCA ID.

From server

A declaration of a client's ALSA client ID; either because it has been requested or because the client set the ID. The ALSA client ID is contained in the event's string, as desribed in Normal CCA_Alsa_Client_ID.

project

The client's project.

client ID

The client's LADCCA ID.

CCA_Percentage

This event exists to provide user feedback on the status of save operations and perhaps other operations in future. The server will first send a percentage of 0, then successive percentages up to and including 100. When the operation is complete, the server will send a percentage of 0 again.

From interface

Should not occur.

From server

The percentage of completion of the current operation. The percentage is sent as a string, derived from sprintfing an int.

project

The project whose operation is being described.

client ID

Undefined.

This document was generated on April, 22 2011 using texi2html 1.78.