ML programs are composed of the following structure. Each of the functions are described later in this chapter (except where noted).

// Get list of available media devices:
mlGetCapabilities( systemId, &capabilities );

// Search the devices to find the desired jack, path, or transcoder to open (see Chapter 7):
mlGetCapabilities( deviceId, &capabilities );

// Query the jack, path or transcoder to discover allowable open options and parameters (see Chapter 7):
mlGetCapabilities( objectId, &capabilities );

// Query for individual parameter characteristics (see Chapter 7):
mlPvGetCapabilities( deviceId, paramId, &capabilities );

// Free memory associated with any of the above get-capabilities (see Chapter 7):
mlFreeCapabilities( capabilities );

// Open a logical connection to the desired object:
mlOpen( objectId, options, &openid );

// Get and set any necessary immediate controls:
mlGetControls( openId, controls );
mlSetControls( openId, controls );

// Send any synchronous controls:
mlSendControls( openId, controls );

// Send buffers to device: 
mlSendBuffers( opendId, buffers );

// Prepare for asynchronous processing by getting wait handle:
mlGetWaitHandle( openId, &waitHandle );

// Start the path or transcoder transfer:
mlBeginTransfer( openId );

// Perform synchronous transcoder work (if applicable):
mlXcodeWork( openId );

// Check on the status of the queue:
mlGetSendMessageCount( openId, &sendMsgCount );
mlGetReceiveMessageCount( openId, &receiveMsgCount );

// Process return messages:
mlReceiveMessage( openId, &status, &replyMsg );

// Find specific returned parameters:
mlPvFind( replyMsg, param );

//Repeat mlSendControls, mlSendBuffers, mlXcodeWork, etc. as required, then
// stop the transfer:
mlEndTransfer( openId );

// Close the logical connection:
mlClose( openId );

// Other useful functions:
mlGetVersion( &major, &minor );
mlGetSystemUST( systemId, &UST );
statusName = mlStatusName( status );
msgName = mlMessageName( messageType );

For audio and video paths and transcoders, the device transitions through well-known states, known as device states. These states are as follows:

In order to communicate with a jack, path, or transcoder, a connection must be opened. A physical device (such as a PCI card) may simultaneously support several such connections. These connections are done by calling mlOpen:

MLstatus mlOpen (const MLint64 objectId, MLpv* options,MLopenid* openid);

where:

These parameters are described in Table 3-7.

The status return for this function is one of the following:

Some controls on a logical connection are asynchronous in nature and do not affect an ongoing data transfer. These controls may be set in an out-of-band message using the mlSetControls operation:

MLstatus mlSetControls( MLopenid openid, MLpv* controls );

where:

This call blocks until the device has processed the message. To identify an invalid value specification, the device will set the length component of the erroneous MLpv to -1, otherwise the controls array will not be altered in any way and may be reused. The controls message is not enqueued on the send queue but instead is sent directly to the device. The device will attempt to process the message as soon as possible.

Enqueueing entails a copy operation, so the application is free to delete/alter the message array as soon as the call returns. Any error return value indicates the control change has not been enqueued and will thus have no effect.

---

Note: The mlSetControls call returns as soon as the control array has been processed. This does not mean that buffers have been affected by the parameter change. Rather, it means that the parameters have been validated and sent to the device (that is, in most cases this means that they reside in registers).

---

The status return is one of the following:

Control on a logical connection may be queried asynchronously to an ongoing transfer:

MLstatus mlGetControls (MLopenid openid, MLpv* controls);

where:

If mlGetControls is called before a control has been explicitly set, then generally the returned value is undefined. (Exceptions are noted in the definitions the controls; see Chapter 10, “Synchronization” or ML_UST in mlSynchronization (3dm).)

The status return for this function is one of the following:

Other controls on a logical connection are synchronous in nature and affect the processing of subsequent data buffers. These controls should be set in an in-band message using the mlSendControls operation:

MLstatus mlSendControls( MLopenid openid, MLpv* controls );

where:

