• 4.4.1. Registration
• 4.4.2. Getting Notification of Registration Status
• 4.4.3. Sending Nonstandard Registration Messages
• 4.4.4. Deregistration

4.4. Registration, Admission and Status (RAS) Information

In System Release 5.x with the NetTSC embedded stack, registration functionality was configurable by setting parameter values in the config.val file. Functionality was provided in stages as described below:

• A setting determined if working with RAS protocol was enabled or disabled
• If working with the RAS protocol was enabled, then another setting determined if automatic registration at initialization time was enabled or disabled.
• If automatic registration at initialization time was enabled, then other settings determined:
  • Whether working with multicast or unicast is required and the respective address
  • The terminal alias, supported prefixes and time-to-live information (optional)

In System Release 6.0 with the host-based stack, registration is achieved using the gc_ReqService( ) function. The following rules apply:

• The application must use a valid board device handle that was previously obtained using the gc_OpenEx( ) function, for example, gc_OpenEx(&boardDevice,":N_iptB1:P_IP",EV_ASYNC, NULL).
• The application must perform initial discovery and registration before handling any calls.
• When the application is registered and has active calls, any deregistration or switching to a different gatekeeper must be done when all line devices in the system are in the Idle state.

The gc_ReqService( ) function is used for both registration and deregistration and includes a GC_PARM_BLK that can be populated with parameters that determine the following:

• The operation to be performed (register or deregister)
• The sub-operation to be performed (set registration information, add to registration information, delete one component of registration information by value, delete all registeration information)
• Registration address information
• Any local aliases to be included in the registration (when the registration target is H.323 only)
• Any supported prefixes to be included in the registration (when the registration target is H.323 only)

4.4.1. Registration

The gc_ReqService( ) function is used for registration. Registration information is stored locally and can be retained or discarded when deregistering. IP registration address information is stored in the IP_REGISTER_ADDRESS structure that has the following definition:

    typedef struct  
    {  
        char    reg_client[IP_REG_CLIENT_ADDR_LENGTH];  
        char    reg_server[IP_REG_SERVER_ADDR_LENGTH];  
        int     time_to_live;  
        int     max_hops;  
    }IP_REGISTER_ADDRESS;

Each field has the following meaning:

• reg_client: 128 character local address of registering host
• reg_server: 64 character local address of gatekeeper
• time_to_live: unicast TTL in seconds
• max_hops: multicast TTL in seconds

Important defines in this context are:

    #define IP_REG_MULTICAST_DEFAULT_ADDR "0.0.0.0" /* default multicast 

                                                       registration address */  
    #define IP_REG_SERVER_ADDR_LENGTH   64    /* server address length in characters */  
    #define IP_REG_CLIENT_ADDR_LENGTH  128    /* client address length in characters */  
    

The following paragraphs contain code segments that demonstrate how to populate the GC_PARM_BLK with the parameters required for registration with a gatekeeper.

1. Including two mandatory parameters. The generic Global Call service request feature requires two mandatory parameters for all service requests including registration. The parameters can be included in the GC_PARM_BLK as follows:

      GC_PARM_BLKP pParmBlock = NULL;  
      int frc = GC_SUCCESS;  
        
      /****** Two (mandatory) elements that are not related directly to   
      the server-client negotiation ********/  
      frc = gc_util_insert_parm_val(&pParmBlock,  
                                    GCSET_SERVREQ,  
                                    PARM_REQTYPE,  
                                    sizeof(char),  
                                    IP_REQTYPE_REGISTRATION);  
        
      frc = gc_util_insert_parm_val(&pParmBlock,  
                                    GCSET_SERVREQ,  
                                    PARM_ACK,  
                                    sizeof(char),  
                                    1);

2. Since Global Call in System Release 6.0 supports both H.323 and SIP protocols, the protocol must be specified. This is achieved by including the following set ID and parameter ID in the GC_PARM_BLK:

      /******Setting the protocol target***********/

      frc = gc_util_insert_parm_val(&pParmBlock,

                                    IPSET_PROTOCOL,

                                    IPPARM_PROTOCOL_BITMASK,

                                    sizeof(char),

                                    IP_PROTOCOL_H323); /*can be H323, SIP or Both*/

