• 1.5.1. Generation of Call Logging Events
• 1.5.2. Retrieving Event Data
• CL_EVENTDATA Data Structure

1.5. Call Logging System Operation

The primary function of a call logging system is to observe the activity on digital lines. When a call is established on a monitored digital line, the call logging system receives the voice and signaling data from both the outbound and inbound parties. In order to indicate this dual source of data, the Call Logging API refers to calls as call logging transactions.

The Call Logging API analyzes the signaling data and manages the call logging transactions according to the semantics rules of the CCS protocol used. The semantics rules consist of:

• a list of semantics states, such as dialing, alerting, connected or disconnected, that a call logging transaction can use to represent the current status of the monitored call. The number, index, and names of the semantics states are retrieved using the cl_GetSemanticsState functions.
• a list of semantics variables, such as calling party number, called party number, and bearer channel (B channel) number. The semantics variables are assigned from the contents of the signaling data and can be queried by the application. The variables can be queried on an event basis when an event is received or on a polling basis:
  • Event basis - use the "Get" functions cl_GetCalled( ), cl_GetCalling( ), cl_GetChannel( ), and cl_GetVariable( ).
  • Polling basis - use the "Peek" functions cl_PeekCalled( ), cl_PeekCalling( ), cl_PeekChannel( ), and cl_PeekVariable( ).
• a list of the specific events that the Call Logging API must monitor to identify the first and the last L3 messages related to a call logging transaction. The list of events is also used to determine when the monitored call is connected and later on disconnected. This list allows the Call Logging API to report those key events to the application in a protocol-independent way. Information about specific events is retrieved using the cl_GetTransaction( ) and cl_GetTransactionDetails( ) functions along with other call logging functions depending on the information required. (See Section 1.6.3: Event Handling for a sample scenario.)

For more information on the Call Logging API functions listed above, see Chapter 3: Call Logging Function Reference.

1.5.1. Generation of Call Logging Events

Because of the high impedance nature of its configuration, the call logging system is only an observer; it never has to make outbound calls or answer inbound calls. Instead, the call logging system receives unsolicited events, such as L1 alarms and L2 frames that may contain L3 messages.

When an L2 frame containing an L3 message is received, the Call Logging API:

1. extracts the L3 message from the L2 frame
2. decodes the L3 message
3. changes the state of the related call logging transaction according to the semantics rules of the CCS protocol used
4. sends an unsolicited call logging event to the application

The following table describes the call logging events the Call Logging API can generate:

Table 1. Call Logging Events

Event	Description
CLEV_MESSAGE	The monitored L2 frame contains an L3 message about a call logging transaction.
CLEV_ALARM	An L1 alarm was detected.
CLEV_ERROR	An error occurred.

1.5.2. Retrieving Event Data

Information about events received by the application is contained in an event data block. This information includes the time the initial unsolicited event was observed by the Call Logging API. You obtain the event data block by calling the sr_getevtdatap( ) function while processing a call logging event.

You obtain the type of event by calling the sr_getevttype( ) function. As described in Table 1, the type of event indicates whether a message was received (CLEV_MESSAGE), an alarm was detected (CLEV_ALARM), or an error occurred (CLEV_ERROR).

CL_EVENTDATA Data Structure

The event data block associated with call logging events is based on the CL_EVENTDATA data structure:

{  
      int         iResult;  
      time_t      timeEvent;  
} CL_EVENTDATA;

Table 2 describes the fields in the CL_EVENTDATA data structure.

Table 2. CL_EVENTDATA Data Structure Fields

Field	Meaning/Values
iResult	A bitset of result codes and error codes. The field can contain several of the following symbolic values:
CLEV_MESSAGE events:	ECL_CONNECT_MESSAGE   ECL_DISCONNECT_MESSAGE   ECL_FIRST_MESSAGE   ECL_LAST_MESSAGE   ECL_NOERR   ECL_STATE_HAS_CHANGED   ECL_WRONG_FIRST_MESSAGE
CLEV_ERROR events:	ECL_L2FRAMES_WERE_LOST   ECL_L2LAYER_WAS_RESTARTED   ECL_OUT_OF_MEMORY   ECL_UNRECOGNIZED_L2FRAME   ECL_UNRECOGNIZED_L3MESSAGE
timeEvent	The time when the L2 frame was monitored on the line (that is, when the message was received or the error occurred) or when the L1 alarm event was detected.
NOTES: 1. The value of ECL_NOERR is is 0. This value means that no error was detected and because no bit is set, that the L3 message received is not the first or last message, not a connect or disconnect message, and that this L3 message has not triggered a semantics state change. You can ignore it unless you want to log every L3 message. 2. ECL_WRONG_FIRST_MESSAGE bit is set (together with the ECL_FIRST_MESSAGE bit) to indicate that the received message is the first message received about the call logging transaction, but that this L3 message is unexpected according to the semantics rules. This situation happens when there are already calls in progress when the call logging application starts and the received L3 message is about one of these other calls. This situation can also occur if the expected first message was missed or incorrectly received by the call logging system because of bad cables, poor connections, or glitches on the line. 3. ECL_OUT_OF_MEMORY means there is no more memory left to store transactions. You can get this error event if the application does not use cl_ReleaseTransaction( ).

Click here to contact Dialogic Customer Engineering