MAN1781 Revision 6.4.15 Aculab Call control API guide
PROPRIETARY INFORMATION The information contained in this document is the property of Aculab plc and may be the subject of patents pending or granted, and must not be copied or disclosed without prior written permission. It should not be used for commercial purposes without prior agreement in writing. All trademarks recognised and acknowledged. Aculab plc endeavours to ensure that the information in this document is correct and fairly stated but does not accept liability for any error or omission. The development of Aculab s products and services is continuous and published information may not be up to date. It is important to check the current position with Aculab plc. Copyright Aculab plc. 2002-2010 all rights reserved. Document Revision Rev Date By Detail 6.0 19.12.02 DJL Interim release 6.1 04.06.03 DJL Controlled release 6.1.1 15.01.04 DJL Review updates 6.1.2 27.07.04 DJL Addition of IP telephony protocol support (iptel) 6.2.2 07.09.04 DJL Beta release 6.2.2 15.09.04 DJL Full release 6.2.3 14.10.04 DJL Addition of Linux support 6.3.0 24.12.04 DJL Various updates inclusing support for new hardware 6.3.1 27.01.05 DJL Clarification on slotmap added. 6.3.2 02.02.05 DJL Additional Calling Party Number (ISUP) 6.3.3 24.02.05 DJL Small changes & update to and unequex_isup 6.3.4 21.03.05 DJL RFC updates to uniquex_q931 6.3.5 22.08.05 NS Suplementary services library added 6.3.6 24.08.05 DJL Some small changes/corrctions 6.4.0 03.11.05 DJL Updates for V6.4.0 release including ISUP 6.4.1 01.01.06 DJL Correction of typos and some small changes 6.4.2 21.02.06 DJL Small changes including SIP use of call_openout CNF_TSVIRTUAL 6.4.3 10.03.06 DJL Addition of ISUP information 6.4.4 03.04.06 DJL Clarification added to call_version and call_handle_2_chan 6.4.5 07.07.06 DJL Addition of call driver configuration APIs and small changes 6.4.6 05.10.06 DJL Various small changes/updates. 6.4.7 14.12.06 DJL Addition of resilience APIs 2 of 324
Document Revision Continued Rev Date By Detail 6.4.8 20.06.07 MF Various small changes/updates 6.4.9 08.05.08 DRT Addition of h323_call_details 19.09.08 BB call_protocol_trace timestamp resolution is 1ms for PMX Clarify command field in facility_xparms only needed when connectionless facility is being used AT&T call diversion supported Add AT&T user to user UUI Use CONTROL_NEXT_CC_MESSAGE in network side call transfer Appendix I.4 Remove call transfer operations from call diversion and remove call diversion operations from call transfer. Corrections to message_control for call_feature_openout() and call_feature_send(). 26.09.08 KGB Added UUI for NI2 05.01.09 SAM Added call transfer to call_feature_openout. Added h323_gateway_mode. Fixed list numbering in Call Transfer section. Documented H.323 support of original_diverting_reason field and OP_DIVERTING_LEG_INFO1 in diversion_xparms. Fixed erroneous mention of transfer in diversion_xparms. Added sig_h323 field to feature_transfer_xparms with details. Added H.323 gateway example to Appendix I: Network side call transfer 04.02.09 SAM Fixed some errors in the message_control field in call_feature_openout and call_feature_send. 09.02.09 MF Typo correction 25.02.09 KGB Clarified use of call_get_charge 25.03.09 KGB Corrected orig_number_incomplete 02.07.09 KGB Clarifiied use of CNF_REM_DISC 20.07.09 KGB Clarified raw cause value table 6.4.10 19.08.09 EBJ Updated to corporate fonts. 6.4.11 04.10.10 DF Removed reference to EOL products and V5 drivers 3 of 324
Document Revision Continued Rev Date By Detail 6.4.12 25.10.10 DF Updated as a result of QA assessment 6.4.13 29.10.10 6.4.14 26.11.10 EBJ Removal of Hyperlinks 6.4.15 22.03.11 NC Added call_release_lost_failover_ids() 4 of 324
CONTENTS 1 Introduction... 10 1.1 Scope... 10 1.2 Using the guide... 10 2 Compatibility... 11 2.1 Forward Compatibility... 11 2.2 Writing portable and forward compatible applications using the Aculab API... 12 3 Declaration types... 13 3.1 ACU_RESOURCE_ID Generic Resource ID... 13 3.2 ACU_CALL_HANDLE - Call handle... 13 3.3 ACU_CARD_ID Card id... 13 3.4 ACU_PORT_ID Port id... 13 3.5 ACU_WAIT_OBJECT Wait Object... 13 3.6 ACU_ACT Application token...14 3.7 ACU_ERR Error code... 14 3.8 ACU_EVENT_QUEUE Event queue... 14 4 Call control functions... 15 4.1 System configuration... 15 4.2 Line control... 15 4.3 Basic call control... 16 4.4 Advanced call control... 17 4.5 call_card_dsp_config()... 21 4.6 call_driver_version()... 23 4.7 call_type() - Get signalling system type...24 4.8 call_line() - Get line type... 25 4.9 call_watchdog() - Watchdog... 26 4.10 call_send_alarm() - Sending alarms to the network... 27 4.11 call_port_info() - get information about a port... 28 4.12 call_set_port_name() - set the name of a port... 33 4.13 call_get_card_info() - return information about a card... 34 4.14 call_get_fmw_dl_parms return downloaded call firmware parameters... 36 4.15 port_init() - port initialisation... 37 4.16 call_open_port() - open a port... 37 4.17 call_close_port() - close a port... 40 4.18 call_openout() - Open for outgoing call... 41 4.19 call_openin() - Open for incoming call...48 4.20 call_send_overlap() - Sending overlap digits... 53 4.21 call_event() - Get a call event... 54 4.22 call_details() - Get call details... 60 4.23 call_incoming_ringing() - send incoming ringing... 63 4.24 call_accept() - Accept incoming call... 68 4.25 call_getcause() - Get idle cause... 72 4.26 call_disconnect() - Disconnect call... 74 4.27 call_release() - Release call... 76 4.28 call_feature_openout() - Open for outgoing (with features)... 79 4.29 call_feature_enquiry() - make an outgoing enquiry call with feature information... 84 5 of 324
4.30 call_feature_details() - Get feature information...86 4.31 call_feature_send() - Sending feature information...88 4.32 call_setup_ack() - Send setup acknowledge...91 4.33 call_proceeding() - Send call proceeding message...94 4.34 call_progress() - Send progress information...97 4.35 call_get_originating_addr() - Receiving the originating address...102 4.36 call_answercode() - Setting the answer code...103 4.37 call_get_charge()- Receiving call charge information...105 4.38 call_put_charge()- Sending call charge information...107 4.39 call_notify() - Send notification information...109 4.40 call_send_keypad_info() - Send Keypad Information...111 4.41 call_send_connectionless() - Call independent signalling...113 4.42 call_get_connectionless() - Call independent signalling...116 4.43 call_enable_connectionless() - Call independent signalling...118 4.44 call_maint_port_block()/call_maint_port_unblock() - block or unblock timeslots...119 4.45 call_maint_port_reset() - reset and clear timeslots...121 4.46 call_maint_ts_block()/call_maint_ts_unblock() - block or unblock a timeslot...122 4.47 call_maint_port_status() obtaining timeslot blocking and reset states...123 4.48 call_set_handle_event_queue() - associate a handle with an event queue...125 4.49 call_get_handle_event_wait_object() - get a wait object for a handle...126 4.50 call_set_handle_app_context_token() - associate data with a handle...127 4.51 call_get_handle_app_context_token() - receive data for a handle...128 4.52 call_set_port_default_handle_event_queue() - set the default queue for a port...129 4.53 call_set_port_app_context_token() associate data with a port...130 4.54 call_get_port_app_context_token() - retrieve data for a port...131 4.55 call_set_port_notification_queue() - set a queue for a port...132 4.56 call_get_port_notification() - retrieve events for a port...133 4.57 call_get_port_notification_wait_object() - get events for a card...136 4.58 call_get_global_event_wait_object() - get a global event...137 4.59 call_set_global_notification_queue() - signal event queue on global notification...138 4.60 call_get_global_notification() - retreives next event from global queue...139 4.61 call_get_global_notification_wait_object() - signal event queue on global notification...140 4.62 call_get_system_notification() - get a system event ID...141 4.63 call_get_system_notification_wait_object() - wait for a global event/handle...142 4.64 call_open_iptel_port Open a port for TiNG Media Configuration...143 4.65 call_set_dtmf_handling()...144 4.66 h323_call_details() - Get h323 call details...145 4.67 h323_gateway_mode() - Set H.323 transfer gateway mode...148 4.68 call_hold() - Put a call on hold...151 4.69 call_reconnect() - Reconnect a call on hold...152 4.70 call_enquiry() - Make an enquiry call...154 4.71 call_transfer() - Call transfer...155 4.72 call_get_failover_id() - Get unique identifier for a call...157 4.73 call_reopen() - Recover a handle to an earlier call...158 4.74 call_reattach_fmw() Reattach the call driver to running signaling firmware...159 4.75 call_release_lost_failover_ids() Release any unattached call handles...159 5 Miscellaneous functions... 161 5.1 call_port_2_swdrvr() - Determine port s switch...162 5.2 call_handle_2_io() - Convert handle to call direction...162 5.3 call_handle_2_port() - Determine port_id of a given handle...163 5.4 call_handle_2_chan() - Convert handle to logical channel number...163 5.5 call_get_port_dsp_stream() Retrieve a trunk DSP stream allocated to a network port....164 6 of 324
5.6 idle_net_ts() - Write the IDLE pattern to the network timeslot... 165 5.7 call_api_version()... 166 6 Downloading and Configuring Firmware... 167 6.1 call_restart_fmw() - Restart signalling system firmware... 167 6.2 call_reconfig_fmw () reconfigure the signalling system firmware... 170 6.3 call_stop_fmw()... 171 6.4 call_is_download() - Check if network port requires firmware download... 172 7 Diagnostic Functions... 173 7.1 call_dcba() - Reading the CAS ABCD bits... 174 7.2 call_protocol_trace() - Obtaining protocol information... 176 7.3 call_l1_stats() - Layer 1, statistics... 178 7.4 call_l2_state() - Layer 2 State... 182 7.5 call_start_trace()... 184 7.6 call_stop_trace()... 185 7.7 call_set_trace_mode()... 186 8 unique_xparms... 187 8.1 unique_xparms for Q931... 187 8.2 unique_xparms for DASS2...196 8.3 unique_xparms for DPNSS... 197 8.4 unique_xparms for CAS... 199 8.5 unique_xparms for ISUP\SS7... 200 8.6 unique_xparms for IP telephony (iptel)... 206 9 disconnect_xparms... 213 9.1 Q931... 213 9.2 ISUP\SS7... 214 9.3 DPNSS... 214 9.4 DASS... 214 9.5 CAS... 214 9.6 IP telephony (iptel)... 215 10 Feature xparms... 217 10.1 uui_xparms - user to user information... 218 10.2 facility_xparms - facility information... 225 10.3 diversion_xparms - Diversion/redirect supplementary service... 230 10.4 feature_hold_xparms - Structure for Hold\Retrieve(Reconnect) Information... 240 10.5 feature_transfer_xparms - Call Transfer Information... 242 10.6 raw_data_struct - Raw Data information... 246 10.7 mlpp_xparms (ETSI only)... 247 10.8 Non_standard_data_xparms... 249 10.9 raw_msg_xparms Send / Receive of raw messages / parameters... 250 10.10 call_waiting_xparms Send and receive call waiting information... 253 10.11 restart_channels_xparms... 254 10.12 addressed_non_standard_data_xparms Send/receive connectionless non-standard data... 255 11 Function usage... 256 11.1 Event driven applications... 256 11.2 Call control using events... 256 7 of 324
11.3 Exception handling...258 11.4 Event queues...258 12 Supplementary services library... 259 12.1 ets_mwi_activate() - make mwi activate message...260 12.2 ets_mwi_deactivate() - make mwi deactivate message...261 12.3 ets_mwi_indicate() - make mwi indicate message...262 12.4 ETS_PartyNumber...263 12.5 qsig_mwi_activate() - make MWI Activate message...264 12.6 qsig_mwi_deactivate() - make MWI Deactivate message...265 13 Call driver configuration API... 266 13.1 Available generic call driver settings...266 13.2 call_get_card_configuration_option - Get a configuration option...267 13.3 call_set_card_configuration_option - Set a configuration option...269 13.4 call_enum_card configuration_option - Enumerate available configuration options...271 Appendix A: Error codes... 273 Appendix B: Service Octets... 277 Appendix C: DASS service indicator codes (SIC)... 279 Appendix D: DPNSS service indicator codes (SIC)... 282 Appendix E: Standard clearing causes... 285 Appendix F: Q931 and ISUP... 296 Appendix G: Call independent signalling for euro ISDN & QSIG... 303 Appendix H: Generic functional procedures (facility)... 304 Appendix I: Network side call transfer... 305 I.1 Acknowledgement of a Call Hold request...306 I.2 Accepting an Enquiry Call...307 I.3 Handling a linkid request...307 I.4 Handling a Call Transfer request...309 I.5 Handling a Call Transfer Setup request...313 I.6 Handling a Call Transfer Setup response...314 Appendix J: Raw data format... 315 Appendix K: TiNG media configuration... 318 K.1 Introduction...318 K.2 Benefits...318 K.3 The traditional call API for IP telephony calls...318 8 of 324
K.4 TiNG media configuration... 319 K.5 How to use TiNG media configuration with a system wide port... 320 K.6 On-board H.323... 322 Appendix L: H.323 registration... 323 L.1 Adding Aliases... 323 L.2 Alias Format... 323 L.3 Removing Aliases and Clearing the Gatekeeper... 323 L.4 General Points to Note... 324 9 of 324
1 Introduction This call control guide is designed to help application developers and system integrators understand and use the API provided by Aculab for use with Aculab cards. The call control functions defined in this guide are independent of the operating system used on the host system, enabling applications developed for Aculab cards to be used with several different operating systems. Aculab support a wide range of international signalling systems and this is reflected in the generic data structures employed by the functions described in this guide. The generic data structures provide a superset of compatible data structures with signalling system specific data structures embedded within the generic data structures. The use of these generic data structures allows applications to be written for use with the range of public and private signalling systems supported by Aculab. This version of the document is for use with version 6 (V6) drivers. 1.1 Scope This guide should be used with Aculab call control driver Version 6 or later, for the development of applications that initiate and control outgoing calls and receive and control incoming calls. The Aculab switch control API guide describes the control and switching of timeslots. 1.2 Using the guide This guide describes the interfaces for the API functions and the device driver. Each function is described in terms of its calling parameters and the values that the function will return. No particular operating system or signalling system is assumed and function definitions apply equally to all combinations of operating system and signalling protocols. It should be noted that some features and calls are not applicable to all signalling systems. See Also The Aculab call, switch and speech driver installation guide, which describes how to install the software under different operating systems. The Aculab Switch Control API Guide, which describes the switching and clock control interface. The Aculab example code, which comprises a number of sample applications that illustrate various aspects of the Aculab call and switch API s. The latest versions of these documents are available from the company web site at http://www.aculab.com The latest release notes for each signalling system, containing the latest information and describe the use of configuration switches, are also available from the company web site. 10 of 324
2 Compatibility 2.1 Forward Compatibility Enhancements to the Aculab API are generally made by extending the structures that are passed as parameters to Aculab API calls. To eliminate the problems associated with this, the following steps must be performed: memset(&structure, 0, sizeof(structure)); structure.size = sizeof(structure); In C and C++ programs, these steps can be replaced with the following macro, defined in acu_type.h: INIT_ACU_STRUCT(&structure); In Visual Basic, the LenB() function is the equivalent of sizeof(). Applications, that correctly set this field up, will work correctly against any Aculab library built subsequent to the version with which the application is compiled. Even following this scheme it is not possible for an application built with a particular version of the Aculab libraries to be used against an earlier release of the Aculab drivers. 11 of 324
2.2 Writing portable and forward compatible applications using the Aculab API Applications should always initialise Aculab data structures to 0 using INIT_ACU_STRUCT() or an equivalent. This sets unpopulated fields to a safe default and makes forward compatibility much easier. All Aculab functions assume that unused values will be initialised to 0. Applications must always initialize the size member of Aculab fields to the size of the structure. Call control APIs can also use INIT_ACU_CL_STRUCT(). Always release resources you allocate. Each card_id, port_id, call handle, etc. represents a finite system resource. Failure to de-allocate them may lead to unexpected behaviour or outright system failure. Always check the return code of Aculab API calls, even if you are convinced that they cannot fail. Do not rely on undocumented or platform specific behavior. For example, do not rely on apparently predictable values for call handles, etc. Do not rely on the format of Aculab internal structures. Do not rely on driver filenames, driver directories, the number of drivers, registry entries or values, etc. These are all things that can change arbitrarily between releases. Do not use undocumented functions. Some Aculab API libraries export functions that are not documented. These are for Aculab internal use and should not be used by customers. There is no guarantee that these functions will continue to exist in future versions or that their semantics will remain the same. Where possible do not hard code items such as card serial numbers, firmware filenames, firmware configuration switches, etc. It is much easier to edit a configuration file associated with an application in the field than it is to rebuild the application. Do not make assumptions about what constitutes a valid card serial number. Always use the appropriate Aculab type e.g. ACU_CALL_HANDLE for a call handle, ACU_PORT_ID for a port id. Where there is an Aculab-defined constant for something (e.g. variable lengths, error codes), use it. Never make IOCTL calls directly to the Aculab driver. The internal API-driver interface is liable to change at any time. If the Aculab API lacks some functionality that would be useful, please contact us at support@aculab.com to discuss your requirements. Similarly, do not attempt to use the Aculab API in an environment for which it was not designed, for instance, Aculab s API libraries are not designed for kernel mode operation. 12 of 324
3 Declaration types These types must be used in all applications written using the V6 API instead of native C types. All API calls in the V6 API use these types in their declarations. Some examples of their use can be found in this document, and in some instances, in the V6 resource management API guide. 3.1 ACU_RESOURCE_ID Generic Resource ID This type is used when any of the Aculab resource ID types can be passed into an API call. 3.2 ACU_CALL_HANDLE - Call handle This type is used to represent a single call. Values used for this are returned by functions such as call_openout() and call_openin(). Many Aculab API calls take these values as parameters. The call handle is not meaningful in itself no attempt should be made to decompose it. Call handles are allocated by the system you cannot specify your own handle (see call_openout() for information on how to associate your own data with a call). Additionally, any regularity or commonality in the values returned should not be relied upon. Call handles are associated with a particular process and cannot be passed between different processes. 3.3 ACU_CARD_ID Card id This type is used to represent an instance of an Aculab card. Values used for this are returned by acu_open_card(). A number of Aculab API calls take these values as parameters. The card id is not meaningful in itself. Card ids are associated with a particular process and cannot be passed between different processes. 3.4 ACU_PORT_ID Port id This type is used to represent an instance of a port on an Aculab card. Values used for this are returned by acu_open_port(). A number of Aculab API calls take these values as parameters. The port id is not meaningful in itself. Port ids are associated with a particular process and cannot be passed between different processes. 3.5 ACU_WAIT_OBJECT Wait Object This type is used to allow platform specific wait functions to be used with the Aculab API. It represents a platform-specific wait object (e.g. a HANDLE on Windows, and a file descriptor on Unix-like operating systems). It can be used in functions such as poll() or WaitForMultipleObjects(). 13 of 324
3.6 ACU_ACT Application token This type is used to allow an application to associate data with a call. This is passed in as an additional parameter to call_openin() and call_openout(). The value is returned by call_event() and call_details(). 3.7 ACU_ERR Error code This is the return type of Aculab API calls. 3.8 ACU_EVENT_QUEUE Event queue This type is a reference to an event queue created with acu_alloc_event_queue(). This type is used to allow an application to associate a particular resource with a queue. 14 of 324
4 Call control functions 4.1 System configuration These functions configure the card or provide information about the system: API call_card_dsp_config() call_driver_version() call_type() call_line() Description This API call returns information about the DSPs present on the specified card. This function returns the version of the driver operating for a port. As different ports on the same card can be controlled by different drivers, the driver version is returned on a per-port basis. Used to return a system wide signalling system reference value for a given network port number. This function is useful for applications that support multiple signalling systems Used to return a reference value describing the type of trunk supported by the card. This function is useful if support of multiple interface types is being considered for the application 4.2 Line control These functions control the Physical or Layer 1 connection: API call_watchdog() call_send_alarm() call_port_info() call_set_port_name() call_get_card_info() Description Used to start, stop and refresh the layer 1 watchdog. The aim of this feature is to signal to the network that the Aculab card can no longer take calls. Reasons for this could be an application or operating system failure. Used to send a layer 1 alarm to the network. This may be useful in systems where receipt of an alarm on one trunk may require transmission of that alarm on another trunk. Care should be taken when using this function as transmission of some alarms may cause the network receiving the alarm to cease operation. Get information about a port This function is used to set the name of a port. The name of a port can be used to provide a more descriptive identifier to each port in the system. Return information about a card. 15 of 324
(Line control continued) API call_get_fmw_dl_parms() port_init() Description This diagnostic function returns the parameters that were specified when call control firmware was downloaded. This function is used to initialise a port before calls are made on it. This function calls idle_net_ts() for each of the timeslots on a port. 4.3 Basic call control This section of the guide covers the library functions available for basic call control. These allow calls to be made or received, details of the call to be received and the clearing of calls: API call_open_port() call_close_port() call_openout() call_openin() call_send_overlap() call_event() call_details() Description This function is used to open a port for use. The port_id returned by this function is used as a parameter in many API calls. This function is used to close a port that was previously opened with acu_open_port(). Allows an application to initiate an outgoing call. The function registers the outgoing call requirement with the device driver, which, if satisfied with the calling parameters, will return a unique call identifier, the handle. Allows an application to initiate a wait for an incoming call. The function registers the incoming call requirement with the device driver. If the driver is satisfied with the calling parameters, it will return a unique call identifier, the call handle for that call. Used to send the destination address of an outgoing call one or more digits at a time. The function may also be used any time that a valid outgoing call handle is available and the state of the handle is EV_WAIT_FOR_OUTGOING. The outgoing call handle would have been obtained from the call_openout() function. Used to return an event that may have occurred on any incoming or outgoing call. The device driver issues an event when a change of state occurs. The function may be used any time. Used to gather the details of the current call, either incoming or outgoing, connected through the device driver. call_incoming_ringing() Used to send the ringing message to the network causing the caller to hear the ring tone. This function is used after an incoming call has been detected but before the call has been accepted. Use of the function will stop further call details, such as DDI digits, from being received. 16 of 324
(Basic call control continued) API call_accept() call_getcause() call_disconnect() call_release() Description Used to accept the call after an incoming call has been indicated. This function would typically be used once the application had determined that the DDI digits received by the call_details() function are correct and can be supported. Used to return the clearing cause when an incoming or outgoing call clears. The returned clearing cause will only be valid when the call state is either EV_IDLE or EV_REMOTE_DISCONNECT. Used to disconnect an incoming or outgoing call currently routed through the driver. If the call_disconnect() function is successful, the driver will start the disconnect procedure and will return immediately to the calling process. When the call has been disconnected, the state will be EV_IDLE. The call_release() function must be used to give back the handle to the driver. Used to relinquish ownership of a call handle in response to call termination (CS_IDLE or EV_IDLE) or any error condition that may cause the application to abandon the call. The handle may no longer be used by the application. 4.4 Advanced call control These functions complement the Basic Call functions and provide extra functionality for the user including the use of Supplementary Services : API call_feature_openout() call_feature_enquiry() call_feature_details() call_feature_send() Description It is possible to transmit feature information in a call setup message. An enhanced version of call_openout() is needed to include extra parameters. During the process of call transfer, this function allows an application to make an enquiry call, i.e. an outgoing call to a third party, with feature information Supplementary service information may arrive at different stages during the lifetime of a call. An indication of the availability of this information is found in the feature_information field, after a call to call_details(). To retrieve the information a second function, call_feature_details() should be used. call_feature_send() is used to transmit feature information at different stages during the lifetime of a call. call_setup_ack() Used on an incoming call to send a Q.931 SETUP_ACKNOWLEDGE message to the calling party. 17 of 324
18 of 324 (Advanced call control continued) API call_proceeding() call_progress() call_get_originating_addr() call_answercode() call_get_charge call_put_charge call_notify() call_send_keypad_info() call_send_connectionless() call_get_connectionless() call_enable_connectionless( ) call_maint_port_block()/ call_maint_port_unblock() Description Used on an incoming call to send a message to the calling party to indicate that sufficient information has been obtained to proceed with the call. Used to send call progress information to the network. Used to obtain the originating address of an incoming call. It is primarily intended for use in some Channel Associated Signalling (CAS) systems where the application must explicitly request the originating address from the network Some protocols allow an incoming call to be answered with information about how the call is to be handled during the EV_CALL_CONNECTED state. This function is used to pass the answer code to the driver for use during call connection. Used to obtain information regarding the cost of a call. The function may be used any time that a valid call handle is available, however, the call charge information may not be valid until the call has cleared and the call has gone to the EV_IDLE state. Used to send call charging information on the network and may be used any time that a valid call handle is available and the call is in the EV_CALL_CONNECTED state. Used on a call to send a message to the network to indicate an appropriate call related event during the active state of a call (such as user suspended). Used to send keypad information during a call. This function is only supported in Q.931 Some supplementary services require the use of a connectionless network service to transmit FACILITY messages. call_send_connectionless() allows these messages to be transmitted. Some supplementary services require the use of a connectionless network service to transmit FACILITY messages. call_get_connectionless() will retrieve the latest message of this kind Some protocols require that actions be taken for messages that are not understood. The block function is used to block a group of timeslots within a port, preventing these timeslots from being used for subsequent calls. Conversely, unblock is used on a blocked port to unblock a group of timeslots for that port, bringing the timeslots back into service.
(Advanced call control continued) API call_maint_ts_block()/ call_maint_ts_unblock() call_maint_port_reset() call_maint_port_status call_set_handle_event_queue() call_get_handle_event_wait_object() call_set_handle_app_context_token() call_get_handle_app_context_token() call_set_port_default_handle_event_que ue() call_set_port_app_context_token() Description The block function is used to block (take out of service) a specific timeslot, preventing it from being used to set up a call. Conversely, unblock is used on a blocked timeslot to unblock the timeslot and bring it back into service. Used to reset the status of a port. This will clear any calls in progress on the port. (Currently SS7/ISUP support only) Used to protocol specific status information. This function is used to associate a call handle with an event queue. All call events that occur for the specified call handle will be notified via this event queue This function is used to get a wait object that is associated with a specific call handle. This wait object will be signalled while there are call events pending for that call handle. The wait object returned by this function can be used with operating system specific wait functions such as WaitForMultipleObjects() or poll(). This function is used to associate application-defined data with a call handle. This data is returned as the context field by acu_get_event_from_queue() This function is used to retrieve application defined data that was associated with a call handle by an earlier call to call_openin(), call_openout(), or call_set_handle_app_context_token(). This function is used to set the default event queue for calls made on a particular port. This allows an application to easily group calls by port. This function is used to associated application defined data with a port. This data is returned as the context field by acu_get_event_from_queue(). 19 of 324
(Advanced call control continued) API call_get_port_app_context_token() call_set_port_notification_queue() call_get_port_notification() call_get_port_notification_wait_objec t() call_get_global_event_wait_object() call_set_global_notification_queue() call_get_global_notification() call_get_global_notification_wait_obj ect() call_get_system_notification() call_get_system_notification_wait_obj ect() call_open_iptel_port() Description This function is used to retrieve application-defined data that is associated with a port. The data can be set using call_set_port_app_context_token(). This function is used to associate a port with a queue. All port notification events for this port will be notified via this event queue. The call driver queues a number of events that are not associated with a particular call. This function retrieves events that are associated with a particular port This function is used to get a wait event that is associated with a given card s notification event queue. The event returned by this function can be used with operating system specific wait functions such as WaitForMultipleObjects() or poll(). This function is used to get a wait object that is signalled whenever there is a pending call event on any call handle that the application owns that is associated with the global event queue (see call_event()). This function is used to cause an event queue to be signaled whenever a global notification is raised. This function retrieves the next pending event from the global notification queue. This function is used to cause an event queue to be signaled whenever a global notification is raised. This function retrieves the next pending event from the system notification queue. This function is used to cause an event queue to be signaled whenever a system notification is raised. There are times when an application may wish to have a greater level of control over the media resources on an IP Telephony call than the basic API offers 20 of 324