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 );

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:

If errno is ENOMSG, Photon had no messages enqueued to your application at the time you emitted the event.
If errno isn't ENOMSG, an error occurred.

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