ms_genringCallerID( )

---

Termination Events | Cautions | Errors | Example | See Also

Name:	int ms_genringCallerID(devh, len, mode, Cadid, OrigAddr, rfu)
Inputs:	int devh	station device handle
	unsigned short len	length in cycles for ring
	unsigned short mode	asynchronous or synchronous mode setting
	unsigned short Cadid	cadence ID or default ring
	char* OrigAddr	call origination information
	void* rfu	reserved for future use
Returns:	0 on success for asynchronous operation >0 on success for synchronous operation -1 on failure
Includes:	srllib.h dtilib.h msilib.h
Category:	Station
Mode:	Asynchronous or synchronous
Platform:	DI, HDSI

Description

The ms_genringCallerID( ) function allows transmission of analog caller ID data (call originator information) to telephones equipped with FSK caller ID detectors.

Parameter	Description
devh	device handle
len	ring length (in cycles)
mode	mode setting synchronous EV_SYNC asynchronous EV_ASYNC
Cadid	Either a CadenceID for distinctive rings or the current default ring (MS_RNG_DEFAULT) may be specified
OrigAddr	ASCII character string that holds the information about the origination party. The maximum length is 64 characters. With this feature, OrigAddr can be divided into multiple sub-fields identified by field identifiers to hold analog caller identification (FSK) transmission data.
rfu	reserved for future use

The sub-fields used by the OrigAddr parameter include:

Caller Name

identifies the name of the call originator if available. Maximum value is 36 characters.

Caller Name Absence Reason

identifies why call originator's name is not available. Possible reasons are Private (P) or Out of Area (O).

Caller Number

identifies the number of the call originator if available.

Caller Number Absence Reason

identifies why call originator's number is not available. Possible reasons are Private (P) or Out of Area (O).

Date Time

identifies the date and time at which the call is sent, in the format: month, day, hour, minutes. For example, a string of T:01221215 would be interpreted as Jan 22, 12:15 PM.

User Data

identifies that the data in this field is user-defined analog caller identification (FSK) data and it should be transmitted without parsing. This gives flexibility to the applications to transmit data that is not defined in the above sub-fields.

Sub-group identifiers with format X: are used to specify sub-fields for caller ID transmission. Note that the user strings embed this character as part of sub-field identifiers. Thus this sub-group identifier is implicit by nature.

The following sub-group identifiers are supported:

A: identifies beginning of Caller Number Absence Reason sub-field.

B: identifies beginning of Caller Name Absence Reason sub-field.

I: identifies beginning of Caller Number sub-field.

N: identifies beginning of Caller Name sub-field.

T: identifies beginning of Time and Date sub-field.

R: identifies beginning of user-defined FSK data. This string holds the checksum data at the end. This field provides application support for transmission of FSK data that is not covered by the above fields.

Notes:

1. Use the character '/' as an escape character to indicate that ':' is part of the string. For example, Next string "N:J/:NamathI:993-3000" uses escape character / to embed the name J:Namath.
2. The end of a sub-field is recognized by the character ':' or the end of string when a sub-field is located at the end of the string.

Termination Events

When this function is called in asynchronous mode, a return value of 0 indicates that the function was initiated, while a return value of -1 indicates error. The following events may be received:

MSEV_RING

Indicates successful completion of ring operation.

MSEV_NORING

Indicates the ring operation was not successful. The event data for MSEV_NORING is:

• MSMM_RNGOFFHK

  Solicited off hook detected

• MSMM_RNGSTOP

  Ringing stopped by ms_stopfn( )

• MSMM_TERM

  Ringing terminated

When this function is called in synchronous mode, a return value of -1 indicates failure and a positive return value (>0) indicates the reason for termination. Reasons for termination are:

MSMM_RNGOFFHK

Solicited off hook detected

MSMM_RNGSTOP

Ringing stopped by ms_stopfn( )

MSMM_TERM

Ringing terminated

Cautions

• None.

Errors

If this function returns -1 to indicate failure, obtain the reason for the error by calling the SRL standard attribute function ATDV_LASTERR( ) or ATDV_ERRMSGP( ) to retrieve either the error code or a pointer to the error description, respectively.

Refer to the error type tables found in Chapter 5, "Error Codes". Error defines can be found in dtilib.h or msilib.h.

Example

The following code snippets demonstrate different uses of the OrigAddr parameter.

Application sends Caller Name and Date to a Caller ID phone connected to a station:

OriginationAddress[128] = "T:01310930N:John Doe" which is:
Caller Name = John Doe
Date Time = Jan 31, 9 30 am 

Application sends Caller Number absence reason (O: Out Of Area) and Date and Time to a Caller ID phone connected to a station:

OriginationAddress[128] = "T:01310930A:O" which is:
Caller Number Absence Reason : Out Of Area
Date Time = Jan 31, 9 30 am 

Application sends proprietary data to a Caller ID phone connected to a station:

OriginationAddress[128] = "R:xxxxxxxxxxx" which is:
xxxx  represents the proprietary data to be sent 

See Also

• ms_genring( )
• ms_genringex( )
• ms_SetMsgWaitInd( )
• ms_stopfn( )

Click here to contact Telecom Support Resources