dx_gtextcallid( )

Description | Cautions | Example | Errors | See Also

Name:	int dx_gtextcallid (chdev, infotype, bufferp)
Inputs:	int chdev	Channel device handle
	int infotype	Message Type ID
	unsigned char *bufferp	Pointer to where to return the requested Caller ID message
Returns:	0 success
	-1 error return code
Includes:	srllib.h
	dxxxlib.h
Category:	Caller ID
Mode:	synchronous

Description

The dx_gtextcallid( ) function returns the requested Caller ID message by specifying the Message Type ID. The application can issue this function as many times as required to get the desired Caller ID messages (such as date and time, calling line subscriber name, reason why Caller ID is not available). The formatting and content of the Caller ID messages documented are based on published telecommunication standards. The actual formatting and content of the data returned depend on the implementation and level of service provided by the originating and destination Central Offices.

NOTE:

For CLASS and ACLIP, do not use Multiple Data Message Type IDs with Caller ID information in Single Data Message format.

This function has the following parameters:

Parameter	Description
chdev:	Channel device handle.
infotype:	The Message Type ID for the specific Caller ID information to receive. (Message Type IDs for CLASS, ACLIP, JCLIP and CLIP are listed on the following pages.)
bufferp:	Pointer to where to return the requested Caller ID message. All returns are NULL terminated.

Common Message Types

The following standard Message Types are available for:

• CLASS (Single Data Message)
• CLASS (Multiple Data Message)
• ACLIP (Single Data Message)
• ACLIP (Multiple Data Message)
• CLIP
• JCLIP

All returns are NULL terminated.

Table 9. Caller ID Common Message Types

Value	Definition/Returns
CLIDINFO_CMPLT	All Caller ID information as sent from the CO (maximum of 258 bytes; includes header and length byte at the beginning). Can produce EDX_CLIDINFO error.
CLIDINFO_GENERAL	Date and time (20 bytes - formatted with / and : characters; padded with spaces). Caller phone number or reason for absence (20 bytes; padded with spaces). Caller name or reason for absence (variable length _0; not padded). Can produce EDX_CLIDINFO error. See Figure 1. Format of General Caller ID Information.
CLIDINFO_CALLID	Caller ID (phone number). Can produce EDX_CLIDINFO, EDX_CLIDOOA, and EDX_CLIDBLK errors.
CLIDINFO_FRAMETYPE	Indicates Caller ID frame. Does not apply to CLIP. Can produce EDX_CLIDINFO error. Values (depending upon service type):
	CLASSFRAME_SDM CLASSFRAME_MDM ACLIPFRAME_SDM ACLIPFRAME_MDM JCLIPFRAME_MDM

Figure 1. Format of General Caller ID Information

Message Types for CLASS (Multiple Data Message)

See Table 9. Caller ID Common Message Types for the standard Message Types that can also be used. The following Message Types can produce an EDX_CLIDINFO error. All returns are NULL terminated.

Table 10. Caller ID CLASS Message Types (Multiple Data Message)

Value	Definition/Returns
MCLASS_DATETIME	Date and Time (as sent by CO without format characters / and :)
MCLASS_DN	Calling line directory number (digits only)
MCLASS_DDN	Dialed number (digits only)
MCLASS_ABSENCE1	Reason for absence of Caller ID (only available if caller name is absent): O = out of area, P = private
MCLASS_REDIRECT	Call forward: 0 = universal; 1 = busy; 2 = unanswered
MCLASS_QUALIFIER	L = long distance call
MCLASS_NAME	Calling line subscriber name
MCLASS_ABSENCE2	Reason for absence of name (only available if caller name is absent): O = out of area, P = private

Message Types for ACLIP (Multiple Data Message)

See Table 9. Caller ID Common Message Types for the standard Message Types that can also be used. The following Message Types can produce an EDX_CLIDINFO error. All returns are NULL terminated.

Table 11. Caller ID ACLIP Message Types (Multiple Data Message)

Value	Definition/Returns
MACLIP_DATETIME	Date and Time (as sent by CO without format characters / and :)
MACLIP_DN	Calling line directory number (digits only)
MACLIP_DDN	Dialed number (digits only)
MACLIP_ABSENCE1	Reason for absence of Caller ID (only available if caller name is absent): O = out of area, P = private
MACLIP_REDIRECT	Call forward: 0 = universal; 1 = busy; 2 = unanswered
MACLIP_QUALIFIER	L = long distance call
MACLIP_NAME	Calling line subscriber name
MACLIP_ABSENCE2	Reason for absence of name (only available if caller name is absent): O = out of area, P = private

