[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 Types and functions


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.1 Server interaction

Function: lash_client_t * lash_init (lash_args_t * args, const char * client_class, int client_flags, lash_protocol_t protocol)

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

The args argument must be obtained using lash_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:

LASH_Config_Data_Set

The client wishes to save its data use the LASH config system. See Configs and Event protocol.

LASH_Config_File

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

LASH_Server_Interface

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

LASH_No_Autoresume

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

LASH_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 Protocol versioning for information on how to contruct a lash_protocol_t variable.

Function: lash_args_t * lash_extract_args (int * argc, char *** argv)

Extract LASH-specific arguments from argc/argv for use in lash_init. This should be done before the client checks the arguments, obviously.

Function: const char * lash_get_server_name (lash_client_t * client)

Get the hostname of the server.

Function: unsigned int lash_get_pending_event_count (lash_client_t * client)

Get the number of pending events.

Function: lash_event_t * lash_get_event (lash_client_t * client)

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

Function: unsigned int lash_get_pending_config_count (lash_client_t * client)

Get the number of pending configs.

Function: lash_config_t * lash_get_config (lash_client_t * client)

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

Function: void lash_send_event (lash_client_t * client, lash_event_t * event)

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

Function: void lash_send_config (lash_client_t * client, lash_config_t * config)

Send some configuration data to the server. The config must be created using lash_config_new, lash_config_new_with_key or lash_config_dup. The library takes over ownership of the memory (including the key, etc) and it should not be freed by the client.

Macro: lash_enabled (client)

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

Function: int lash_server_connected (lash_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 lash_jack_client_name (lash_client_t * client, const char * name)

Tell the server the client's JACK client name. This is a convenience function that just sends a LASH_Jack_Client_Name event to the server. See Normal LASH_Jack_Client_Name.

Function: void lash_alsa_client_id (lash_client_t * client, unsigned char id);

Tell the server the client's ALSA client ID. This just is a convenience function that just sends a LASH_Alsa_Client_ID event to the server. See Normal LASH_Alsa_Client_ID.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.2 Protocol versioning

The event protocol (See section Event protocol,) is versioned with a major and minor component. The lash_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: LASH_PROTOCOL (major, minor)

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

Macro: LASH_PROTOCOL_GET_MAJOR (protocol)

Obtain the major component of a lash_protocol_t protocol version.

Macro: LASH_PROTOCOL_GET_MINOR (protocol)

Obtain the minor component of a lash_protocol_t protocol version.

Function: const char * lash_protocol_string (lash_protocol_t protocol)

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.3 Events

Function: lash_event_t * lash_event_new (void)
Function: lash_event_t * lash_event_new_with_type (enum LASH_Event_Type type)
Function: void lash_event_destroy (lash_event_t * event)
Function: enum LASH_Event_Type lash_event_get_type (const lash_event_t * event)
Function: const char * lash_event_get_string (const lash_event_t * event)
Function: void lash_event_set_type (lash_event_t * event, enum LASH_Event_Type type)
Function: void lash_event_set_string (lash_event_t * event, const char * string);

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.3.1 Server interface events

All events have a LASH 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 lash_event_get_client_id (const lash_event_t * event, uuid_t id)

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

Function: const char * lash_event_get_string (const lash_event_t * event)
Function: void lash_event_set_client_id (lash_event_t * event, enum uuid_t id)
Function: const char * lash_event_get_project (const lash_event_t * event)
Function: void lash_event_set_project (lash_event_t * event, const char * project_name);

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.4 Configs

Function: lash_config_t * lash_config_new (void)
Function: lash_config_t * lash_config_dup (const lash_config_t * config)
Function: lash_config_t * lash_config_new_with_key (const char * key)
Function: void lash_config_destroy (lash_config_t * config)
Function: const char * lash_config_get_key (const lash_config_t * config)
Function: const void * lash_config_get_value (const lash_config_t * config)
Function: size_t lash_config_get_value_size (const lash_config_t * config)
Function: void lash_config_set_key (lash_config_t * config, const char * key)
Function: void lash_config_set_value (lash_config_t * config, const void * value, size_t value_size)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.4.1 Semi-typed configs

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

Function: uint32_t lash_config_get_value_int (const lash_config_t * config)
Function: float lash_config_get_value_float (const lash_config_t * config)
Function: double lash_config_get_value_double (const lash_config_t * config)
Function: const char * lash_config_get_value_string (const lash_config_t * config)
Function: void lash_config_set_value_int (lash_config_t * config, uint32_t value)
Function: void lash_config_set_value_float (lash_config_t * config, float value)
Function: void lash_config_set_value_double (lash_config_t * config, double value)
Function: void lash_config_set_value_string (lash_config_t * config, const char * value)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated on July, 25 2006 using texi2html 1.76.