PtAppAddFd(), PtAppAddFdPri()

Install a file-descriptor function

Synopsis:

int PtAppAddFd( PtAppContext_t app, 
                int fd, 
                unsigned mode, 
                PtFdProc_t fun,
                void *data);

int PtAppAddFdPri( PtAppContext_t app,
                int fd, 
                unsigned mode,
                PtFdProc_t fun, 
                void *data,
                int priority):

Description:

These functions install an "FD function" that will inform the application about device events.

The app argument is the address of the application context, a structure that manages all the data associated with this application. For Photon 1.1x, this must be specified as NULL, so that the default context is used.

The mode argument defines what kind of conditions the application is interested in:

Pt_FD_READ

Data available for reading.

Pt_FD_WRITE

Buffer space available for writing.

Pt_FD_OBAND

Out-of-band data available.

These values correspond to conditions defined for the ionotify() or select() functions. You can OR two or all three values together. You can change the mode later by calling PtAppSetFdMode()

Multiple FD functions attached to the same file descriptor aren't supported. PtAppAddFd() fails with errno set to EBUSY if you try to attach another function to the same FD.

The fun argument defines the function to be called. This function should match the following prototype:

typedef int PtFdProcF_t( int fd, void *data, unsigned mode );
typedef PtFdProcF_t *PtFdProc_t;

The fd and data arguments will have the same value as the fd and data arguments to PtAppAddFd(). The mode argument will indicate which conditions were actually met.

If the fun function returns a value other than Pt_CONTINUE, it will be removed automatically from the list of fd functions.

There are other flags that you can add to the mode argument to PtAppAddFd(). They can be used for optimizing the performance by avoiding unnecessary messages. Note that these flags aren't necessarily implemented for both QNX 4 and Neutrino; if a flag isn't implemented, it's defined as zero.

Pt_FD_NOPOLL

Tells the library that you're not particularly interested in the value of the mode argument to your function. Under QNX 4, this may save one message to the resource manager per call to your function. In those cases, the mode argument to your function will have a value of Pt_FD_NOPOLL.

Pt_FD_DRAIN

When used together with Pt_FD_READ, tells the library that your function will drain the input completely. Under Neutrino, the _NOTIFY_ACTION_TRANARMC action will be used when possible. This will save one message to the resource manager per call to your function. Note that even if no input is pending when you call PtAppAddFd(), your function may be called soon with the mode argument set to zero. You should then make sure that the input queue is drained completely.

For PtAppAddFdPri(), the priority parameter specifies the priority of the Photon pulse that's created (see PtAppCreatePulse()).

Returns:

0

Success.

-1

An error occurred.

Classification:

Photon

See also:

PtAppCreatePulse(), PtAppRemoveFd(), PtAppSetFdMode()

"Other I/O mechanisms" in the Interprocess Communication and Lengthy Operations chapter of the Programmer's Guide