1.5.4 Target Objects

A target object provides a way of identifying a particular entity that is maintained by a specific software module. In API function calls, the target object is specified by a pair of parameters, the target_type and target_ID:

target_type

Identifies the kind of software module and the entity that it maintains. For example, the target type GCTGT_GCLIB_CHAN represents the Global Call Library and a channel entity that it maintains.

target_ID

Identifies the specific target object, such as a line device ID (LDID), which is generated by Global Call at runtime.

Table 2 shows the combinations of physical or logical entities and software module entities that can make up a target type (target_type).

Table 2. Supported Target Types

Software Module	Entity
	System	Network Interface	Channel	CRN
GCLib	S	S	S	S
CCLib	S	S	S	S
Protocol	SV	SV	SV
Firmware		SV	SV
S = Supported SV = Supported with Variances, see the appropriate Global Call Technology User's Guide for more information.

The possible software modules include:

• GCLib
• CCLib
• Protocol
• Firmware

The possible entities include:

System

all physical boards

Network Interface

logical board or virtual board

Channel

time slot

CRN

call reference number

A target type (target_type) name is composed of the prefix, GCTGT, which stands for Global Call Target, a software module name, such as GCLIB, and an entity name, such as NETIF. For example, the target type GCTGT_GCLIB_NETIF, indicates that the desired target type is a network interface maintained by the Global Call library.

A target ID (target_ID) identifies the specific object that is located within the category defined by the target type (target_type). A target ID can be any of the following:

• line device ID (LDID)
• call reference number (CRN)
• Global Call library ID (GCGV_LIB)
• call control library ID (CCLib ID)
• protocol ID

The types and IDs for target objects are defined at the Global Call level. Table 3 shows the target types, as described in Table 2, with various target IDs to represent valid target objects.

Table 3. Target Types and Target IDs

Target Type	Target ID	Description
GCTGT_GCLIB_SYSTEM †	GCGV_LIB	Global Call library module target object.
GCTGT_CCLIB_SYSTEM †	CCLib ID	Call control library module target object.
GCTGT_PROTOCOL_SYSTEM †	Protocol ID	Protocol module target object.
GCTGT_GCLIB_NETIF	Global Call Line device ID	Network interface target object in Global Call Library module.
GCTGT_CCLIB_NETIF	Global Call Line device ID	Network interface target object in call control library module.
GCTGT_PROTOCOL_NETIF †	Global Call Line device ID	Network interface target object in protocol module.
GCTGT_FIRMWARE_NETIF	Global Call Line device ID	Network interface target object in firmware module.
GCTGT_GCLIB_CHAN	Global Call Line device ID	Channel target object in Global Call library module.
GCTGT_CCLIB_CHAN	Global Call Line device ID	Channel target object in call control library module.
GCTGT_PROTOCOL_CHAN	Global Call Line device ID	Channel of protocol module target object.
GCTGT_FIRMWARE_CHAN	Global Call Line device ID	Channel target object in firmware module.
GCTGT_GCLIB_CRN	Global Call CRN	CRN target object in Global Call library module.
GCTGT_CCLIB_CRN	Global Call CRN	CRN target object in call control library module.
† Target types that can only be used by functions issued in synchronous mode. If a function uses one of these target types in asynchronous mode, an error will be generated. The functions that can use these target types are gc_GetConfigData( ), gc_QueryConfigData( ), gc_SetConfigData( ), gc_ReqService( ), and gc_RespService( ).

Target Object Availability

Except for the GCTGT_GCLIB_SYSTEM target object, all target IDs are generated or assigned by the Global Call API when the target object is created (for physical targets) or loaded (for software targets). Table 4 shows when a target object becomes available and when it becomes unavailable, depending on the target type.

Table 4. Target Object Availability

Target Type	Target Object Available	Target Object Unavailable
GCTGT_GCLIB_SYSTEM GCTGT_CCLIB_SYSTEM	After gc_Start( )	After gc_Stop( )
GCTGT_PROTOCOL_SYSTEM	After first successful call to gc_OpenEx( )	After call to gc_Close( ) using the protocol specified in target_type
GCTGT_GCLIB_CRN GCTGT_CCLIB_CRN	After a call is created (gc_MakeCall( ) returns or GCEV_OFFERED is received)	After gc_ReleaseCallEx( )
GCTGT_GCLIB_NETIF GCTGT_CCLIB_NETIF GCTGT_PROTOCOL_NETIF GCTGT_FIRMWARE_NETIF GCTGT_GCLIB_CHAN GCTGT_CCLIB_CHAN GCTGT_PROTOCOL_CHAN GCTGT_FIRMWARE_CHAN	After gc_OpenEx( )	After gc_Close( )

Retrieving Target IDs

Before the Global Call application can retrieve, update, or query the configuration data of a target object, it should obtain the target ID as shown in Table 5.

Table 5. Obtaining Target IDs

Target ID	Procedure for Obtaining Target ID
GCGV_LIB	After the call control library has been successfully started (that is, after the gc_Start( ) function is called), the target object's CCLib ID can be obtained by calling the gc_CCLibNameToID( ) function.
Protocol ID	After the first successful call to gc_OpenEx( ), the protocol ID can be obtained by calling gc_QueryConfigData( ) in which: Query ID is GCQUERY_PROTOCOL_NAME_TO_ID source data is the protocol name destination data is the protocol ID
Global Call Line Device ID	After a line device is opened, the CCLib ID and protocol ID (if applicable) associated with this line device can be obtained by the gc_GetConfigData( ) function with the set ID and parameter ID as (GCSET_CCLIB_INFO, GCPARM_CCLIB_ID) and (GCSET_PROTOCOL, GCPARM_PROTOCOL_ID).
Global Call CRN	After a call target object is created, its target object ID (that is, the Global Call CRN) will be an output of the gc_MakeCall( ) function or provided by the metaevent associated with the GCEV_OFFERED event.

Click here to contact Telecom Support Resources