Table of Contents Index NMS Glossary Previous Page Next Page Version

Chapter 9

Auxiliary Functions

9.1 Introduction
9.2 Energy Detector
9.2.1 Energy Detector Events
9.2.2 Energy Detector Parameters
9.2.3 Terminating Energy Detection
9.3 Frequency Shift Key (FSK) Data
9.3.1 Sending FSK Data
9.3.2 Parameters for Sending FSK Data
9.3.3 Terminating FSK Data Transmission
9.3.4 Receiving FSK Data
9.3.5 Parameters for Receiving FSK Data
9.3.6 Terminating FSK Data Reception
9.4 Low Level Call Control
9.5 On-Board Timers
9.5.1 Starting the Timer
9.5.2 Start Timer Events
9.5.3 Stopping the Timer
9.5.4 Stop Timer Event
9.6 Other Functions

9.1 IntroductionTop of Page

This chapter describes ADI service functions for the following features:

9.2 Energy DetectorTop of Page

The ADI service is capable of running an energy detector which examines the inband signal, distinguishing between silence and energy.

The following table lists the functions available in the ADI service for manually starting or stopping the energy detector:
If you want to...

 Then use...

Start the energy detector

 adiStartEnergyDetector

Stop the energy detector

 adiStopEnergyDetector

9.2.1 Energy Detector EventsTop of Page

The energy detector generates the following events:

9.2.2 Energy Detector ParametersTop of Page

adiStartEnergyDetector takes two qualification time parameters:
Parameter

 Description

energyqual

 Energy qualification time; the time in milliseconds in which energy must be present to report an energy event.

silencequal

 Silence qualification time; the time in milliseconds in which energy must not be present to report a silence event.


Additional energy detector parameter information is stored in the ADI_ENERGY_PARMS structure, which is defined in the ADI Service Function Reference Manual.

You can modify the energy detector's default behavior by specifying the following parameters when invoking adiStartEnergyDetector:
Parameter

 Description

thresholdampl

 Threshold amplitude, the noise level in dBm, below which is considered silence. Noise above this level is further qualified as energy.

deglitch

 Deglitch time, the minimum time in milliseconds before a transition between energy and silence is recognized.

autostop

 Automatic stop, controls whether the energy detector continues running after the first event. By default, automatic stop is enabled.

Figure 30 illustrates the energy detection parameters stored in ADI_ENERGY_PARMS:
chap9a.gif

Figure 30. Energy Detection Parameters





9.2.3	 Terminating Energy DetectionTop of Page





adiStopEnergyDetector immediately terminates energy/silence detection. The ADI service generates an ADIEVN_ENERGYDETECT_DONE event with the value set to CTA_REASON_STOPPED, which means that the operation was stopped by application request.



The ADI service may also generate the ADIEVN_ENERGYDETECT_DONE event with an error code, ADIERR_xxx or CTAERR_xxx, or with the value set to CTA_REASON_FINISHED. When set to autostop (one-shot), the value is set to CTA_REASON_FINISHED and the size field contains either ADIEVN_ENERGY_DETECTED or ADIEVN_SILENCE_DETECTED.






9.3	 Frequency Shift Key (FSK) DataTop of Page





The ADI service is capable of sending and receiving Frequency Shift Key (FSK) data. The transmit function is an implementation of the modem portion of Bellcore advisory TA-NWT-000030. The basic modulation is continuous-phase binary FSK at 1200 baud between 1200 Hz (mark) and 2200 Hz (space). The only supported baud rate is 1200.






9.3.1	 Sending FSK DataTop of Page





To send FSK data, call adiStartSendingFSK.



While it is running, the FSK transmitter is in one of the following four states:




An FSK transmission consists of a sequence of states used to transmit a data packet, and it is bracketed by silence or the Idle state.



An FSK transmission with Analog Display Services Interface (ADSI) feature phones consists of the following sequence of data: Sending Mark, Sending Data. The Sending Channel Seizure state never occurs in ADSI feature phones. Therefore, noseizureflag in the ADI_FSKSEND_PARMS structure must be set to  1.






9.3.2	 Parameters for Sending FSK DataTop of Page





adiStartSendingFSK requires the following five parameters defined in the ADI_FSKSEND_PARMS structure. 





 Field Name



 Description



 Default Value



 Valid Values




 noseizureflag



 0: Allows Send Channel Seizure
state and Sending Mark state.
1: Allows only Sending Mark state.



 1



 0, 1




 level



 Transmit output level.



 -14 dBm



 -




 seizetime



 Length of channel seizure in milliseconds, ignored if noseizureflag is set to 1.



 1000



 -




 marktime



 Length of initial mark signal in milliseconds.



 500



 -




 baudrate



 Transmission baud rate.



 1200



 1200



















9.3.3	 Terminating FSK Data TransmissionTop of Page





The send function may be stopped using adiStopSendingFSK. The event value field contains CTA_REASON_STOPPED. The number of bytes sent before the function was stopped cannot be determined.






9.3.4	 Receiving FSK DataTop of Page





Call adiStartReceivingFSK to enable an application to receive FSK data. While it is running, the FSK receiver is in one of the following four states:




A complete packet of FSK data consists of either of the following sequences:




During the receive process, a number of errors can occur. These errors will cause the function to terminate prematurely. If errors occur, the ADIEVN_FSK_RECEIVE_DONE event is sent with one of the following reasons: 





 Reason



 Description




 ADI_REASON_DROP_IN_DATA



 Stopped because of drop in data. The noseizureflag signal dropped to silence during data, not during stop mark period.




 ADI_REASON_BAD_STOP_BIT



 Stopped because of data framing error: the stop bit at the end of data was a space, not a mark.



