The mlSendControls operation sends a message containing a list of control parameters to a previously-opened digital media device. These controls are enqueued on the send queue in sequence with any other messages to that device. Any control changes are thus guaranteed not to have any effect until all previously enqueued messages have been processed.

This call returns as soon as the control change has been enqueued to the device. It does not wait until the control change has actually taken effect.

All the control changes within a single message are considered to occur atomically. If any one control change in the message fails, then the entire message has no effect. A successful return does not guarantee that resources will be available to support the requested control change at the time it is processed by the device.

As each message is processed by the device, a reply message will be enqueued for return to the application. By examining that reply, the application may obtain the result of attempting to process the requested controls.

---

Note: A device may take an arbitrarily long time to generate a reply (it may, for example, wait for several messages before replying to the first). If an application requires an immediate response, consider using the mlSetControls operation instead.

---

Enqueueing entails a copy operation, so the application is free to delete/alter the message array as soon as the call returns. Any error return value indicates the control change has not been enqueued and will thus have no effect.

The status return is one of the following:

The return event may be one of the following:

The mlSendBuffers function sends a message containing a list of buffers to a previously-opened digital media device. These buffers are enqueued on the send queue in sequence with any other messages to that device. All the buffers within a single message are considered to apply to the same point in time. For example, a single buffers message could contain image, audio, HANC, and VANC buffers, each specified with its own buffer parameter in the buffers message. The mlSendBuffers operation is as follows:

MLstatus mlSendBuffers( MLopenid openid, MLpv* buffers );

where:

As each message is processed by the path, a reply message will be enqueued for return to the application. By examining that reply, the application may obtain the result of attempting to process the buffers.

A successful return value from mlSendBuffers guarantees only that the requested buffers have been enqueued to the device. Any error return value indicates the buffers have not been enqueued and will thus have no effect.

The memory for the buffers is designated by the pointer value, and is always owned by the application. However, after a buffer has been sent, it is on loan to the system and must not be touched by the application. After the buffer has been returned via mlReceiveMessage , then the application is again free to delete and/or modify it.

When sending a buffer to be output, the application must set the buffer length to indicate the number of valid bytes in the buffer. In this case, maxLength is ignored by the device. (It does not matter how much larger the buffer may be because the device will not read past the last valid byte.)

When sending a buffer to be filled (on input) the application must set the buffer maxLength to indicate the maximum number of bytes that may be written by the device to the buffer. As the device processes the buffer, it will write no more than the maxLength bytes and then set the returned length to indicate the last byte written. The maxLength is returned without change. It is acceptable to send the same buffer multiple times.

Enqueueing entails a copy operation, so the application is free to delete/alter the message array as soon as the call returns. Any error return value indicates that the buffer has not been enqueued and will thus have no effect.

The status return is one of the following:

The return event may be one of the following:

To obtain the control values on a logical connection that are synchronous via an in-band message, use the mlQueryControls operation:

MLstatus mlQueryControls( MLopenid openid, MLpv* controls );

where:

This call returns as soon as the message has been enqueued to the device. It does not wait until the control value is available.

As each message is processed by the device, a reply message will be enqueued for return to the application. By examining that reply, the application may obtain the result of attempting to process the requested controls.

---

Note: A device may take an arbitrarily long time to generate a reply (it may, for example, wait for several messages before replying to the first). If an application requires an immediate response, consider using the mlGetControls operation instead.

---

Enqueueing entails a copy operation, so the application is free to delete/alter the message array as soon as the call returns. Any error return value indicates the control change has not been enqueued and will thus have no effect.

The status return is one of the following:

The return event may be one of the following:

When processing a number of digital media streams asynchronously, there exists a need for the application to know when processing is required on each individual stream. The mlGetSendWaitHandle and mlGetReceiveWaitHandle functions are provided to facilitate this processing:

MLstatus mlGetSendWaitHandle( MLopenid openid, MLwaitable* WaitHandle );
MLstatus mlGetReceiveWaitHandle( MLopenid openid, MLwaitable* WaitHandle );

where:

