PhAttach()

Open a communications channel

Synopsis:

struct _Ph_ctrl *
          PhAttach(
             char const *name,
             PhChannelParms_t const *parms );

Library:

ph

Description:

This function opens a communications channel to a Photon Manager. The channel becomes the current channel.

---

This is a low-level routine that you aren't likely to call directly. Both PtInit() and PtAppInit() invoke this function. Your application must call one of these functions or PhAttach() before it calls any other Photon functions. The application that calls PhAttach() must have the appropriate permissions to read from and write to the attached Photon server, or the call will fail.

---

A Photon channel contains:

• an FD that can be used to send QNX messages to Photon
• an optional channel that the Photon Manager can send Neutrino pulses to
• a draw buffer for graphics commands.

PhAttach() doesn't create a channel; if you need to create one, call PhChannelAttach().

The name argument contains the name registered by a Photon Manager. If you pass NULL, the function uses the PHOTON environment variable. If PHOTON isn't set, the function uses /dev/photon instead.

The parms argument lets you fine-tune the resources of the channel. Passing NULL to this argument gets the channel defaults:

• maximum queue size (max_q_entries) of 10 events
• no special flags on the channel.

If you don't pass NULL for parms, you should pass a pointer to a PhChannelParms_t structure, which contains at least:

unsigned long  max_q_entries;
unsigned long  flags;

where:

max_q_entries

The maximum number of queued events likely to be needed. The Photon Manager may override this value.

flags

Defined flags:

Ph_NO_HOLD

Don't block the client if it overflows another application's event queue.

Ph_DYNAMIC_BUFFER

If there's a pending Photon event that's larger than the client's event buffer, send an event that indicates how large the client's buffer needs to be to receive the entire event message. For more information, see PhEventNext(), PhEventRead(), and PhGetMsgSize().

---

If you attach communications channels to multiple Photon managers, you'll have to keep track of which regions belong to which manager.

---

Returns:

A pointer to a control structure.

Examples:

promiscuous_call( void )
{
     struct _Ph_ctrl *ph1, *ph2, *ph3;

     ph1 = PhAttach( NULL, NULL );
     if( ph1 )
          printf( "ph1 is the current channel to: "
             "the local Photon kernel\n" );
     ph2 = PhAttach( "/dev/photon", NULL );
     if( ph2 )
          printf( "ph2 is the current channel to: "
             "the local Photon kernel\n" );
     ph3 = PhAttach( "/net/darrin/dev/photon", NULL );
     if( ph3 )
          printf( "ph3 is the current channel to: "
             "the Photon kernel on node 83\n" );
     if( !ph1 | !ph2 | !ph3 )
     return( -1 );

     PhReattach( ph1 );
     printf( "ph1 is the current channel again\n" );
     PhDetach( ph1 );
     printf( "there is no current channel\n" );
     PhReattach( ph3 );
     printf( "ph3 is the current channel again\n" );
     PhDetach( ph2 );
     PhDetach( ph3 );
     printf( "all Photon channels closed\n" );
     return( 0 );
}

Classification:

Photon

See also:

PgSetDrawBufferSize(), PhChannelAttach(), PhDetach(), PhEventNext(), PhEventArm(), PhEventRead(), PhGetMsgSize(), PhReattach(), PtInit(), PtAppInit()