3. The operation (registration) and the sub-operation (set registration information) can be specified by including the following set ID and parameter IDs in the GC_PARM_BLK:

      /****** Setting the operation to perform ***********/  
      frc = gc_util_insert_parm_val(&pParmBlock,  
                                    IPSET_REG_INFO,  
                                    IPPARM_OPERATION_REGISTER, /* can be Register  
                                                                  or Deregister */  
                                    sizeof(char),  
                                    IP_REG_SET_INFO);  /* can be other relevant  
                                                          "sub" operations */

4. Registration address information is specified by including the following set ID and parm ID in the GC_PARM_BLK:

      /****** Setting address information ***********/  
      IP_REGISTER_ADDRESS registerAddress;  
      strcpy(registerAddress.reg_server,"101.102.103.104"); /* set server address*/  
      strcpy(registerAddress.reg_client,"10.20.30.40");     /* set client (self)  
                                                               address */  
      registerAddress.max_hops = regMulticastHops;  
      registerAddress.time_to_live = regUnicastTTL;  
        
      frc = gc_util_insert_parm_ref(&pParmBlock,  
                                    IPSET_REG_INFO,  
                                    IPPARM_REG_ADDRESS,  
                                    (UINT8)sizeof(IP_REGISTER_ADDRESS),  
                                    &registerAddress);

5. An e-mail alias can be specified by including the following set ID and parameter ID in the GC_PARM_BLK. Other alias types can be included by using the parameter IDs: IPPARM_ADDRESS_DOT_NOTATION (for IP addresses), IPPARM_ADDRESS_H323_ID (for H.323 IDs), IPPARM_ADDRESS_PHONE (for phone numbers), IPPARM_ADDRESS_URL (for universal resource locators), and IPPARM_ADDRESS_TRANSPARENT (for unknown types).

      /**** Setting terminalAlias information  ****/  
      /**** With H.323 - may repeat this line with different aliases and   
              alias types ****/  
      /**** SIP does not allow the setting of this parm block ****/  
      frc = gc_util_insert_parm_ref(&pParmBlock,  
                                    IPSET_LOCAL_ALIAS,  
                                    (unsigned short)IPPARM_ADDRESS_EMAIL,  
                                    (UINT8)(strlen("someone@someplace.com")+1),  
                                     "someone@someplace.com");

6. A phone number supported prefix can be specified by including the following set ID and parameter ID in the GC_PARM_BLK. Other supported prefix types can be included by using the parameter IDs: IPPARM_ADDRESS_DOT_NOTATION (for IP addresses), IPPARM_ADDRESS_H323_ID (for H.323 IDs), IPPARM_ADDRESS_PHONE (for phone numbers), IPPARM_ADDRESS_URL (for universal resource locators), and IPPARM_ADDRESS_TRANSPARENT (for unknown types).

      /**** Setting supportedPrefixes information  ***********/  
      /**** With H.323 - may repeat this line with different supportedPrefixes and   
              supported prefix types ****/  
      /**** SIP does not allow the setting of this parm block ****/  
      frc = gc_util_insert_parm_ref(&pParmBlock,  
                                    IPSET_SUPPORTED_PREFIXES,  
                                    (unsigned short)IPPARM_ADDRESS_PHONE,  
                                    (UINT8)(strlen("011972")+1),  
                                    "011972");

7. Once the GC_PARM_BLK has been set up, the gc_ReqService( ) function can be used to send the request to the gatekeeper.

      /****** Send the request  ***********/  
          unsigned long   serviceID ;  
      int rc = gc_ReqService(GCTGT_CCLIB_NETIF,  
                             boarddev,  
                             &serviceID,  
                             pParmBlock,  
                             NULL,  
                             EV_ASYNC);  
        
      if (rc != GC_SUCCESS)  
      {  
          printf("failed in gc_ReqService\n");  
          return GC_ERROR;  
      }