Message Types for CLIP

See Table 9. Caller ID Common Message Types for the standard Message Types that can also be used. The following Message Types can produce an EDX_CLIDINFO error. All returns are NULL terminated.

Table 12. Caller ID CLIP Message Types

Value	Definition/Returns
CLIP_DATETIME	Date and Time (as sent by CO without format characters / and :)
CLIP_DN	Calling line directory number (digits only)
CLIP_DDN	Dialed number (digits only)
CLIP_ABSENCE1	Reason for absence of Caller ID (only available if caller name is absent): O = out of area, P = private
CLIP_NAME	Calling line subscriber name
CLIP_ABSENCE2	Reason for absence of name (only available if caller name is absent): O = out of area, P = private
CLIP_CALLTYPE	1 = voice call, 2 = ring back when free call, 129 = message waiting call
CLIP_NETMSG	Network Message System status: number of messages waiting

Message Types for JCLIP (Multiple Data Message)

See Table 9. Caller ID Common Message Types for the standard Message Types that can also be used. The following Message Types can produce an EDX_CLIDINFO error. All returns are NULL terminated.

Table 13. Caller ID JCLIP Message Types (Multiple Data Message)

Value	Definition/Returns
JCLIP_DN	Calling line directory number (digits only)
JCLIP_DDN	Dialed number (digits only)
JCLIP_ABSENCE1	Reason for absence of Caller ID (only available if caller name is absent): O = out of area or unkown reason, P = private (denied by call originator), C = public phone, S = service conflict (denied by call originator's network)
JCLIP_ABSENCE2	Reason for absence of name (only available if caller name is absent): O = out of area or unkown reason, P = private (denied by call originator), C = public phone, S = service conflict (denied by call originator's network)

By passing the proper Message Type ID, the dx_gtextcallid( ) function can be used to retrieve the desired message(s). For example:

• CLIDINFO_CMPLT can be used to get the complete Caller ID frame including header, length, sub-message(s) as sent by the CO
• CLIDINFO_GENERAL can be used to get messages including date and time (formatted), caller's Directory Number (DN), and name
• CLIDINFO_CALLID can be used to get caller's Directory Number (DN)
• CLIDINFO_FRAMETYPE can be used to determine the type of Caller ID frame (for example: CLASS SDM or CLASS MDM, ACLIP SDM or ACLIP MDM, JCLIP MDM)
• MCLASS_DDN can be used to get the dialed number for CLASS MDM (digits only)
• MACLIP_DDN can be used to get the dialed number for ACLIP MDM (digits only)
• CLIP_NAME can be used to get the calling line subscriber name for CLIP
• MACLIP_NAME can be used to get the calling line subscriber name for ACLIP

Caller ID information is available for the call from the moment the ring event is generated (if the ring event is set to occur on or after the second ring (CLASS, ACLIP) or set to occur on or after the first ring (CLIP, JCLIP)) until either of the following occurs:

• If the call is answered (the application channel goes off-hook), the Caller ID information is available to the application until the call is disconnected (the application channel goes on-hook).
• If the call is not answered (the application channel remains on-hook), the Caller ID information is available to the application until rings are no longer received from the Central Office (signaled by ring off event, if enabled).

Cautions

To allow the reception of Caller ID information from the central office before answering a call (application channel goes off-hook):

• For CLASS and ACLIP, set the ring event to occur on or after the second ring.
• For CLIP and JCLIP, set the ring event to occur on or after the first ring.

NOTE:

If the call is answered before Caller ID information has been received from the CO, Caller ID information will not be available.

CLASS and ACLIP: Do not use Multiple Data Message Type IDs with Caller ID information in Single Data Message format.

Make sure the buffer size is large enough to hold the Caller ID message(s) returned by this function.

JCLIP operation requires that the Japanese country-specific parameter file be installed and configured (select Japan in the Dialogic country configuration).

If the application program performs a dx_sethook( ) on an on-hook channel device during the short period before the first ring and when the channel is receiving JCLIP caller ID information , the function will return an error.

Example

/*$ dx_gtextcallid( ) example to obtain all available Caller ID information $*/



#include <windows.h>

#include <sys/types.h>

#include <stddef.h>

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <ctype.h>



/* Dialogic Includes */

#include "srllib.h"

#include "dxxxlib.h"



int main()

{



   int numRings = 2;      /* In the US */

   int ringTimeout = 20;   /* 20 seconds */

   int chdev;      /* Channel descriptor */

   unsigned short parmval;

   unsigned char buffer[81];



   /* Open channel */

   if ((chdev=dx_open("dxxxB1C1", NULL)) == -1) {

      /* process error */

      exit(0);

   }



   /* Enable the caller ID functionality */

   parmval = DX_CALLIDENABLE;

   if (dx_setparm(chdev, DXCH_CALLID, (void *) &parmval) == -1) {

      /* process error */

      exit(0);

   }



   /******************************************************************

    * Set the number of rings required for a RING event to permit

    * receipt of the caller ID information.  In the US, caller ID

    * information is transmitted between the first and second rings

    ******************************************************************/

   parmval = numRings;      /* 2 in the US */

   if (dx_setparm(chdev, DXCH_RINGCNT, &parmval) == -1) {

      /* process error */

      exit(0);

   }



   /* Put the channel onhook */

   if (dx_sethook(chdev, DX_ONHOOK, EV_SYNC) == -1) {

      /* process error */

      exit (0);

   }



   /* Wait for 2 rings and go offhook (timeout after 20 seconds) */

   if (dx_wtring(chdev, numRings, DX_OFFHOOK, ringTimeout) == -1)  {

      /* process error */

   }



   /*************************************************************

    * If the message is an MDM (Multiple Data Message), then

    * individual submessages are available.

    * First get the frame and check the frame type.  If Class MDM,

    * get and print information from submessages.

    *************************************************************/

   if ( dx_gtextcallid(chdev,CLIDINFO_FRAMETYPE, buffer) != -1) {

   

      if(buffer[0] == CLASSFRAME_MDM) {

         /* Get and print the Caller ID */

         if (dx_gtextcallid(chdev, MCLASS_DN, buffer) != -1) {

            printf("Caller ID = %s\n", buffer);

         }

         /* This is another way to obtain Caller ID (regardless of frame type)*/

         else if (dx_gtextcallid(chdev, CLIDINFO_CALLID, buffer) != -1) {

            printf("Caller ID = %s\n", buffer);

         }

         else {

            /* print the reason for the Absence of Caller ID */

            printf("Caller ID not available: %s\n", ATDV_ERRMSGP(chdev));

         }



         /* Get and print the Caller Name */

         if (dx_gtextcallid(chdev, MCLASS_NAME, buffer) != -1) {

            printf("Caller Name = %s\n", buffer);

         }



         /* Get and print the Date and Time */

         if (dx_gtextcallid(chdev, MCLASS_DATETIME, buffer) != -1) {

            printf("Date/Time = %s\n", buffer);

         }



         /* Get and print the Dialed Number */

         if (dx_gtextcallid(chdev, MCLASS_DDN, buffer) != -1) {

            printf("Dialed Number = %s\n", buffer);

         }

      }

      else {

         printf("Submessages not available - not an MDM message\n");



         /* Get just the caller ID */

         if (dx_gtextcallid(chdev, CLIDINFO_CALLID, buffer) != -1) {

            printf("Caller ID = %s\n", buffer);

         }

         else {

            /* print the reason for the absence of caller ID */

            printf("Caller ID not available: %s\n", ATDV_ERRMSGP(chdev));

         }



         /***********************************************************

          * If desired, the date/time, caller name, and caller ID can

          * be obtained together.

          **********************************************************/

         if (dx_gtextcallid(chdev, CLIDINFO_GENERAL, buffer) != -1) {

            printf("Date/Time, Caller Number, and Caller ID = %s\n", buffer);

         }

         else {

            /* Print out the error message */

            printf("Error: %s\n", ATDV_ERRMSGP(chdev));

         }



      }

   }



   dx_close(chdev);

   return(0);

}

Errors

If this function returns -1 to indicate failure, use ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to retrieve one of the following error reasons:

EDX_BADPARM	Invalid parameter
EDX_BUSY	Channel is busy
EDX_CLIDBLK	Caller ID is blocked or private or withheld (infotype = CLIDINFO_CALLID)
EDX_CLIDINFO	Caller ID information not sent, sub-message(s) requested not available or Caller ID information invalid
EDX_CLIDOOA	Caller ID is out of area (infotype = CLIDINFO_CALLID)
EDX_SYSTEM	Error from operating system; use dx_fileerrno( ) to obtain error value

All Message Types (infotype) can produce an EDX_CLIDINFO error. Message Type CLIDINFO_CALLID can also produce EDX_CLIDOOA and EDX_CLIDBLK errors.

See Also

• dx_gtcallid( )
• dx_wtcallid( )

Click here to contact Dialogic Customer Engineering