Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

PhEventEmitmx()

Emit an event when the event-specific data isn't contiguous in memory

Synopsis:

int PhEventEmitmx( PhEvent_t const *event,
                   PhRect_t const *rects,
                   int mxparts,
                   iov_t *mx );

Library:

ph

Description:

This function provides an alternative to PhEventEmit(). You'll find it useful when the event-specific data isn't contiguous in memory.

PhEmitmx() does the same things as PhEventEmitmx() and provides a cleaner API.

The mx argument points to an array of iov_t entries, and mxparts contains the number of mx entries pointed to by mx. You should leave the first three entries of mx blank; these are filled in by the PhEventEmitmx() call. You're free to use the remaining entries to build a description of the data to be attached to the event. If event->data_len isn't 0, then the event data must be at least event->data_len bytes long.

The rects argument points to an array of PhRect_t structures that define the rectangles associated with the event. If event->num_rects isn't 0, then rects must point to an array of event->num_rects valid rectangles.

Returns:

0
Successful completion.
-1
An error occurred, or no further events are pending. Check the value of errno:

These return codes are useful for applications that spend most of their time emitting events and want to retrieve an event only if there's one pending for them.

Examples:

The following example emits a pointer press event. (A call to PhEventEmit() is just as efficient and slightly more convenient.)

#include <stdio.h>
#include <time.h>
#include <Ph.h>

int main( int argc, char *argv[] )
{
     PhEvent_t event = { 0 };
     PhRect_t rect;
     PhPointerEvent_t ptr_event;
     iov_t mx[4];

     if( NULL == PhAttach( NULL, NULL ) ) {
     
          fprintf( stderr,
                 "Could not attach a Photon channel.\n");
          exit( EXIT_FAILURE );
     }
     event.type = Ph_EV_BUT_PRESS;
     event.subtype = 0;
     event.emitter.rid = Ph_DEV_RID;
     event.flags = 0;
     event.num_rects = 1;
     event.data_len = sizeof( ptr_event );
     rect.ul.x = rect.lr.x = 100;
     rect.ul.y = rect.lr.y = 200;
     ptr_event.flags = 0;
     ptr_event.buttons = Ph_BUTTON_SELECT;
     SETIOV( &mx[3], &ptr_event, sizeof( ptr_event ) );
     PhEventEmitmx( &event, &rect, 4, mx );

     return EXIT_SUCCESS;
}

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PgFlush(), PhEmit(), PhEmitmx(), PhEvent_t, PhEventEmit(), PhPointerEvent_t, PhRect_t

"Emitting events" in the Events chapter of the Photon Programmer's Guide.

MsgSendv(), SETIOV() in the QNX Neutrino Library Reference