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

PtAppAddInput()

Add an input processing function

Synopsis:

PtInputId_t *PtAppAddInput(
                 PtAppContext_t app_context,
                 pid_t pid,
                 PtInputCallbackProc_t input_func,
                 void *data );

Library:

ph

Description:

This routine adds a function to a PtMainLoop() input-event processing chain.

The app_context argument is the address of the application context, a structure that manages all the data associated with this application. Specify NULL for app_context, so that the default context is used.

The input function is executed whenever the application receives a message from process pid. If pid is negative, it's the ID of a Photon pulse.

If you specify a pid of 0, the input function is called for every non-Photon event message that's received, but only if there's no input function that catches messages from the sending pid specifically.

The rcvid argument that the input function gets may have a different value:

• In case of real processes under QNX Neutrino, the input function gets the rcvid -- which is the value that you'll need for replying, just like the PID under QNX 4. To retrieve the ID of the process, use PtGetRcvidPid().
• In the case of Photon pulses, the rcvid argument won't necessarily have the same value as the pulse PID, either. The rcvid matches the pulse PID on bits defined by _NOTIFY_DATA_MASK (see ionotify() in the QNX Neutrino Library Reference), but the other bits will be taken from the Neutrino pulse or signal that was received.

The input_func argument points to the input function to be invoked. The function takes this form:

int (*input_func)(void *data, int rcvid,
               void *message, size_t size);

The arguments are:

data

A pointer to any extra data you want to pass to the input handler.

rcvid

The rcvid of the process that sent the message.

message

A pointer to the message sent.

size

The size of the message buffer. If the actual message is longer than the buffer, load the rest of the message by calling MsgRead().

If you application knows the maximum size of a message that can be possibly sent to it, you can use PtResizeEventMsg() to ensure that the buffer is large enough.

---

Receiving a large Photon event may make the buffer bigger than was established by PtResizeEventMsg().

---

You can declare the function to be of type PtInputCallbackProcF_t to take advantage of the compiler's type-checking.

If the input function changes the display, it should call PtFlush() to make sure the display is updated.

The input function must return one of the following:

Pt_CONTINUE

The input handler doesn't recognize the message. If there are other input handlers attached to the same process ID, they're called. If there are no input handlers attached specifically to this process ID, or if all input handlers attached specifically to this process ID return Pt_CONTINUE, the library looks for input handlers attached to pid 0. If all the input handlers return Pt_CONTINUE, the library replies to the message with an ENOSYS.

Pt_END

The message has been recognized and processed and the input handler needs to be removed from the list. No other input handlers are called for this message.

Pt_HALT

The message has been recognized and processed but the input handler needs to stay on the list. No other input handlers are called for this message.

name_attach() and PtAppAddInput()

PtAppAddInput() and name_attach() both try to create a channel with _NTO_CHF_COID_DISCONNECT and _NTO_CHF_DISCONNECT set (see the QNX Neutrino Library Reference). If your application calls both functions, you need to let Photon use the same channel as name_attach(). To do this, call these functions in this order:

• name_attach()
• PhChannelAttach()
• PtAppAddInput()

See the Examples section of PhChannelAttach() for a sample of code that illustrates the correct order.

If you want to create a separate channel for Photon, it doesn't matter whether you create it and give it to PhChannelAttach() before or after calling name_attach(). But keep in mind that since certain mechanisms in Photon library expect the Photon channel to have the two DISCONNECT flags, they might not work properly if it doesn't. One such mechanism is the detection of broken connections (see PtConnectionClientSetError() and PtConnectionServerSetError()) and anything that relies on it.

Returns:

A pointer to a PtInputId_t structure that uniquely identifies the specified input function for the given application context. If an error occurs, the function returns NULL.

Examples:

See the example given in "Photon pulses" in the Interprocess Communication chapter of the Photon Programmer's Guide

Classification:

Photon

See also:

PhChannelAttach(), PtMainLoop(), PtAppCreatePulse(), PtAppRemoveInput(), PtSetParentWidget(), PtResizeEventMsg()

Interprocess Communication chapter of the Photon Programmer's Guide

name_attach() in the QNX Neutrino Library Reference