The send queue handle is signaled whenever the device dequeues a message and the message count drops below a preset level (set by the parameter ML_OPEN_SEND_SIGNAL_COUNT specified when the object was opened). Thus, if the send queue is full, an application may wait on this handle for notification that space is available for additional messages.

The receive queue handle is signaled whenever the device enqueues a reply message. Thus, if the receive queue is empty, the application may wait on this handle for notification that additional reply messages are ready.

The returned handles were created when the device was opened and are automatically destroyed when the path is closed.

The status return is one of the following:

mlBeginTransfer starts the actual transferring of buffers to the logical media connection:

MLstatus mlBeginTransfer (MLopen id openid);

where openid is a previously-opened digital media object as returned by an mlOpen call.

This function begins a continuous transfer on the specified path or transcoder. It is not used on a logical connection to a jack. This call advises the device to begin processing buffers and returning messages to the application. As stated earlier, sending a buffer to a device that has not yet begun transfers will cause the send queue to stall until the transfers have started. Typically, applications will open a device, send several buffers, and then call mlBeginTransfer. This call returns as soon as the device has begun processing transfers. It does not block until the first buffer has been processed. It is an error to call this function more than once without an intervening call to mlEndTransfer.

---

Note: The delay between a call to mlBeginTransfer and the transfer of the first buffer is implementation-dependent. To begin sending data at a particular time, an application should start the transfer early (enqueueing blank buffers) and use the UST/MSC mechanism to synchronize the start of real data.

---

The status return is one of the following:

For software-only transcoders opened with the ML_XCODE_MODE_INT32 open option set to ML_XCODE_MODE_SYNCHRONOUS, this function allows an application to control exactly when (and in which thread) the processing for that codec takes place:

MLstatus mlXcodeWork( MLopenid openid );

where openid refers to a previously-opened digital media transcoder.

This function performs one unit of processing for the specified codec. The processing is done in the thread of the calling process and the call does not return until the processing is complete. For most codecs, a unit of work is the processing of a single buffer from the source queue and the writing of a single resulting buffer on the destination queue.

---

Note: The default behavior for all codecs is for processing to happen automatically as a side effect of enqueueing messages to the device. This function only applies to software codecs and only applies if they are opened with the ML_XCODE_MODE_SYNCHRONOUS open option.

---

The status return is one of the following:

During the processing of messages, it is sometimes necessary to inquire about the current capacity (fullness) of the message queues. The following functions provide that capability:

MLstatus mlGetSendMessageCount ( MLopenid openid, MLint32* messageCount);
MLstatus mlGetReceiveMessageCount ( MLopenid openid, MLint32* messageCount );

where:

These functions return a count of the number of messages in the send or receive queues of a device:

The message counts are intended to aid load-balancing in sophisticated applications. They are not a reliable method for predicting UST/MSC pairs.

Some devices can begin processing one or more following messages before the first has been completed. Thus, the sum of the send and receive queue counts may be less than the difference between the number of messages that have enqueued and dequeued by the application. The time lag between a message being removed from the send queue and the time at which it affects data passing though a physical jack is implementation-dependent. The message counts are not a reliable method for timing or synchronizing media streams.

The status return is one of the following:

To obtain the results of previous digital media requests, use the mlReceiveMessage function:

MLstatus mlReceiveMessage( MLopenid openid, MLint32* messageType, MLpv *reply );

where:

This function reads the oldest message from the receive queue. The receive queue holds reply messages sent from a digital media device back to an application.

Messages on the receive queue may be the result of the following:

Each message sent with an mlSendBuffers or mlSendControls generates a single reply message with messageType. This indicates whether or not the message was processed successfully and a pointer to a list of parameters holding the reply.

The contents of the reply array are guaranteed to remain valid until the next call to mlReceiveMessage. It is acceptable for an application to modify the reply and then send it to the same or to another device by calling mlSendControls or mlSendBuffers.

On some devices, triggering of the receive wait handle does not guarantee that a message is waiting on the receive queue. Thus applications must accept a status return of ML_STATUS_RECEIVE_QUEUE_EMPTY from an mlReceiveMessage function.

