Before you send messages to a device, you must open a processing path that goes through it. This is done by calling mlOpen(3dm) as follows:

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

where:

Think of a path as a logical device; a physical device (for example, a PCI card) may simultaneously support several such paths. A side effect of opening a path is that space is allocated for queues of messages from your application to the device and replies from the device back to your application. All of the messages sent to a queue share a common payload area and are required to observe a strictly ordered relationship. That is, if message A is sent before message B, then the reply to A must arrive before the reply to B.

Messages are arrays of parameters, where the last parameter is always ML_END. For example, set the image width to be 720 and the image height to be 480 as follows:

MLpv message[3];
message[0].param = ML_IMAGE_WIDTH_INT32;
message[0].value.int32 = 720;
message[1].param = ML_IMAGE_HEIGHT_INT32;
message[1].value.int32 = 480;
message[2].param = ML_END

In some cases, an application wishes to influence a device without first waiting for all previously enqueued messages to be processed. These cases are known as out-of-band messages. They are performed with the mlSetControls(3dm) or mlGetControls (3dm) calls.

Following is an example of how you can immediately get the width and height of an image:

MLpv message[3];
message[0].param = ML_IMAGE_WIDTH_INT32;
message[1].param = ML_IMAGE_HEIGHT_INT32;
message[2].param = ML_END
if( mlGetControls( somePath, message))
   handleError();
else
  printf("Image size is %d x %d\n",
          message[0].value.int32,
          message[1].value.int32);

where:

Out-of-band messages work well for simple sets and queries. They are blocking calls. If the call succeeds, the message has been successfully processed.

Out-of-band messages are appropriate for simple control changes, but they provide no buffering between your application and the device. For most applications, processing real-time data will require using a queuing communication model. ML supports this with the following calls:

For example, to send a controls message to a device input queue, use the following:

MLstatus mlSendControls( MLopenid openId, MLpv* message);

where:

Devices interpret messages in the order in which they are enqueued. Because of this, the time relationship is explicit between, for example, video buffers and changes in video modes.

---

Note: The mlSendControls and mlSendBuffers calls do not wait for a device to process the message. Rather, they copy it to the device input queue and then return.

---

When your application sends a message, it is copied into the send queue. The message is then split between a small fixed header on the input list and a larger, variable-sized space in the data area.

Sometimes, there is not enough space in the data area and/or send list for new messages. In that case, the return code indicates that the message was not enqueued. As a rule, a full input queue is not a problem -- it simply indicates that the application is generating messages faster than the device can process them.

For some devices, the system may use device-specific knowledge to best manage messaging transactions. For example, when you call mlSendBuffers, the system may copy the message exactly as described above, or it may send part or all of the message directly to the hardware. Regardless of what happens, the system always looks to your application as described here.

Each message you send is guaranteed to result in at least one reply message from the device, allowing you know when your message is interpreted and what is the result:

Some devices can send messages to advise your application of important events (for example, some video devices can notify you of every vertical retrace). However, no notification messages will be generated unless you explicitly request them.

The device processes messages as follows:

In general, your application must allow space in the message for any reply you expect to be returned.

---

Note: The device performs no memory allocation, but rather uses the memory allocated when the application enqueued the input message. This guarantees that there will never be any need for the device to block because it did not have enough space for the reply.

---

In some cases, an exception event occurs that requires the device to pass a message back to your application. Your application must explicitly ask for such events.

Possible exception events are:

If you ask for events, your application must read its receive queue frequently enough to prevent the device from running out of space for messages that you have asked it to enqueue. If the queue starts to fill up, then the device will enqueue an event message advising that it is stopping notification of exception events.

---

Note: The device never needs to allocate space in the data area for reply messages. It will automatically stop sending notifications of events if the output list starts to fill up. Space is reserved in the receive queue for a reply to every message your application enqueues. If there is insufficient space, attempts to send new messages will fail.

---

To receive a reply message from a device, use mlReceiveMessage (3dm) as follows:

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

where:

This call returns the earliest unread message sent from the device back to your application.

Devices do not begin to process enqueued messages until explicitly instructed to by an application with the mlBeginTransfer(3dm) call:

MLstatus mlBeginTransfer( MLopenid openId);

This call frees the device to begin processing enqueued messages. It also commands the device to begin generating exception events. Typically, an application will open a device, enqueue several buffers (priming the input queue), and then call mlBeginTransfer. In this way, it avoids the underflow that could otherwise occur if the application were swapped out immediately after enqueueing the first buffer to the device.

To stop a transfer, call mlEndTransfer(3dm):

MLstatus mlEndTransfer( mlopenid openId);

This causes the device to do the following:

When your application has finished using an open path, it may close it by using the following:

MLstatus mlClose( MLopenId openId);

This causes an implicit mlEndTransfer on any device with an active transfer. It then frees any resources used by the device. If you wish to have pending messages processed prior to closing a device, you must identify a message (perhaps by adding a piece of user data or by remembering its MSC number) and make sure it is the last thing you enqueue. When it appears on the output queue, you will know all messages have been processed. At that point, you can close the device.

For more information, see the mlClose (3dm) man page.