Global Call API for HMP on Windows Programming Guide — August 2006 95
Call Control
The gc_Extension( ) function can also be used to transmit information to the remote endpoint. In
this case, while the application at the local end point receives a GCEV_EXTENSIONCMPLT, the
application at the remote end point will receive an unsolicited GCEV_EXTENSION notification
event from the network with the transmitted information. The EXTENSIONEVTBLK structure
contains the transmitted information and is referenced via the extevtdatap pointer in the
METAEVENT structure associated with the GCEV_EXTENSION event.
The application at the local end point may also receive an unsolicited GCEV_EXTENSION event
with information from the network.
It is important to note that the EXTENSIONEVTBLK structure referenced in the
GCEV_EXTENSION event has a persistence only until the next call of gc_GetMetaEvent(). In
other words, any information contained or referenced in the associated EXTENSIONEVTBLK
structure must be either processed or copied in the application, or risk having the memory space
containing the actual information lost on the next gc_GetMetaEvent( ) call.
7.4.3 Technology-Specific User Information
The gc_GetUserInfo( ) (E1, T1 and ISDN technologies only) and gc_SetUserInfo( ) (all
technologies) functions permits the application to retrieve and configure user information for the
specified line device that is transmitted to or received from the remote side. The actual content and
format of the user information is technology- or protocol-specific, or both. Refer to the associated
technology’s Global Call Technology Guide for details on the format of the user information
supported and the proper usage of the gc_GetUserInfo( ) and gc_SetUserInfo( ) functions.
One typical application of the gc_SetUserInfo() and gc_GetUserInfo( ) functions is on an ISDN
platform where it is desired to transmit and receive user-to-user information elements in each
incoming and outgoing message.
In the case of gc_SetUserInfo(), u ser information is transmitted to the remote side embedded in a
protocol-specific message. The duration flag is used to specify the persistence of the information.
Using the duration flag, the user information may be specified to persist as long as the current or
next call, or for all calls (including the current call). When the duration is specified to be all calls on
the specified line device, the user information is valid and utilized for all calls until the device is
eventually closed via gc_Close().
In the case of gc_GetUserInfo( ), the user information is retrieved from an already received
protocol-specific message that has been received from the remote side. Note that the user
information parameters returned from the call control library in the GC_PARM_BLK buffer must
be processed or copied prior to the next Global Call function call. The reason for this is that the
GC_PARM_BLK buffer will be deallocated within Global Call in a subsequent function call.