PhAttach()

Open a communications channel

Synopsis:

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

Description:

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

The application must call the PhAttach() function before it calls any other Photon functions. Both PtInit() and PtAppInit() invoke this function.

A Photon channel contains:

an FD that can be used to send QNX messages to Photon
an optional proxy that can be triggered by the Photon Manager
a draw buffer for graphics commands

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:

channel attached to a proxy (to be used for asynchronous events)
maximum queue size (max_q_entries) of 10 events
no special flags on the channel

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

mpid_t   proxy;
unsigned long  max_q_entries;
unsigned long  flags;

where:

proxy

Your own proxy instead of the one that the channel would otherwise obtain. This member is valid only if you set the Ph_NO_PROXY bit in flags.

max_q_entries

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

flags

Defined flags:

Ph_NO_PROXY: Don't allow the channel to obtain a proxy unless the proxy member of PhChannelParms_t contains a proxy. This flag prevents the PhEventArm()/PhEventRead() combination from working. You should find this flag useful when proxies are a limited resource.
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( "//83/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

Safety:
Interrupt handler	No
Signal handler	No
Thread	No