9.3.5	 Parameters for Receiving FSK DataTop of Page





adiStartReceivingFSK requires that the following four parameters are defined in the ADI_FSKRECEIVE_PARMS structure: 





 Field Name



 Field Interpretation



 Default Value




 minlevel



 Required minimum receive level.



 -35 dBm




 minmark



 Minimum required initial mark and seizure time, in milliseconds.



 10




 mindrop



 Minimum dropout to silence before a packet is considered terminated, in milliseconds.



 5




 baudrate



 Transmission baud rate.



 1200



















9.3.6	 Terminating FSK Data ReceptionTop of Page





The receive function may be stopped using adiStopReceivingFSK. The event value field will contain CTA_REASON_STOPPED. The size of the partial buffer received is stored in the size field of the event structure.






9.4	 Low Level Call ControlTop of Page





The ADI service includes a set of functions that enables applications to perform call control from the host. These functions are typically used in conjunction with the NOCC (no call control) protocol. Some of the low-level call control functions may also be used when running the ADI service call control; however, their use may be restricted by the specific protocols. 


Note:  The Natural Call Control service API does not include low-level call control functions at this time. Regardless of which service is used to start the NOCC protocol, the low-level call control functions listed below remain accessible to the application.


For example, all Channel Associated Signaling (CAS) protocols reserve out-of-band signaling, so some ADI service functions that perform out-of-band signaling may not be available. For more information about CAS protocols, refer to the AG CAS for the ADI Service Developer's Manual.



The following low level control functions are available in the ADI service: 





 If you want to...



 Then use...




 Assert an out-of-band signaling pattern



 adiAssertSignal




 Pulse an out-of-band signaling pattern for a duration



 adiStartPulse




 Start detection of out-of-band signaling bits



 adiStartSignalDetector




 Stop detection of out-of-band signaling bits



 adiStopSignalDetector




 Query the current inbound out-of-band signaling bits



 adiQuerySignalState




 Start DTMF/pulse dialing of digits



 adiStartDial




 Stop DTMF/pulse dialing of digits



 adiStopDial

















The first five functions are related to out-of-band signaling. This signaling is either the physical out-of-band signal bits of digital protocols or relates to the control of analog interface boards. In both cases, four signaling bits are addressed: A, B, C, and D, often written as ABCD, and defined by a bit mask (0x8, 0x4, 0x2, and 0x1, respectively). When using these functions, refer to the appropriate manual for your telephone line interface board.



The last two functions provide the capability to perform dialing operations when not running formal call control.






9.5	 On-Board TimersTop of Page





The ADI service supports one on-board timer per CTA context on an AG board. This on-board timer has 10-ms resolution. The timer generates periodic events. You specify both the period and number of events when invoking adiStartTimer.



The following functions are available in the ADI service for manually starting or stopping the on-board timers: 





 If you want to...



 Then use...




 Start an on-board timer



 adiStartTimer




 Stop an on-board timer



 adiStopTimer



















9.5.1	 Starting the TimerTop of Page





The timer is started by calling adiStartTimer passing a CTA context, a timeout value, and an event count value. A DONE event will be generated when the timer has expired.



If the count value is greater than one, a "tick" event will be generated for each expiration of the timeout with a DONE event for the final expiration.



The timer may be reset/restarted with an additional call to adiStartTimer. When restarted, previous timer definitions are discarded and the timer begins with the new parameters.


Note:  Unlike most CT Access asynchronous functions, the timer is not stopped automatically when a call is released.





9.5.2	 Start Timer EventsTop of Page





The start timer events are presented in the following table: 





 Event



 Description




 ADIEVN_TIMER_DONE



 Once the timer has completed (expired), the ADI service generates a DONE event with the value field set to CTA_REASON_FINISHED. A DONE event will be received with an error in the value field only if the board has an error. If the timer is stopped by calling adiStopTimer, the value field will be CTA_REASON_STOPPED.




 ADIEVN_TIMER_TICK



 If count is greater than 1, the ADI service generates a "tick" event for the first count-1 expirations.



















9.5.3	 Stopping the Timer Top of Page





adiStopTimer stops the timer started with adiStartTimer. Once the timer has stopped, a DONE event is generated.






9.5.4	 Stop Timer EventTop of Page





The stop timer event is presented in the following table: 





 Event



 Description




 ADIEVN_TIMER_DONE



 When the timer is stopped, a DONE event is generated with the value field set to CTA_REASON_STOPPED.



















9.6	 Other FunctionsTop of Page





The following table lists the board functions available in the ADI service: 





 If you want to...



 Then use...




 Obtain information about a board



 adiGetBoardInfo




 Read the MVIP timeslots for the given board



 adiGetBoardSlots




 Read the on-board OEM data for a given board



 adiGetEEPromData




 Convert an event timestamp to seconds since January 1, 1970



 adiGetTimeStamp

















Board functions only communicate with the board's driver (not directly with the board). When opening the ADI service to use these functions, you do not specify an MVIP address. The board_number parameter in the mvipaddr structure can be set to ADI_AG_DRIVER_ONLY.


Note:  adiGetEEPromData and adiGetTimeStamp are not supported on QX 2000 boards. If these functions are called in a QX 2000-based application, CTAERR_FUNCTION_NOT_AVAIL is returned.










 
Table of Contents Index NMS Glossary Previous Page Next Page Version




 




Want to send us feedback on our documentation?  Email: Tech_Pubs@nmss.com



Copyright © 2000, Natural MicroSystems, Inc.   All rights
reserved.