PtAppAddInput()

Add an input processing function

Synopsis:

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

Description:

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

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 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 will be 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 will get may have a different value:

In case of real processes under 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().
Under QNX 4, the rcvid is the same as the PID, and the PtGetRcvidPid() function is a macro that returns its argument:
```
#define PtGetRcvidPid( pid )   (pid)
```
In the case of Photon pulses, the rcvid argument won't necessarily have the same value as the pulse PID, either. In QNX 4, it's the PID of a proxy. In Neutrino, the rcvid matches the pulse PID on bits defined by _NOTIFY_DATA_MASK (see ionotify() in the 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, pid_t rcvid, 
               void *message, size_t size);

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

The data argument points to user data that's passed to the input entry function.

If the input function changes the display, it should call PtFlush() to make sure the display is updated.
If the input function returns a value other than Pt_CONTINUE, the function is removed from the input entry chain.

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:

// From /qnx4/phtk/apps/msgpass register_name.c
int
msg_handler( void *data, pid_t rcvid, 
             void *message, ushort_t size)
{
    struct msg_s 
    {
        unsigned type;
        unsigned color;
    } *msg;

    msg = ( struct msg_s * ) message;
    Reply( rcvid, "OK!", 4);
    switch(msg->type)
    {
        case 10:
            printf("got:: type = %d, color = %d, 
                size = %d\n",msg->type,
                msg->color, size);
            color = msg->color;
            color_chg( ABW_PtRegBut, NULL, NULL );
            PtFlush();
        break;
    }
    return( Pt_CONTINUE );
}
    

/****************************************************/
/*** The following function would normally        ***/
/*** be placed in an AppBuilder Init function.    ***/
/*** See Application menu, Startup Info. The      ***/
/*** function is set up here as a button callback ***/
/*** to clarify the sample's operation.           ***/
/****************************************************/
int
register_name( PtWidget_t *widget, void *data, 
               PtCallbackInfo_t *cbinfo )
{
    PtArg_t args[5];
    PtInputId_t *ipid;
    
    static nid_t name = -1;
    if ( -1 == name )
    {
        name = qnx_name_attach( 0, "Photon_App" );
        if( name == -1 )
            return( Pt_CONTINUE );
    }
    PtSetArg( &args[0], Pt_ARG_TEXT_STRING, 
              "Registered!", 0);
    PtSetResources( ABW_PtRegBut, 1, &args );

    ipid = PtAppAddInput( NULL, 0, msg_handler, NULL );
    return( Pt_CONTINUE );
    //added to illustrate removal of input routine....
    PtAppRemoveInput( NULL, ipid );
}

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No