PhEventRead()

Provide asynchronous event notification

Synopsis:

int PhEventRead( int rcvid,
                 void *buffer,
                 unsigned size );

Arguments:

rcvid

The receive ID returned by MsgReceive() (see the QNX Neutrino Library Reference).

buffer

A pointer to the message received. If the message is a pulse telling you that there's a Photon event waiting, PhEventRead() stores the event in this buffer. This buffer must be large enough to hold a Photon event and its associated rectangles and data.

size

The size of the buffer, in bytes.

Library:

ph

Description:

This function provides an asynchronous event-notification mechanism. You'll find it useful for applications that need to interact with Photon but also need to collect Neutrino pulses or messages from other processes.

For synchronous event notification, see PhEventNext() and PhEventPeek().

---

The widget library calls PhEventRead() internally; if you call PhEventRead() in an application that uses widgets, you might get unexpected results. Use PtMainLoop() or PtProcessEvent() instead.

---

Typically, you call this function with the rcvid returned by MsgReceive() to see if the message received was a pulse sent by Photon.

If the message received is the application's event pulse, then:

• If the buffer is large enough for the event, PhEventRead() retrieves the event, stores it in the location pointed to by buffer, and rearms Photon. PhEventRead() returns Ph_EVENT_MSG.
• If the buffer is too small for the event, but you set Ph_DYNAMIC_BUFFER when you called PhAttach(), PhEventRead() stores a resize event in the buffer and returns Ph_RESIZE_MSG; see PhGetMsgSize().
• If the buffer is too small for the event, and you didn't set Ph_DYNAMIC_BUFFER when you called PhAttach(), PhEventRead() sets errno to EMSGSIZE and returns -1.

If the message isn't the application's event pulse, PhEventRead() returns 0.

Photon may close a region (for example, via the window manager) before you read the pending event. As a result, PhEventRead() may indicate that no event is pending even though you were notified otherwise. In this case, PhEventRead() returns -1 and sets errno to ENOMSG.

---

You must call PhAttach() and arm the event pulse by calling PhEventArm() before you call PhEventRead() for the first time.

---

Returns:

Ph_EVENT_MSG

Successful completion.

Ph_RESIZE_MSG

The Ph_DYNAMIC_BUFFER flag was set in PhAttach(), and there's a pending Photon event that's larger than the client's event buffer. This event that indicates how large the client's buffer needs to be to receive the entire event message.

0

A non-Photon message was available.

-1

An error occurred.

Examples:

This code fragment shows how you can use PhEventRead() with PhGetMsgSize() to maintain a dynamic event buffer. You need to define my_msg_struct, initialize(), and process_app_msg():

#include <stdlib.h>
#include <errno.h>
#include <sys/neutrino.h>
#include <Pt.h>

int initialize( void );
void process_app_msg( void * );

int main( int argc, char *argv[] )
{
   int rcvid, chid;
   void *msg;
   unsigned msg_size;

   if( initialize() == -1 )
       exit( EXIT_FAILURE );

   msg_size = sizeof (my_msg_struct);
   if ( !(msg = malloc( msg_size )))
   {
      errno = ENOMEM;
      return( EXIT_FAILURE ); 
   }

   PhEventArm();
   chid = PhChannelAttach( 0, -1, NULL );
    
   while( 1 ) {
      rcvid = MsgReceive( chid, msg, msg_size, NULL );

      switch( PhEventRead( rcvid, msg, msg_size)) {
         case Ph_EVENT_MSG:
            PtEventHandler( (PhEvent_t *)msg );
            break;

         case Ph_RESIZE_MSG:
            msg_size = PhGetMsgSize( (PhEvent_t *)msg );
            if( !( msg = realloc( msg, msg_size )))
            {
               errno = ENOMEM;
               return( EXIT_FAILURE ); 
            }
            break;

         case 0:
            process_app_msg( msg );
            break;
         case -1:
            perror( "PhEventRead failed" );
            break;
      }
   }
   return( EXIT_SUCCESS ); 
}

Classification:

Photon

See also:

PhAttach(), PhEvent_t, PhEventArm(), PhEventNext(), PhEventPeek(), PhGetMsgSize(), PtEventHandler()

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

MsgReceive() in the QNX Neutrino Library Reference