AG ISDN Messaging API Developer's Reference Manual P/N 6272-12

isdnStartProtocol

isdnStartProtocol

Description

Starts up an ISDN protocol stack instance on a specified CTA context.

Prototype

DWORD isdnStartProtocol ( CTAHD ctahd,
unsigned protocol,
unsigned netoperator,
unsigned country,
unsigned partner_equip,
unsigned nai,
void *parms )

ctahd CTA context handle associated with a D channel, returned by ctaCreateContext or adiOpenPort.

protocol Configuration to start protocol instance in:

ISDN_PROTOCOL_Q931CC for ACU configuration.

ISDN_PROTOCOL_LAPD for LAPD configuration.

ISDN_PROTOCOL_CHANNELIZED for NCC configuration.

netoperator The network operator variant to start. Valid values for netoperator depend on the runfile, as follows:

Runfiles

Available Variants

systius.run, sysqius.run

ISDN_OPERATOR_ATT_5E9
ISDN_OPERATOR_NT_DMS
ISDN_OPERATOR_NI2
ISDN_OPERATOR_ATT_5E10

systieu.run, sysqieu.run

ISDN_OPERATOR_FT_VN6
ISDN_OPERATOR_ETSI

systias.run, sysqias.run

ISDN_OPERATOR_NTT
ISDN_OPERATOR_AUSTEL_1
ISDN_OPERATOR_HONG_KONG

Note that if you start the protocol stack on more than one NAI, netoperator must be the same for all NAIs.

country Country mode for the network operator variant to start in. Note that the behavior of a variant may change depending on the country specified.

Note also that if you start the protocol stack on more than one NAI, country must be the same for all NAIs.

The following are valid operator and country combinations:

Country

Available Variants

COUNTRY_AUS

ISDN_OPERATOR_AUSTEL_1
ISDN_OPERATOR_ETSI

COUNTRY_BEL

ISDN_OPERATOR_ETSI

COUNTRY_FRA

ISDN_OPERATOR_VN6

COUNTRY_GER

ISDN_OPERATOR_ETSI

COUNTRY_JPN

ISDN_OPERATOR_NTT

COUNTRY_SWE

ISDN_OPERATOR_ETSI

COUNTRY_UK

ISDN_OPERATOR_ETSI

COUNTRY_USA

ISDN_OPERATOR_ATT_5E9
ISDN_OPERATOR_NT_DMS
ISDN_OPERATOR_NI2
ISDN_OPERATOR_ATT_5E10

COUNTRY_EUR²

ISDN_OPERATOR_ETSI

nai The network access identifier (NAI) of the D channel to link to the protocol stack instance.

partner_equip
The type of equipment connected to the AG board:

If the AG board is...

And AG ISDN is to run in...

Set partner_equip to:

Connected to network

ACU configuration

EQUIPMENT_NT

LAPD configuration

EQUIPMENT_DCE

Acting as network

ACU configuration

EQUIPMENT_TE

LAPD configuration

EQUIPMENT_DTE

parms Pointer to the parameter block/structure required by the protocol:

For access to the parameters for AG ISDN in LAPD configuration, use ISDN_PROTOCOL_PARMS_LAPD.

For access to the parameters for AG ISDN in ACU configuration, use ISDN_PROTOCOL_PARMS_Q931CC.

For access to the parameters for AG ISDN in NCC configuration, use ISDN_PROTOCOL_PARMS_CHANNELIZED.

When parms is NULL, the default parameters for the protocol are used. The default parameters for each protocol enable the required service access points (SAPIs). For the ACU configuration, all the services are supported by default.

Note that the size field of the structure must contain the size of the structure. Refer to Appendix C: Parameters for more details on the contents of these parameter structures.

Return Values

SUCCESS

CTAERR_BAD_ARGUMENT
The protocol argument is invalid, or the size field of the parms data structure does not match the size of the structure corresponding to the protocol value.

CTAERR_INVALID_CTAHD
The CTA context handle is invalid.

CTAERR_INVALID_STATE
The CTA context is not open, or an ISDN protocol stack instance is being started on the same CTA context by a previous call, or an instance is already started on the CTA context, or the instance on the CTA context is in the process of stopping.

CTAERR_OUT_OF_MEMORY
Memory allocation failed on the host machine.

