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

PhChannelAttach()

Create or use a Neutrino channel

Synopsis:

int PhChannelAttach( int channel,
                     int connection,
                     struct sigevent const *event );

Arguments:

channel: A channel ID, or 0 to create a new channel.
connection: A connection ID, or -1 to create a new connection.
event: argument describes how Photon is to notify your application. If your application is using the widget library, pass NULL. For more information, see sigevent and ionotify() in the QNX Neutrino Library Reference.

Description:

Use this function if you want the library to create a Neutrino channel or use one that you've already created.

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 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 channel ID, or -1 on error (errno is set).

Errors:

EBUSY: A channel is already attached and chid is nonzero and differs from the current channel ID, or connection isn't -1 and differs from the currently used connection.
EINVAL: The channel argument is 0, but connection isn't -1.
Other values: ChannelCreate() or ConnectAttach() failed.

Examples:

To create a channel and a connection:

PhChannelAttach( 0, -1, NULL )

To attach a channel chid and create a connection:

PhChannelAttach( chid, -1, NULL )

To attach channel chid and connection coid:

PhChannelAttach( chid, coid, NULL )

Here's a fully working code sample that illustrates the order of PhChannelAttach(), name_attach(), and PtAppAddInput():

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>
#include <sys/neutrino.h>
#include <sys/iomsg.h>
#include <sys/iofunc.h>
#include <sys/dispatch.h>
#include <Pt.h>

struct my_msg
{
  short type;
  char reply[50];
};

#define NON_PHOTON_PULSE _IO_MAX+4
#define MY_SERV "my_server_name"

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

int main( int argc, char **argv)
{
  name_attach_t *attach;
  PtWidget_t *window;

  if (PtInit(NULL) == -1)
    exit(EXIT_FAILURE);
  /* attach the name the client will use to find us */
  /* our channel will be in the attach structure */
  if ( (attach = name_attach( NULL, MY_SERV, 0 )) == NULL)
  {
    printf("server:failed to attach name, errno %d\n", errno );
    PtExit(EXIT_FAILURE);
  }
  PhChannelAttach (attach->chid, -1, NULL );
  PtAppAddInput( NULL, 0, &non_photon_msg_func, NULL );
  if ((window = PtCreateWidget(PtWindow, Pt_NO_PARENT, 0, NULL)) == NULL)
    PtExit(EXIT_FAILURE);
  PtRealizeWidget ( window);
  PtMainLoop ();
  return 0;
}

int non_photon_msg_func (void *data, int rcvid, void *message, size_t size)
{
  struct my_msg *msg = ( struct my_msg * ) message;
  printf ( "Recieved a non photon message\n");

  if ( msg->type == NON_PHOTON_PULSE )
  {
    printf("server: This message is to be handled by this input handler\n");
    /* deliver message to client that client requested */
    strcpy ( msg->reply, "I got your message" );
    MsgReply ( rcvid,EOK, (char *) msg->reply, sizeof ( msg->reply ));
    return ( Pt_HALT );
  }
  else
  {
    printf("server: This message isn't for this input handler\n");
    return ( Pt_CONTINUE );
  }
}

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No