mme_connect()

Connect to a control context

Synopsis:

#include <mme/mme.h>

mme_hdl_t *mme_connect( const char *filename,
                        uint32_t flags );

Arguments:

filename
The full pathname to the multimedia engine device name, including the control context (for example, /dev/mme/control_context1).
flags
Flags that can be used to modify the behavior or the MME connection. See Flags below.

Library:

mme

Description:

The function mme_connect() connects the client application to the MME in a specified control context. It returns an mme_hdl_t object, which is used by the other mme_*() API functions.

To communicate to multiple control contexts you must use mme_connect() to connect at least once for each control context.

By default, the MME has one control context, but you can add more to the MME database, then connect to them. For more detailed information about control contexts, see Connecting to the MME in the MME Developer's Guide. For more information about the controlcontexts table, see the appendix MME Database Schema Reference.


Caution: Connections are not thread safe, so the client application must ensure that a connection handle isn't used by more than one thread at a time.

Device path

A control context's path maps directly to a resource manager device path. The device path, such as, for example, /dev/mme/frontseat, correlates directly to the control context with the same name; for example: “frontseat”. The device may be on the same machine that the MME is running on, or it can be located on another machine accessible to the MME.

Flags

The client application can use the flags variable to configure the behavior of the MME connection. Behavior is configured as follows:

O_SYNC is not set (default).
The MME returns to the client as soon as possible, and completes work after unblocking the client. It verifies the validity of as much of the request as possible before unblocking with a success code.
O_SYNC is set.
The MME completely executes requests before returning to the client.
O_NONBLOCK is not set (default).
The MME will block clients in a queue until it can service their requests.
O_NONBLOCK is set.
The MME will return an error with errno set to EAGAIN if executing a client request would result in the client being blocked.

Note: The blocking option is not honored by all MME functions. Synchronizations, for example, ignore the blocking flag and are always non-blocking. The main use for the non-blocking option is to give client application developers more control over the behavior of the MME playback functions.


Note: Functions that use the QDB many block on the QDB.

Events

None delivered.

Blocking and validation

This function fully validates all data; all arguments are checked before the call returns. The operation is complete when the call returns.

Returns:

An initialized mme_hdl_t, or NULL if an error occurred (errno is set).

Examples:

The example below shows how to connect your client application to the MME:

#include <mme/mme.h>
#include <qdb/qdb.h>

static char *mme_device_name = "/dev/mme/default";
static char *qdb_device_name = "/dev/qdb/mme";

...

// Establish a connection to the QDB
// (to obtain information about tracks and their information)
if( NULL == (qdb = qdb_connect( qdb_device_name, 0 )) ) {
    fprintf( stderr, "%s: ", qdb_device_name );
    perror( "qdb_connect()" );
    exit( EXIT_FAILURE );
}

// Establish a connection to the MME
// (to control what to play)
if( NULL == (mme = mme_connect( mme_device_name, 0 )) ) {
    fprintf( stderr, "%s: ", mme_device_name );
    perror( "mme_connect()" );
    exit( EXIT_FAILURE );
}

Note that in the sample code above the flags variable is set to 0. The MME will use its default settings, which are O_SYNC and O_NONBLOCK not set.

Classification:

QNX Neutrino

Safety:
Interrupt handler No
Signal handler No
Thread Yes

Caveats:

MME connections can be shared between threads in a process. However, they are not thread safe, so the client application must take precautions to ensure that the same connection handle isn't used by two threads at the same time.

See also:

mme_disconnect()