Events

ISDNEVN_START_PROTOCOL
The value field of the received event contains the completion status of the protocol starting operation, as follows:

SUCCESS

ISDNERR_BAD_NAI
The network access identifier (NAI) in the protocol parameters structure is not valid.

ISDNERR_INVALID_COUNTRY
The country specified is invalid for the network operator specified.

ISDNERR_INVALID_HDLC_CHAN
The HDLC controller number specified is invalid.

ISDNERR_INCOMPATIBLE_LIB
The ISDN library used is incompatible with the runfile.

ISDNERR_INVALID_OPERATOR
The network operator specified is not supported by the runfile.

ISDNERR_INVALID_PARTNER
partner_equip is not supported by the runfile.

ISDNERR_INVALID_PROTOCOL
The protocol argument is not supported by the runfile.

ISDNERR_NAI_IN_USE
Another thread or process has already started a protocol for the same network access identifier.

ISDNERR_PROTOCOL_CC_FAILURE
The call control parameters are invalid.

ISDNERR_PROTOCOL_DL_FAILURE
The data link parameters are invalid.

ISDNERR_PROTOCOL_NS_FAILURE
The network signaling parameters are invalid.

ISDNERR_PROTOCOL_PH_FAILURE
The physical layer parameters are invalid.

Details

Starts the specified protocol on the AG board that is associated with the specified ctahd.

The runfile is specified in the AG configuration file. For more information, see the AG ISDN Installation Manual and the AG Runtime Configuration and Developer's Manual.

If the parms pointer is NULL, the default values for the specified protocol are used. It is assumed that an HDLC data stream has been connected to the specified HDLC controller during initialization or by explicit switching calls. The parameters to the particular selected protocol are found in the parms data structure defined in isdnparm.h.

See Also

isdnStopProtocol

Example 1

mystartisdn (CTAHD ctahd) /* use defaults */
{
CTA_EVENT event;
DWORD ret;
char errortext[40];
unsigned nai = 0;

nai = 0;
ret = isdnStartProtocol( ctahd, ISDN_PROTOCOL_Q931CC,
ISDN_OPERATOR_NI2, COUNTRY_USA, ISDN_PARTNER_NT, nai, NULL);

if( ret != SUCCESS)
{
ctaGetText(ctahd, ret, errortext, 40);
printf("START_FAIL: %s\n", errortext );
return MY_ERROR_START_FAILED;
}
myWaitForEvent( ctahd, &event);
if( event.value != SUCCESS)
{
ctaGetText(ctahd, event.value, errortext, 40);
printf("START_FAIL: %s\n", errortext) );
return MY_ERROR_START_FAILED;
}
return SUCCESS ;
}

Example 2

mystartisdn (CTAHD ctahd) /* user-specified parms */
{
CTA_EVENT event;
DWORD ret;
char errortext[40];
unsigned nai;
unsigned j;
ISDN_PROTOCOL_PARMS_Q931CC parms;

memset( parms, 0, sizeof parms);
parms.size = sizeof(ISDN_PROTOCOL_PARMS_Q931CC);
parms.sapi_sig.enabled = 1;
parms.sapi_mdl.enabled = 1;
nai = 0;
j = 0;

parms.services_list[j++] = ACU_FAX_SERIVICE;
parms.services_list[j++] = ACU_VOICE_SERIVCE;
parms.services.list[j] = ACU_NO_SERVICE;
/*
** NOTE: The last service MUST contain ACU_NO_SERVICE
*/

ret = isdnStartProtocol( ctahd, ISDN_PROTOCOL_Q931CC,
ISDN_OPERATOR_NI2, COUNTRY_USA, ISDN_PARTNER_NT, nai, &parms);

if( ret != SUCCESS)
{
ctaGetText(ctahd, ret, errortext, 40);
printf("START_FAIL: %s\n", errortext );
return MY_ERROR_START_FAILED;
}
myWaitForEvent( ctahd, &event)
if( event.value != SUCCESS)
{
ctaGetText(ctahd, event.value, errortext, 40);
printf("START_FAIL: %s\n", errortext );
return MY_ERROR_START_FAILED;
}
return SUCCESS;
}

