Sharing client specific, custom data among all clients

Detailed Description

Purpose of this API is to allow arbitrary data of any type to be shared between JACK clients. Data which would be out of the scope of the JACK system itself. It is especially handy on sandboxed environments like iOS, where all apps have their own, private and isolated file system, which prevents data to be shared easily between individual, independent apps.

See also section "Publish client Icon" on article Getting Started for an important use case of this API part.

Typedefs
typedef void(*	JackCustomDataAppearanceCallback )(const char *client_name, const char *key, jack_custom_change_t change, void *arg)

Functions
int	jack_custom_publish_data (jack_client_t *client, const char *key, const void *data, size_t size) JACK_OPTIONAL_WEAK_EXPORT
int	jack_custom_get_data (jack_client_t *client, const char *client_name, const char *key, void **data, size_t *size) JACK_OPTIONAL_WEAK_EXPORT
const char **	jack_custom_get_keys (jack_client_t *client, const char *client_name) JACK_OPTIONAL_WEAK_EXPORT
int	jack_custom_unpublish_data (jack_client_t *client, const char *key) JACK_OPTIONAL_WEAK_EXPORT
int	jack_custom_set_data_appearance_callback (jack_client_t *client, JackCustomDataAppearanceCallback callback, void *arg) JACK_OPTIONAL_WEAK_EXPORT

Typedef Documentation

typedef void(* JackCustomDataAppearanceCallback)(const char *client_name, const char *key, jack_custom_change_t change, void *arg)

Prototype of a client supplied function that is called when any custom data of foreign JACK clients appear, were replaced or removed. A client may implement such a callback to efficiently react on clients publishing and unpublishing any custom data.

Parameters

client_name	- name of the foreign JACK client which modified the data
key	- name of the new, replaced or removed custom data within the name space of the foreign client
change	- 0 = removed (unpublished), 1 = added (published), 2 = replaced
arg	- client specific structure, supplied when callback was registered

Definition at line 62 of file custom.h.

Function Documentation

int jack_custom_publish_data	(	jack_client_t *	client,
		const char *	key,
		const void *	data,
		size_t	size
	)

Makes the passed data publicly available for every JACK client to be read. The passed data will be copied into the JACK server process and kept in RAM by the server for the life-time of the calling client. The data will be available to be read by any JACK client under the given name (given by key). Every JACK client has its own name space for custom data. Since the data is copied by the server, the calling client may i.e. free the data from its memory immediately after this call. As soon as the client was closed, all custom data created by him will be unpublished automatically. In case some custom data with name key already exists in the client's name space, it will simply be replaced. It is also valid to pass a NULL pointer for data, to publish some "empty" data. The latter might be used as kind of flag variables.

Parameters

client	- handle of the calling JACK client
key	- some name under which the custom data shall be publicly visible
data	- pointer to the data that shall be published (copied immediately, may be NULL)
size	- size of the custom data in bytes

Returns

0 on success

int jack_custom_get_data	(	jack_client_t *	client,
		const char *	client_name,
		const char *	key,
		void **	data,
		size_t *	size
	)

Retrieve the custom data named by key from client given by client_name. The data returned by this function is a copy, so it can be modified by the caller of this function, without the original data to be modified in any way. Since every JACK client has its own name space for custom data, the actual unique ID of a specific custom data is identified by the combination of client_name and key.

The caller is responsible for calling jack_free() on any non-NULL returned data at a later point.

Parameters

client	- handle of the calling JACK client
client_name	- client with which the custom data is associated with
key	- name of the custom data
data	- will be set to a copy of the custom data, will be set to NULL if sought custom data is empty or does not exist (you may pass a NULL pointer for just checking by return value whether the sought data exists at all)
size	- optional pointer which will be set to the size of the custom data (in bytes), NULL can be passed if irrelevant

Returns

0 on success, non-zero if client or data do not exist

const char** jack_custom_get_keys	(	jack_client_t *	client,
		const char *	client_name
	)

Allows to lookup all custom data currently published by the foreign JACK client given by client_name. The caller will get a NULL-terminated list of all data object names of the foreign JACK client reflected by client_name. The caller may then pass one of the returned names to jack_custom_get_data() to get the actual custom data.

The caller is responsible for calling jack_free() on any non-NULL returned result value !

Parameters

client	- handle of the calling JACK client
client_name	- name of the foreign JACK client whose custom data list shall be retrieved

Returns

NULL-terminated name list

int jack_custom_unpublish_data	(	jack_client_t *	client,
		const char *	key
	)

If a client wants some of its custom data to explicitly disappear during the life-time of its JACK client, it may do so by calling this function.

Parameters

client	- handle of the calling JACK client
key	- name of the custom data to be removed

Returns

0 on success

int jack_custom_set_data_appearance_callback	(	jack_client_t *	client,
		JackCustomDataAppearanceCallback	callback,
		void *	arg
	)

Tell the JACK server to call callback whenever new custom data appears publicly or whenever some existing custom data was replaced or removed (unpublished). The callback is only called for custom data published by foreign JACK clients, not for any custom data published by the calling client itself (given by client).

All "notification events" are received in a seperated non RT thread, the code in the supplied function does not need to be suitable for real-time execution.

NOTE: this function cannot be called while the client is activated (after jack_activate has been called.)

Parameters

client	- handle of calling JACK client
callback	- client's callback implementation
arg	- arbitrary client specific data that shall be passed on each callback call

Returns

0 on success, otherwise a non-zero error code