4.4.2. Getting Notification of Registration Status

When using the Global Call API, getting notification of registration status is a two step process:

• Detecting a registration event on the board device
• Extracting the status from the GC_PARM_BLK associated with the event

The following code demonstrates how to detect the event on the board device.

int rasProcessEvent(METAEVENT *metaevt)  
{  
    long                type = sr_getevttype();  
    LINEDEV             device = sr_getevtdev();  
    EXTENSIONEVTBLK*    pextensionBlk = NULL;  
    GC_PARM_BLKP        gcParmBlk;  
    int                 rc;  
    printf("Got event [0x%x] for board device [%d]\n",type,device);  
    if(GCEV_SERVICERESP == metaevt->evttype)  
    {  
        pextensionBlk = (EXTENSIONEVTBLK*)(metaevt->extevtdatap);  
        if (NULL == pextensionBlk)  
        {  
            printf("rasProcessEvent: (NULL == pextensionBlk)\n");  
            return FUNCFAIL;  
        }
  
        gcParmBlk  = (&(pextensionBlk->parmblk));
  
        rc = getExtension(gcParmBlk);  
        if (FUNCSUCCESS != rc)  
        {  
            printf("rasProcessEvent: No InfoElement on Extension Buffer\n");  
            return FUNCFAIL;  
        }  
    }  
    return FUNCSUCCESS;  
}

The following code shows how to extract registration status (accepted or rejected) from the GC_PARM_BLK associated with the event.

int getExtension(GC_PARM_BLKP parm_blk)  
{  
    GC_PARM_DATA        *parmp = NULL;  
    static int xxx=0;  
    parmp = gc_util_next_parm(parm_blk,parmp);
  
    if (!parmp)  
    {  
        return FUNCFAIL;  
    }
  
    while (NULL != parmp)  
    {  
        xxx++;  
        printf("param # = %d\n",xxx);  
        switch (parmp->set_ID)  
        {  
            case IPSET_REG_INFO:  
                if  (IPPARM_REG_STATUS == parmp->parm_ID)  
                {  
                    int value = (*(int *)(parmp->value_buf));  
                    switch (value)  
                    {  
                        case IP_REG_CONFIRMED:  
                            switch (g_waitForCmplt)  
                            {  
                                case REGESTER:  
                                    printf("\tGot REG_STATUS - IP_REG_CONFIRMED for Regesteration\n");  
                                    break;  
                                case UNREGESTER:  
                                    printf("\tGot REG_STATUS - IP_REG_CONFIRMED for un regester\n");  
                                    ApplicationExit();  
                                    break;  
                                default:  
                                    break;  
                             }  
                        case IP_REG_REJECTED:  
                            switch (g_waitForCmplt)  
                            {  
                                case REGESTER:  
                                    printf("\tGot REG_STATUS - IP_REG_REJECTED for Regesteration\n");  
                                    break;  
                                case UNREGESTER:  
                                    printf("\tGot REG_STATUS - IP_REG_REJECTED for un regester\n");  
                                    break;  
                                default:  
                                    break;  
                             }  
                        default:  
                            break;  
                    }  
                }  
                break;  
            default:  
                printf("\tGot unknown extension setID %d\n",parmp->set_ID);  
                break;  
        }/* end switch (parmp->set_ID) */
  
        parmp = gc_util_next_parm(parm_blk,parmp);  
    }  
    return FUNCSUCCESS;  
}




4.4.3. Sending Nonstandard Registration Messages

Non-standard registration messages are sent to the gatekeeper using the gc_Extension( ) function with an extension ID (ext_ID) of IPEXTID_SENDMSG. A GC_PARM_BLK associated with the gc_Extension( ) function contains the required parameters and the message data. The following code demonstrates how to set up a GC_PARM_BLK and use the gc_Extension( ) function to send a nonstandard message to the gatekeeper.

