Command Messages are send from the controlling application to the player. Sending a message to the player is asynchronous. This means that when the function that sends the message returns, the message has been POSTED to the player's incoming message queue, but might not have processed it yet. When the player processes the message, it will send back an aknowledgement (positive or negative) to notify of the success or failure of the command (XA_MSG_NOTIFY_ACK, XA_MSG_NOTIFY_NACK).
See the section about Command Messages for a complete list of command messages.
As a result of a command message, or when an event occurs, the player will send back notification messages with other types of information. See the section about Notification Messages" for a complete list of notification messages.
Creates a new asynchronous player (starts a decoding thread or process).This call takes as a parameter a pointer to a platform specific argument block. On UNIX platforms, no argument is needed, so the caller should pass NULL. On Windows platform, the argument block can be used to pass the handle of a window that is to receive the notification messages. See section about the Windows Platform Specifics for more details regarding the argument block on Windows.
int player_new(void **control, void *args);
XA_Player::XA_Player(void *args);
control pointer to a (void*) pointer where the handle to the created player should be stored. args pointer to an argument block, or NULL if there are no arguments.
Returns XA_SUCCESS if the player has been created, or a negative error code if the call failed.
player.h
player_delete()
Deletes an instantiated asynchronous player object (and releases the resources allocated to it). The caller should send an exit message (XA_MSG_CMD_EXIT) to the player and wait for a notification that the player's thread or process has terminated (XA_MSG_NOTIFY_EXITED) before deleting a player.
int XA_EXPORT player_delete(void *control);
XA_Player::~XA_Player();
control pointer to an instantiated player (returned by player_new() or control_procedure_new().
Returns XA_SUCCESS if the player has been deleted, or a negative error code if the call failed.
player.h
player_new()
Sends a message to an asynchronous player object.
Sending is a message is asynchronous. This means that the function posts the message to the player's message queue, and return immediately. So it is possible that the function will return before the player has processed the message. The return value of this call only indicates if the message has been successfully posted, but does not indicate whether the command to be performed by the player upon receipt of this message has been successful.
After the player has received and processed the message, it will send back an positive acknowledge notification message (XA_MSG_NOTIFY_ACK), or a negative acknowledge notification message (XA_MSG_NOTIFY_NACK) with the error code explaining the reason of the failure.
This call takes a variable number of arguments (the arguments depend on the type of message being sent), so it has the standard C calling conventions (__cdecl under Windows).
int control_message_send(void *control, int code, ...);
control pointer to an instantiated player (returned by player_new() or control_procedure_new(). code the type of message to send (See section about messages for a list of message codes).
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send_0(), control_message_send_1_string(),control_message_send_1_int(), control_message_send_1_generic(), control_message_send_2_ints(), control_message_send_3_ints(), control_message_send_4_ints(), control_message_get(), control_message_wait()
Sends a message that requires no argument.
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_N(void *control, int code);
control pointer to an instantiated asynchronous player. code type of the message to send.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Sends a message that requires one argument of type 'pointer' (const void *).
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_P(void *control, int code, const void *ptr1);
control pointer to an instantiated asynchronous player. code type of the message to send. ptr1 a generic pointer.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Sends a message that requires one argument of type 'string' (const char *).
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_S(void *control, int code, const char *str1);
control pointer to an instantiated asynchronous player.@code: type of the message to send. str1 a NULL-terminated character string.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Sends a message that requires 2 arguments of type 'string' (const char *).
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_SI(void *control, int code, const char *str1, const char *str2);
control pointer to an instantiated asynchronous player.@code: type of the message to send. str1 a NULL-terminated character string. str2 a NULL-terminated character string.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Sends a message that requires 1 argument of type 'string' (const char *) and one argument of type 'integer'.
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_SI(void *control, int code, const char *str1, int int1);
control pointer to an instantiated asynchronous player.@code: type of the message to send. str1 a NULL-terminated character string. int1 integer argument.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Sends a message that requires one argument of type 'integer'.
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_1_generic(void *control, int code, void *arg);
control pointer to an instantiated asynchronous player. code type of the message to send. int1 integer argument.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Sends a message that requires 2 arguments of type 'integer'.
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_II(void *control, int code, int int1, int int2);
control pointer to an instantiated asynchronous player. code type of the message to send. int1 first integer argument. int2 second integer argument.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Sends a message that requires 3 arguments of type 'integer'.
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_III(void *control, int code, int int1, int int2, int int3);
control pointer to an instantiated asynchronous player. code type of the message to send. int1 first integer argument. int2 second integer argument. int3 third integer argument.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Sends a message that requires 4 arguments of type 'integer'.
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_IIII(void *control, int code, int int1, int int2, int int3, int int4);
control pointer to an instantiated asynchronous player. code type of the message to send. int1 first integer argument. int2 second integer argument. int3 third integer argument. int4 fourth integer argument.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Sends a message that requires 1 argument of type 'integer', one argument of type 'pointer' (const void *) and 1 argument of type 'integer'.
(only use this call when calling the library from a development language that cannot use functions with a variable number of arguments, other wise, use control_message_send()).
int XA_EXPORT control_message_send_IPI(void *control, int code, int int1, const void *ptr1, int int2);
control pointer to an instantiated asynchronous player. code type of the message to send. int1 first integer argument. ptr1 generic pointer argument. int2 second integer argument.
Returns XA_SUCCESS if the message has been posted to the player's message queue, or a negative error code if the call failed.
control.h
control_message_send()
Retrieves a message from the notification message queue. This function does not wait for a message, it returns immediately, even if no message is available.
int XA_EXPORT control_message_get(void *control, XA_Message *message);
control pointer to an instantiated asynchronous player. message pointer to an XA_Message structure where the retrieved message will be stored.
Returns 1 of a message was available, 0 if no message was available, or a negative error code if the call failed.
control.h
control_message_wait()
Wait for a message to be available on the notification message queue, and retrieves it. If no message is available, this function blocks until a message is received, or the timeout expires. If the timeout is set to XA_TIMEOUT_INFINITE, the timeout never expires, and the function will just wait for a message.
int XA_EXPORT control_message_wait(void *control, XA_Message *message, int timeout);
control pointer to an instantiated asynchronous player. message pointer to an XA_Message structure where the retrieved message will be stored. timeout number of microseconds to wait before giving up, or XA_TIMEOUT_INFINITE to wait indefinitely.
Returns XA_SUCCESS if a message has been received, XA_ERROR_TIMEOUT if the timeout expired before any message was received, or a negative error code if the call failed.
control.h
control_message_get()
Converts a message into a human-readable string describing the message and its parameters.
int XA_EXPORT control_message_sprint(char *string, XA_Message *message);
string string buffer where the message string should be stored. message pointer to an XA_Message structure containing the message.
Returns XA_SUCCESS if the call succeeded, or a negative error code if the call failed.
control.h