Natural MicroSystems, Inc.
100 Crossing Boulevard
Framingham, MA 01702

Contact Developer Support

2 Includes the following countries: Austria, Denmark, Finland, Greece, Iceland, Ireland, Italy, Liechtenstein, Luxembourg, Netherlands, Norway, Portugal, and Spain


*Description*	Starts up an ISDN protocol stack instance on a specified CTA context.
*Prototype*	DWORD isdnStartProtocol ( CTAHD *ctahd, unsigned protocol, unsigned netoperator, unsigned country, unsigned partner_equip, unsigned nai, void *parms* ) *ctahd* CTA context handle associated with a D channel, returned by ctaCreateContext or adiOpenPort. *protocol* Configuration to start protocol instance in: ISDN_PROTOCOL_Q931CC for ACU configuration. ISDN_PROTOCOL_LAPD for LAPD configuration. ISDN_PROTOCOL_CHANNELIZED for NCC configuration. *netoperator* The network operator variant to start. Valid values for *netoperator* depend on the runfile, as follows:
		Runfiles		Available Variants
		systius.run, sysqius.run		ISDN_OPERATOR_ATT_5E9 ISDN_OPERATOR_NT_DMS ISDN_OPERATOR_NI2 ISDN_OPERATOR_ATT_5E10
		systieu.run, sysqieu.run		ISDN_OPERATOR_FT_VN6 ISDN_OPERATOR_ETSI
		systias.run, sysqias.run		ISDN_OPERATOR_NTT ISDN_OPERATOR_AUSTEL_1 ISDN_OPERATOR_HONG_KONG
	Note that if you start the protocol stack on more than one NAI, netoperator must be the same for all NAIs. *country* Country mode for the network operator variant to start in. Note that the behavior of a variant may change depending on the country specified. Note also that if you start the protocol stack on more than one NAI, *country* must be the same for all NAIs. The following are valid operator and country combinations:
		Country	Available Variants
		COUNTRY_AUS	ISDN_OPERATOR_AUSTEL_1 ISDN_OPERATOR_ETSI
		COUNTRY_BEL	ISDN_OPERATOR_ETSI
		COUNTRY_FRA	ISDN_OPERATOR_VN6
		COUNTRY_GER	ISDN_OPERATOR_ETSI
		COUNTRY_JPN	ISDN_OPERATOR_NTT
		COUNTRY_SWE	ISDN_OPERATOR_ETSI
		COUNTRY_UK	ISDN_OPERATOR_ETSI
		COUNTRY_USA	ISDN_OPERATOR_ATT_5E9 ISDN_OPERATOR_NT_DMS ISDN_OPERATOR_NI2 ISDN_OPERATOR_ATT_5E10
		COUNTRY_EUR²	ISDN_OPERATOR_ETSI
	*nai* The network access identifier (NAI) of the D channel to link to the protocol stack instance. *partner_equip* The type of equipment connected to the AG board:
		If the AG board is...	And AG ISDN is to run in...		Set partner_equip to:
		Connected to network	ACU configuration		EQUIPMENT_NT
			LAPD configuration		EQUIPMENT_DCE
		Acting as network	ACU configuration		EQUIPMENT_TE
			LAPD configuration		EQUIPMENT_DTE
	*parms* Pointer to the parameter block/structure required by the protocol: For access to the parameters for AG ISDN in LAPD configuration, use ISDN_PROTOCOL_PARMS_LAPD. For access to the parameters for AG ISDN in ACU configuration, use ISDN_PROTOCOL_PARMS_Q931CC. For access to the parameters for AG ISDN in NCC configuration, use ISDN_PROTOCOL_PARMS_CHANNELIZED. When *parms* is NULL, the default parameters for the protocol are used. The default parameters for each protocol enable the required service access points (SAPIs). For the ACU configuration, all the services are supported by default. Note that the size field of the structure must contain the size of the structure. Refer to Appendix C: Parameters for more details on the contents of these parameter structures.