int sendNonStandardRasMsg()  
{  
    GC_PARM_BLKP    gcParmBlk = NULL;  
    int frc;
  
    /******Setting the protocol target******/  
    frc = gc_util_insert_parm_val(&pParmBlock,  
                                  IPSET_PROTOCOL,  
                                  IPPARM_PROTOCOL_BITMASK,  
                                  sizeof(char),  
                                  IP_PROTOCOL_H323); /* can only be H323 target /*  
                                                     /* for this task */
  
    frc = gc_util_insert_parm_val(&gcParmBlk,  
                                  IPSET_MSG_REGISTRATION,  
                                  IPPARM_MSGTYPE,  
                                  sizeof(int),  
                                  IP_MSGTYPE_REG_NONSTD);
  
    frc = gc_util_insert_parm_ref(&gcParmBlk,  
                                  IPSET_NONSTANDARDDATA,  
                                  IPPARM_NONSTANDARDDATA_OBJID,  
                              (unsigned char)(strlen(Boards[1].RegData.NonStdObjID) +1),  
                                  (void*)Boards[1].RegData.NonStdObjID);
  
    frc = gc_util_insert_parm_ref(&gcParmBlk,  
                                  IPSET_NONSTANDARDDATA,  
                                  IPPARM_NONSTANDARDDATA_DATA,  
                                  (unsigned char)(strlen(Boards[1].RegData.NonStdCmd)+1),  
                                  (void*)(Boards[1].RegData.NonStdCmd) );
  
    if (gc_Extension(GCTGT_CCLIB_NETIF,  
                     Boards[1].device,  
                     IPEXTID_SENDMSG,  
                     gcParmBlk,  
                     NULL,  
                     EV_ASYNC)<0)  
    {  
        printf("gc_Extention failed");  
    }
  
    gc_util_delete_parm_blk(gcParmBlk);  
    return FUNCSUCCESS;  
}




4.4.4. Deregistration

Deregistration is achieved using the gc_ReqService( ) by specifying the IPSET-REG_INFO set ID and the IPPARM_OPERATION_DEREGISTER parameter ID in the GC_PARM_BLK associated with the gc_ReqService( ) function. In addition, the application can choose to keep the registration information that is stored locally or to discard it by setting the IPPARM_OPERATION_DEREGISTER parameter to a value of IP_REG_MAINTAIN_LOCAL_INFO (deregister but keep registration information locally) or IP_REG_DELETE_ALL (deregister and discard the registration information stored locally).

The following code example shows how to deregister from a gatekeeper and discard the registration information stored locally.

int unregister()  
{  
    GC_PARM_BLKP         pParmBlock = NULL;  
    unsigned long        serviceID = 1;  
    int                  rc;
  
    /******Setting the protocol target******/  
    rc = gc_util_insert_parm_val(&pParmBlock,  
                                 IPSET_PROTOCOL,  
                                 IPPARM_PROTOCOL_BITMASK,  
                                 sizeof(char),  
                                 IP_PROTOCOL_H323); /* can be H323 or SIP /*
  
    rc = gc_util_insert_parm_val(&pParmBlock,  
                                 IPSET_REG_INFO,  
                                 IPPARM_OPERATION_DEREGISTER,  
                                 sizeof(char),  
                                 IP_REG_DELETE_ALL);
  
    rc = gc_ReqService(GCTGT_CCLIB_NETIF,  
                       Boards[1].device,  
                       &serviceID,  
                       pParmBlock,  
                       NULL,  
                       EV_ASYNC);
  
    if ( GC_SUCCESS != rc)  
    {  
        printf("gc_ReqService failed while unregestering\n");  
        gc_util_delete_parm_blk(pParmBlock);  
        return FUNCFAIL;  
    }  
    g_waitForCmplt = UNREGESTER;  
    printf("Unregester request to the GK was sent ...\n");  
    printf("the application will not be able to make calls !!! so it will EXIT\n");  
    gc_util_delete_parm_blk(pParmBlock);  
    return FUNCSUCCESS;  
}

Click here to contact Telecom Support Resources