To invoke an orderly shutdown of a digital media stream, use the mlEndTransfer function:

mlEndTransfer( openId );

where openid is a previously-opened digital media object.

This function ends a continuous transfer on the specified path or transcoder. This call advises the device to stop processing buffers and aborts any remaining messages on its input queue. This is a blocking call. It does not return until transfers have stopped and any messages remaining on the device input queue have been aborted and flushed to the device output queue. Calling mlEndTransfer on a device that has not begun transfers is legal (it still causes the queue to be flushed). Any messages that are flushed will be marked to indicate they were aborted. Buffer messages are marked ML_BUFFERS_ABORTED; control messages are marked ML_CONTROLS_ABORTED.

The status return is one of the following:

After an application is finished with a digital media connection, it should terminate that connection. Use the mlClose function to close a previously opened digital media:

MLstatus mlClose(MLopenid openid);

where openid is the handle of the device to be closed.

When a digital media object is closed, all messages in the message queues of the device are discarded. The device handle openid becomes invalid; any subsequent attempt to use it to refer to the closed object will result in an error.

---

Note: An mlClose is implied if an application terminates (for any reason) before an mlClose function is called.

---

mlClose returns ML_STATUS_INVALID_ID if openid is invalid. Otherwise it returns ML_STATUS_NO_ERROR after the device has been closed and associated resources have been freed.

The pipes opened as a side-effect of opening a transcoder are also closed as a side-effect of closing a transcoder. Pipes should not be closed explicitly.

This section describes the following:

MLpv* mlPvFind( MLpv* msg, MLint64 param );

Get Version

The following function obtains the version number for the ML library:

MLstatus mlGetVersion( MLint32* majorVersion, MLint32* minorVersion );

where:

• majorVersion is the first digit in the major version

• minorVersion is the first digit in the minor version

For example, the 1.0 release will have a major number of 1 and a minor number of 0. Changes in major numbers indicate a potential incompatibility, while changes in minor numbers indicate small backward-compatible enhancements. Within a particular major version, all the minor version numbers will start at 0 and increase monotonically.

---

Note: This is the version number of the ML core library. The version numbers for device-dependent modules are available in the capabilities list for each physical device.

---

The status return is one of the following:

ML_STATUS_INVALID_ARGUMENT
	At least one of the pointers passed in is invalid
ML_STATUS_NO_ERROR
	The version numbers were obtained successfully

const char *mlStatusName( MLstatus status );

const char *mlMessageName( MLint32 messageType );

MLstatus  mlPvValueToString(MLint64 objectId, MLpv* pv, char* buffer, MLint32* bufferSize);
MLstatus  mlPvParamToString(MLint64 objectId, MLpv* pv,char* buffer, MLint32* bufferSize);
MLstatus  mlPvToString(MLint64 objectId, MLpv* pv, 	char* buffer, MLint32* bufferSize);
MLstatus  mlPvValueFromString(MLint64 objectId, const char* buffer,MLint32* bufferSize, 
                              MLpv* pv, MLbyte* arrayData, MLint32 arraySize);
MLstatus  mlPvParamFromString(MLint64 objectId, const char* buffer, MLint32* size, MLpv* pv);
MLstatus  mlPvFromString(MLint64 objectId, const char* buffer, MLint32* bufferSize, MLpv* pv,
                         MLbyte* arrayData, MLint32 arraySize);

The following example prints the interpretation of a video timing parameter by a previously-opened video path. The calls could fail if that path did not accept the particular timing value we have chosen here. Because the interpretation is coming from the device, this example will work for device-specific parameters.

char buffer[200]; 
MLpv control;

  control.param = ML_VIDEO_TIMING_INT32;
  control.value = ML_TIMING_1125_1920x1080_5994i;

  mlPvParamToString(someOpenPath, &control, buffer, sizeof(buffer)); 
  printf("control.param is %s\n", buffer); 
  mlPvValueToString(someOpenPath, &control, buffer, sizeof(buffer)); 
  printf("control.value is %s\n", buffer); 
  mlPvToString(someOpenPath, &control, buffer, sizeof(buffer));