*Return Values*	SUCCESS CTAERR_BAD_ARGUMENT The *protocol* argument is invalid, or the *size* field of the *parms* data structure does not match the size of the structure corresponding to the protocol value. CTAERR_INVALID_CTAHD The CTA context handle is invalid. CTAERR_INVALID_STATE The CTA context is not open, or an ISDN protocol stack instance is being started on the same CTA context by a previous call, or an instance is already started on the CTA context, or the instance on the CTA context is in the process of stopping. CTAERR_OUT_OF_MEMORY Memory allocation failed on the host machine.
*Events*	ISDNEVN_START_PROTOCOL The value field of the received event contains the completion status of the protocol starting operation, as follows: SUCCESS ISDNERR_BAD_NAI The network access identifier (NAI) in the protocol parameters structure is not valid. ISDNERR_INVALID_COUNTRY The country specified is invalid for the network operator specified. ISDNERR_INVALID_HDLC_CHAN The HDLC controller number specified is invalid. ISDNERR_INCOMPATIBLE_LIB The ISDN library used is incompatible with the runfile. ISDNERR_INVALID_OPERATOR The network operator specified is not supported by the runfile. ISDNERR_INVALID_PARTNER partner_equip is not supported by the runfile. ISDNERR_INVALID_PROTOCOL The *protocol* argument is not supported by the runfile. ISDNERR_NAI_IN_USE Another thread or process has already started a protocol for the same network access identifier. ISDNERR_PROTOCOL_CC_FAILURE The call control parameters are invalid. ISDNERR_PROTOCOL_DL_FAILURE The data link parameters are invalid. ISDNERR_PROTOCOL_NS_FAILURE The network signaling parameters are invalid. ISDNERR_PROTOCOL_PH_FAILURE The physical layer parameters are invalid.
*Details*	Starts the specified *protocol* on the AG board that is associated with the specified *ctahd. The runfile is specified in the AG configuration file. For more information, see the AG ISDN Installation Manual* and the AG Runtime Configuration and Developer's Manual. If the *parms* pointer is NULL, the default values for the specified protocol are used. It is assumed that an HDLC data stream has been connected to the specified HDLC controller during initialization or by explicit switching calls. The parameters to the particular selected protocol are found in the *parms* data structure defined in isdnparm.h.
*See Also*	isdnStopProtocol
*Example 1*	mystartisdn (CTAHD ctahd) /* use defaults / { CTA_EVENT event; DWORD ret; char errortext[40]; unsigned nai = 0; nai = 0; ret = isdnStartProtocol*( ctahd, ISDN_PROTOCOL_Q931CC, ISDN_OPERATOR_NI2, COUNTRY_USA, ISDN_PARTNER_NT, nai, NULL); if( ret != SUCCESS) { ctaGetText(ctahd, ret, errortext, 40); printf("START_FAIL: %s\n", errortext ); return MY_ERROR_START_FAILED; } myWaitForEvent( ctahd, &event); if( event.value != SUCCESS) { ctaGetText(ctahd, event.value, errortext, 40); printf("START_FAIL: %s\n", errortext) ); return MY_ERROR_START_FAILED; } return SUCCESS ; }
*Example 2*	mystartisdn (CTAHD ctahd) /* user-specified parms / { CTA_EVENT event; DWORD ret; char errortext[40]; unsigned nai; unsigned j; ISDN_PROTOCOL_PARMS_Q931CC parms; memset( parms, 0, sizeof parms); parms.size = sizeof(ISDN_PROTOCOL_PARMS_Q931CC); parms.sapi_sig.enabled = 1; parms.sapi_mdl.enabled = 1; nai = 0; j = 0; parms.services_list[j++] = ACU_FAX_SERIVICE; parms.services_list[j++] = ACU_VOICE_SERIVCE; parms.services.list[j] = ACU_NO_SERVICE; / ** NOTE: The last service MUST contain ACU_NO_SERVICE / ret = isdnStartProtocol*( ctahd, ISDN_PROTOCOL_Q931CC, ISDN_OPERATOR_NI2, COUNTRY_USA, ISDN_PARTNER_NT, nai, &parms); if( ret != SUCCESS) { ctaGetText(ctahd, ret, errortext, 40); printf("START_FAIL: %s\n", errortext ); return MY_ERROR_START_FAILED; } myWaitForEvent( ctahd, &event) if( event.value != SUCCESS) { ctaGetText(ctahd, event.value, errortext, 40); printf("START_FAIL: %s\n", errortext ); return MY_ERROR_START_FAILED; } return SUCCESS; }