isdnStartProtocol

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

Prototype

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

Argument

Description

ctahd

Context handle associated with a D channel returned by ctaCreateContext.

protocol

Stack mode to start protocol instance in:

  • ISDN_PROTOCOL_Q931CC for ACU stack mode.

  • ISDN_PROTOCOL_LAPD for LAPD stack mode.

  • ISDN_PROTOCOL_CHANNELIZED for channelized stack mode.

netoperator

Network operator variant to start. Refer to Valid netoperator and country combinations.

country

Country mode in which the network operator variant starts. A variant's behavior can change depending on the country specified. Refer to Valid netoperator and country combinations.

country must be the same for all NAIs on a single board.

partner_equip

Type of equipment connected to the board. Refer to partner_equip settings.

nai

Network access identifier (NAI) of the D channel to link to the protocol stack instance.

parms

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

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 stack mode, all the services are supported by default.

The size field of the structure must contain the size of the structure. Refer to Overview of API data structures for details on the contents of these parameter structures.

Valid netoperator and country combinations

The following table lists the valid netoperator and country combinations:

netoperator value

Country value

Country

ISDN_OPERATOR_ATT_4ESS

ISDN_OPERATOR_ATT_5E10

ISDN_OPERATOR_NT_DMS

ISDN_OPERATOR_NT_DMS250

ISDN_OPERATOR_NI2

COUNTRY_USA

USA

ISDN_OPERATOR_FT_VN6

COUNTRY_FRA

France

ISDN_OPERATOR_AUSTEL_1

COUNTRY_AUS

Australia

ISDN_OPERATOR_ETSI

COUNTRY_AUS, COUNTRY_BEL, COUNTRY_GER, COUNTRY_SWE, COUNTRY_SGP, COUNTRY_GBR, COUNTRY_CHINA, COUNTRY_EUR

Australia, Belgium, Germany, Sweden, Singapore, Great Britain, and China.

COUNTRY_EUR includes the following countries: Austria, Belgium, Denmark, Finland, Germany, Greece, Iceland, Ireland, Italy, Liechtenstein, Luxembourg, Netherlands, Norway, Portugal, Russia, Spain, Sweden, Switzerland, and the UK.

ISDN_OPERATOR_HONG_KONG

COUNTRY_HONG_KONG

Hong Kong

ISDN_OPERATOR_KOREA

COUNTRY_KOR

Korea

ISDN_OPERATOR_NTT

COUNTRY_JPN

Japan

ISDN_OPERATOR_TAIWAN

COUNTRY_TWN

Taiwan

ISDN_OPERATOR_ECMA_QSIG

NA

country is ignored if variant is QSIG.

ISDN_OPERATOR_DPNSS

COUNTRY_EUR

Europe

The following table shows the ISDN and DPNSS run module files for NMS boards:

Board

ISDN

DPNSS

AG (except for AG 2000-BRI boards)

isdngen.leo

dpnss.leo

CG 6565/C

c6565igen.dlm

c6565dpnss.dlm

CG 6060/C

c6060igen.dlm

c6060dpnss.dlm

For AG 2000-BRI boards, the following table shows the valid netoperator values and the corresponding run module file:

netoperator value

Variant

Run module file

ISDN_OPERATOR_ETSI

ETSI

brietsi.leo

ISDN_OPERATOR_NTT

NTT

brintt.leo

ISDN_OPERATOR_VN6

VN6

brivn6.leo

partner_equip settings

Refer to the following table when setting the partner_equip argument:

If board is...

And NMS ISDN is to run in...

Set partner_equip to:

Connected to network

ACU stack mode

EQUIPMENT_NT

Connected to network

LAPD stack mode

EQUIPMENT_DCE

Acting as a network

ACU stack mode

EQUIPMENT_TE

Acting as a network

LAPD stack mode

EQUIPMENT_DTE

NMS ISDN also supports DPNSS. For DPNSS, the designations TE and NT do not apply. For the DPNSS implementation, TE maps to PBX A and NT maps to PBX B. To run PBX A, the partner equipment designation is EQUIPMENT_NT.

By default, PBX A is assigned to side X and PBX B is assigned to side Y. Use the NS behavior bits to modify this setting.

Return values

Return value

Description

SUCCESS

 

CTAERR_BAD_ARGUMENT

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

Context handle is invalid.

CTAERR_INVALID_STATE

One of the following conditions exists:

  • The context is not open.

  • An ISDN protocol stack instance is being started on the same context by a previous call.

  • An instance is already started on the context.

  • An instance on the context is in the process of stopping.

CTAERR_OUT_OF_MEMORY

Memory allocation failed on the host machine.

ISDNERR_CHANNELIZED_ON_MULTIPLE_BOARDS

An NFAS group is defined including multiple boards, and an attempt was made to start the stack in channelized stack mode.

ISDNERR_PROTOCOL_NS_FAILURE

NFAS groups are configured, and an attempt was made to start the stack using a variant that does not support NFAS.

ISDNERR_RACE_STARTING_PROTOCOL

An attempt was made to restart the stack directly after stopping it, before it was completely stopped. The process of stopping the stack can take several seconds.

Events

Event name

Description

ISDNEVN_START_PROTOCOL

Value field of the received event contains the completion status of the protocol starting operation, as follows:

SUCCESS

ISDNERR_BAD_NAI

Network access identifier (NAI) in the protocol parameters structure is not valid. Or, if duplicate NAI values are configured, the NAI and NFAS group couple is not valid.

ISDNERR_INCOMPATIBLE_LIB

NMS ISDN library used is incompatible with the run module.

ISDNERR_INVALID_COUNTRY

Country specified is invalid for the network operator specified.

ISDNERR_INVALID_OPERATOR

Network operator specified is not supported by the run module.

ISDNERR_INVALID_PARTNER

partner_equip is not supported by the run module.

ISDNERR_INVALID_PROTOCOL

protocol argument is not supported by the run module.

ISDNERR_NAI_IN_USE

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

ISDNERR_PROTOCOL_CC_FAILURE

Call control parameters are invalid.

ISDNERR_PROTOCOL_DL_FAILURE

Data link parameters are invalid.

ISDNERR_PROTOCOL_NS_FAILURE

Network signaling parameters are invalid.

ISDNERR_PROTOCOL_PH_FAILURE

Physical layer parameters are invalid.

Details

This function starts the specified protocol on the board that is associated with the specified ctahd.

The run module is specified in the board keyword file. For information, refer to the NMS ISDN Installation Manual and the NMS OAM System User'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 was connected to the specified HDLC controller during initialization or by explicit switching calls. The parameters for the particular selected protocol are found in the parms data structure defined in isdnparm.h.

See also

isdnStopProtocol

Example 1

DWORD 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

DWORD 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);
nai = 0;
j   = 0;

parms.nfas_group = 0;
parms.services_list[j++] = ACU_FAX_SERVICE;
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;
}