Dialogic Modular Station Interface API

Transcription

1 Dialogic Modular Station Interface API Library Reference May

2 Copyright All rights reserved. You may not reproduce this document in whole or in part without permission in writing from. All contents of this document are furnished for informational use only and are subject to change without notice and do not represent a commitment on the part of or its subsidiaries ( Dialogic ). Reasonable effort is made to ensure the accuracy of the information contained in the document. However, Dialogic does not warrant the accuracy of this information and cannot accept responsibility for errors, inaccuracies or omissions that may be contained in this document. INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH DIALOGIC PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN A SIGNED AGREEMENT BETWEEN YOU AND DIALOGIC, DIALOGIC ASSUMES NO LIABILITY WHATSOEVER, AND DIALOGIC DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF DIALOGIC PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY INTELLECTUAL PROPERTY RIGHT OF A THIRD PARTY. Dialogic products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or in nuclear facility applications. It is possible that the use or implementation of any one of the concepts, applications, or ideas described in this document, in marketing collateral produced by or on web pages maintained by Dialogic may infringe one or more patents or other intellectual property rights owned by third parties. Dialogic does not provide any intellectual property licenses with the sale of Dialogic products other than a license to use such product in accordance with intellectual property owned or validly licensed by Dialogic and no such licenses are provided except pursuant to a signed agreement with Dialogic. More detailed information about such intellectual property is available from Dialogic s legal department at 9800 Cavendish Blvd., 5th Floor, Montreal, Quebec, Canada H4M 2V9. The software referred to in this document is provided under a Software License Agreement. Refer to the Software License Agreement for complete details governing the use of the software. Dialogic encourages all users of its products to procure all necessary intellectual property licenses required to implement any concepts or applications and does not condone or encourage any intellectual property infringement and disclaims any responsibility related thereto. These intellectual property licenses may differ from country to country and it is the responsibility of those who develop the concepts or applications to be aware of and comply with different national license requirements. Dialogic, Dialogic Pro, Brooktrout, Cantata, SnowShore, Eicon, Eicon Networks, Eiconcard, Diva, SIPcontrol, Diva ISDN, TruFax, Realblocs, Realcomm 100, NetAccess, Instant ISDN, TRXStream, Exnet, Exnet Connect, EXS, ExchangePlus VSE, Switchkit, N20, Powering The Service- Ready Network, Vantage, Connecting People to Information, Connecting to Growth, Making innovation Thrive, and Shiva, among others as well as related logos, are either registered trademarks or trademarks of Dialogic. Dialogic's trademarks may be used publicly only with permission from Dialogic. Such permission may only be granted by Dialogic s legal department at 9800 Cavendish Blvd., 5th Floor, Montreal, Quebec, Canada H4M 2V9. Any authorized use of Dialogic's trademarks will be subject to full respect of the trademark guidelines published by Dialogic from time to time and any use of Dialogic s trademarks requires proper acknowledgement. Windows is a registered trademark of Microsoft Corporation in the United States and/or other countries. Other names of actual companies and products mentioned herein are the trademarks of their respective owners. Publication Date: May 2008 Document Number: Dialogic Modular Station Interface API Library Reference May 2008

3 Contents Revision History About This Publication Purpose Applicability Intended Audience How to Use This Publication Related Information Function Summary by Category Attribute Functions Conference Management Functions Configuration Functions Device Management Functions Diagnostic Functions Extended Connection Functions TDM Routing Functions Station Functions Extended Attribute Functions MSI Function Support by Platform Function Information Function Syntax Conventions ATMS_STATINFO( ) retrieve information about the MSI board ATMS_TSSGBIT( ) retrieve the current station hook status ms_addtoconf( ) add one party to an existing conference ms_chgxtder( ) change the attribute of the connection extender ms_close( ) close the MSI device ms_delconf( ) delete a conference ms_delxtdcon( ) delete an extended connection ms_dsprescount( ) retrieve the available DSP resource count ms_estconf( ) establish a conference ms_estxtdcon( ) establish an extended connection ms_genring( ) generate ringing to a station ms_genringcallerid( ) send distinctive ring and caller ID information ms_genringex( ) generate distinctive ringing to a station ms_genziptone( ) generate a zip tone ms_getbrdparm( ) retrieve board parameters ms_getcde( ) retrieve the attributes of a participant ms_getcnflist( ) retrieve a conference list ms_getctinfo( ) retrieve device information ms_getevt( ) block and return control to the application ms_getevtmsk( ) retrieve station event mask ms_getxmitslot( ) return TDM bus time slot Dialogic Modular Station Interface API Library Reference May

4 Contents ms_listen( ) connect receive channel of station device to a TDM bus time slot ms_listenex( ) connect receive channel of station device to TDM bus time slot ms_monconf( ) add a monitor to a conference ms_open( ) open an MSI device ms_remfromconf( ) remove a party from a conference ms_resultmsg( ) retrieve an ASCII string describing a result code ms_resultvalue( ) retrieve the cause of an event ms_senddata( ) send data to station during a call ms_setbrdparm( ) change board parameters ms_setcde( ) change the attributes of a party ms_setevtmsk( ) change transition event masks ms_setmsgwaitind( ) toggle message waiting indicator lamp ms_setstparm( ) change the MSI station level parameters ms_setvol( ) change or reset the station volume ms_stopfn( ) stop a multitasking function ms_tstcom( ) test the communication ability of a board ms_tstdat( ) perform a data test on the MSI board ms_unlisten( ) disconnect receive channel of a station device ms_unlistenex( ) disconnect receive channel of a station device ms_unmonconf( ) remove a monitor from a conference Events Data Structures CT_DEVINFO channel/station information MS_CADENCE cadence information for distinctive ringing MS_CDT conference properties MS_DataInfo call waiting caller ID information MS_NCB notification tone characteristics SC_TSINFO TDM bus time slot information Error Codes Glossary Index Dialogic Modular Station Interface API Library Reference May 2008

5 Contents Figures 1 Ring Cadence Examples Dialogic Modular Station Interface API Library Reference May

6 Contents Tables 1 MSI Function Support by Platform Dialogic MSI Board/Device Parameters MSI Ring Cadence Examples Ring Cadence Group A Valid Attribute Combinations Dialogic Modular Station Interface API Library Reference May 2008

7 Revision History This revision history summarizes the changes made in each published version of this document. Document No. Publication Date Description of Revisions May 2008 Made global changes to reflect Dialogic brand and changed title to Dialogic Modular Station Interface API Library Reference February 2006 This document version was released in conjunction with SR 6.1 Windows for CompactPCI*. ms_setevtmsk( ) and ms_getevtmsk( ) functions: Added MSEV_CHANSTATE for handling station interface alarms. Events chapter: Added MSEV_CHANSTATE for handling station interface alarms. MS_CDT: Added note to chan_sel field that MSPN_STATION is supported on Springware products only. [PTR 35565] September 2005 ms_listenex( ) and ms_unlistenex( ) functions: Added new functions providing asynchronous mode execution and updated Function Summary by Category and Events chapters. Also corrected related information in ms_listen( ) and ms_unlisten( ) November 2004 Global changes: Removed references to operating system errno global variable and errno.h from example code (PTR 28013). Error Codes chapter: For E_MSSYSTEM, corrected error code description to say operating system error (PTR 28013). ms_senddata( ) function: Added a caution regarding timing of the ms_senddata( ) function call and reliable reception of call waiting caller ID (PTR 31361) November 2003 Global changes: Corrected description of MSMM_RNGOFFHK, MSMM_RNGSTOP, and MSMM_TERM; these are event data for MSEV_RING, not for MSEV_NORING. This change was made on the following function reference pages: ms_genring( ), ms_genringcallerid( ), and ms_genringex( ). Also, no longer show E_MSBADRNGSTA as event data for MSEV_RING and MSEV_NORING. (PTR 25051) In code examples, changed tsinfo.sc_tsarray to tsinfo.sc_tsarrayp. This change was made on the following function reference pages: ms_addtoconf( ), ms_chgxtder( ), ms_estconf( ), ms_estxtdcon( ), ms_getxmitslot( ), ms_listen( ), ms_monconf( ), and ms_unmonconf( ). (PTR 29446) Changed mode from asynchronous to synchronous for the following functions: ms_getxmitslot( ), ms_listen( ), and ms_unlisten( ). (PTR 29710) ms_genringcallerid( ) function reference: Noted that the T:Time and Date sub-field used by the OrigAddr parameter is required as per Bellcore FR-NWT spec. (PTR 29371) CT_DEVINFO data structure reference: Provided updated and more detailed field descriptions. MS_CDT data structure reference: Added new values for the chan_attr field January 2003 Initial version of document. Much of the information contained in this document was previously published in the MSI Software Reference for UNIX and Windows, document number Dialogic Modular Station Interface API Library Reference May

8 Revision History 8 Dialogic Modular Station Interface API Library Reference May 2008

9 About This Publication The following topics provide information about this publication: Purpose Applicability Intended Audience How to Use This Publication Related Information Purpose This publication provides a reference to the functions, parameters, and data structures in the Dialogic Modular Station Interface (MSI) API library. It is a companion document to the Dialogic Modular Station Interface API Programming Guide. Applicability This document version ( ) is published for Dialogic System Release 6.0 PCI for Windows, Dialogic System Release 6.1 CompactPCI for Windows, and Dialogic System Release 6.1 for Linux. This document may also be applicable to other software releases (including service updates) on Linux or Windows operating systems. Check the Release Guide for your software release to determine whether this document is supported. Intended Audience This guide is intended for any of the following: Distributors System Integrators Toolkit Developers Independent Software Vendors (ISVs) Value Added Resellers (VARs) Original Equipment Manufacturers (OEMs) Dialogic Modular Station Interface API Library Reference May

10 About This Publication How to Use This Publication Refer to this publication after you have installed the hardware and the system software which includes the modular station interface software. This publication assumes that you are familiar with the Linux or Windows operating system and the C programming language. The information in this guide is organized as follows: Chapter 1, Function Summary by Category groups the modular station interface library APIs into categories. Chapter 2, Function Information provides details about each modular station interface library function, including parameters, cautions, and error codes. Chapter 3, Events describes the events returned by the modular station interface library. Chapter 4, Data Structures provides details about each data structure used by the modular station interface library, including fields and descriptions. Chapter 5, Error Codes lists the error codes included in the modular station interface library. The Glossary provides definitions of key terms used in this document. Related Information See the following for additional information: (for Dialogic product documentation) (for Dialogic technical support) (for Dialogic product information) 10 Dialogic Modular Station Interface API Library Reference May 2008

11 1.Function Summary by Category 1 This chapter describes the categories into which the Dialogic Modular Station Interface (MSI) library functions can be logically grouped. This chapter also includes a table listing function support on various platforms. Attribute Functions Conference Management Functions Configuration Functions Device Management Functions Diagnostic Functions Extended Connection Functions TDM Routing Functions Station Functions Extended Attribute Functions MSI Function Support by Platform Attribute Functions These functions are used to retrieve specific information about the Dialogic MSI board. ms_dsprescount( ) returns DSP resource count ms_getctinfo( ) returns information about the station interface device 1.2 Conference Management Functions These functions are used to manage all conference activities. ms_addtoconf( ) adds a party to an existing conference ms_delconf( ) deletes a conference ms_estconf( ) establishes a conference ms_getcde( ) retrieves the attributes of a conference Dialogic Modular Station Interface API Library Reference May

12 Function Summary by Category ms_getcnflist( ) gets participant list ms_monconf( ) adds a monitor to a conference ms_remfromconf( ) removes a party from a conference ms_setcde( ) sets the attributes of a conference ms_unmonconf( ) removes a monitor from a conference 1.3 Configuration Functions These functions set the Dialogic MSI device or station level parameters and event masks, and check the status of the Dialogic MSI device parameter settings. ms_getbrdparm( ) returns board parameters ms_getevt( ) (Windows only) retrieves an unsolicited event ms_getevtmsk( ) returns the station event mask ms_resultmsg( ) retrieves an ASCII string describing a result code ms_resultvalue( ) retrieves the cause of an event ms_setbrdparm( ) changes board parameters ms_setevtmsk( ) changes station event mask ms_setstparm( ) changes station level parameters 1.4 Device Management Functions These functions are used to open and close devices. Before using any other Dialogic MSI library function, the device must be opened to obtain the handle. ms_close( ) closes an open MSI device ms_open( ) opens an MSI device and returns a unique handle 12 Dialogic Modular Station Interface API Library Reference May 2008

13 Function Summary by Category ms_stopfn( ) stops a multitasking function in progress 1.5 Diagnostic Functions Diagnostic functions check the functionality of the Dialogic MSI firmware and hardware. ms_tstcom( ) runs MSI communications test to determine whether the PC can communicate with the Dialogic MSI board ms_tstdat( ) runs data test on the Dialogic MSI board to determine whether data is passed successfully between the PC and the Dialogic MSI board 1.6 Extended Connection Functions These functions are used to manage all extended connection activities. ms_chgxtder( ) changes the attributes of the connection extender ms_delxtdcon( ) deletes the extended connection ms_estxtdcon( ) establishes an extended connection 1.7 TDM Routing Functions TDM routing functions are used in time division multiplexing (TDM) bus configurations, which include the CT Bus and SCbus. A TDM bus is resource sharing bus that allows information to be transmitted and received among resources over multiple time slots. TDM routing functions enable the application to make or break a connection between voice, telephone network interface, and other resource channels connected via TDM bus time slots. Each device connected to the bus has a transmit component that can transmit on a time slot and a receive component that can listen to a time slot. Note: The transmit component of each channel of a device is assigned to a time slot at system initialization and download. To listen to other devices on the bus, the receive component of the device channel is connected to any one time slot. Any number of device channels can listen to a time slot. When you see references to the SCbus or SCbus routing, this information also applies to the CT Bus. That is, the physical interboard connection can be either SCbus or CT Bus. The SCbus protocol is used and the SCbus routing API applies to all the boards regardless of whether they use an SCbus or CT Bus physical interboard connection. Dialogic Modular Station Interface API Library Reference May

14 Function Summary by Category Note: A set of TDM routing functions exist for each Dialogic library, such as fax (fx_ functions) and voice (dx_ functions). See the appropriate Dialogic API Library Reference for more information on these functions. ms_getxmitslot( ) returns the number of the TDM bus time slot connected to the transmit component of the station ms_listen( ) connects the receive channel of a station device to a TDM bus time slot ms_unlisten( ) disconnects the receive channel of a station device from a TDM bus time slot ms_listenex( ) connects the receive channel of a station device to a TDM bus time slot (asynchronous) ms_unlistenex( ) disconnects the receive channel of a station device from a TDM bus time slot (asynchronous) TDM routing convenience functions, nr_scroute( ) and nr_scunroute( ), are provided to make or break a half- or full-duplex connection between any two channels transmitting on the bus. These functions are not a part of any library but are provided in a separate C source file called sctools.c located in the /usr/dialogic/sctools directory. The functions are defined in sctools.h. MSI functionality may be conditionally compiled in or out of these functions using the SC_MSI and SC_DTI defines in the makefile provided. Refer to the Dialogic Voice API Library Reference for more details. 1.8 Station Functions These functions set individual characteristics to a station. ms_genring( ) generates a ring to a station ms_genringcallerid( ) sends distinctive ring and caller ID information ms_genringex( ) generates distinctive ringing to a station ms_genziptone( ) generates zip tone to a station ms_senddata( ) sends data to station during a call ms_setmsgwaitind( ) toggles message waiting indicator lamp ms_setvol( ) sets station volume 14 Dialogic Modular Station Interface API Library Reference May 2008

15 Function Summary by Category 1.9 Extended Attribute Functions Extended Attribute functions return information specific to the Dialogic MSI device specified in the function call. ATMS_STATINFO( ) returns station information, including station number and location ATMS_TSSGBIT( ) retrieves the current channel signaling bit status (on-hook or off-hook) 1.10 MSI Function Support by Platform Table 1, MSI Function Support by Platform, on page 15 provides an alphabetical listing of Dialogic MSI API functions. The table indicates which platforms are supported for each of the functions. There are three Dialogic platforms that use the Dialogic MSI library: DI, HDSI, and Springware. Dialogic DM3 boards is a collective name used in this document to refer to products that are based on the Dialogic DM3 mediastream architecture. Examples of Dialogic DM3 boards that use the Dialogic MSI library are Dialogic High Density Station Interface (HDSI) boards and Dialogic Integrated Series (DI) boards. Dialogic Springware boards refer to boards based on earlier-generation architecture, such as the Dialogic MSI-Global Series boards. Although a function may be supported on both Dialogic DM3 and Springware boards, there may be some restrictions on its use. For example, some parameters or parameter values may not be supported. For details, see the function reference descriptions in Chapter 2, Function Information. Table 1. MSI Function Support by Platform Dialogic Platform Function DI HDSI Springware ATMS_STATINFO( ) S S S ATMS_TSSGBIT( ) S S S ms_addtoconf( ) S NS S ms_chgxtder( ) NS NS S ms_close( ) S S S ms_delconf( ) S NS S ms_delxtdcon( ) NS NS S Legend: NS = Not Supported S = Supported * = Variance between platforms, refer to the function description for more information. Dialogic Modular Station Interface API Library Reference May

16 Function Summary by Category Table 1. MSI Function Support by Platform (Continued) Function Dialogic Platform DI HDSI Springware ms_dsprescount( ) S S S ms_estconf( ) S NS S ms_estxtdcon( ) NS NS S ms_genring( ) S S S ms_genringcallerid( ) S S NS ms_genringex( ) S* S* S ms_genziptone( ) NS NS S ms_getbrdparm( ) S* S* S ms_getcde( ) S S S ms_getcnflist( ) S NS S ms_getctinfo( ) S S S ms_getevt( ) S S S ms_getevtmsk( ) S S S ms_getxmitslot( ) S S S ms_listen( ) S S S ms_listenex( ) S S S ms_monconf( ) S NS S ms_open( ) S S S ms_remfromconf( ) S NS S ms_resultmsg( ) S S NS ms_resultvalue( ) S S NS ms_senddata( ) S S NS ms_setbrdparm( ) S* S* S ms_setcde( ) S NS S ms_setevtmsk( ) S S S ms_setmsgwaitind( ) S S NS ms_setstparm( ) S S S ms_setvol( ) S S S ms_stopfn( ) S S S ms_tstcom( ) S S S ms_tstdat( ) S S S Legend: NS = Not Supported S = Supported * = Variance between platforms, refer to the function description for more information. 16 Dialogic Modular Station Interface API Library Reference May 2008

17 Function Summary by Category Table 1. MSI Function Support by Platform (Continued) Function Dialogic Platform DI HDSI Springware ms_unlisten( ) S S S ms_unlistenex( ) S S S ms_unmonconf( ) S NS S Legend: NS = Not Supported S = Supported * = Variance between platforms, refer to the function description for more information. Dialogic Modular Station Interface API Library Reference May

18 Function Summary by Category 18 Dialogic Modular Station Interface API Library Reference May 2008

19 2.Function Information 2 This chapter provides an alphabetical reference to the functions in the Dialogic Modular Station Interface (MSI) library. 2.1 Function Syntax Conventions The Dialogic MSI functions use the following syntax: Note: data_type ms_function(device_handle, parameter1,... parametern) data_type refers to the data type, such as integer, long, or void ms_function represents the function name. Typically, Dialogic MSI functions begin with ms. Extended Attribute functions begin with ATMS. device_handle represents the device handle, which is a numeric reference to a device, obtained when a device is opened. The device handle is used for all operations on that device. parameter1 represents the first parameter parametern represents the last parameter Some Dialogic MSI library functions can operate in either synchronous or asynchronous mode, using a mode parameter. Synchronous functions do not return control to the calling process until the function call is completed. When a function operates in asynchronous mode, the calling process retains control and a completion event is passed to the application to notify that the function is complete. Dialogic Modular Station Interface API Library Reference May

20 ATMS_STATINFO( ) retrieve information about the MSI board ATMS_STATINFO( ) retrieve information about the MSI board Name: long ATMS_STATINFO (devh, statinfop) Inputs: int devh Dialogic MSI board device handle char * statinfop pointer to four bytes containing station information Returns: station information on success -1 on failure Includes: srllib.h dtilib.h msilib.h Category: Extended Attribute Mode: synchronous Dialogic DI, HDSI, Springware Platform: Description The ATMS_STATINFO( ) function returns information about the board running the Dialogic Modular Station Interface (MSI) software. This information includes the number and location of the stations on the board. The application is responsible for allocating the space (4 bytes) for the station information buffer. Parameter devh statinfop Description the valid Dialogic MSI board device handle returned by a call to ms_open( ) pointer to four bytes. When the function returns, the first byte contains the total number of stations on the board. For Dialogic DM3 boards (DI and HDSI), byte 2 is fixed at 1 and bytes 3 and 4 are fixed at -1 (0xFF). For Dialogic MSI boards, bytes 2, 3, and 4 indicate the status of the baseboard and two daughterboards, respectively. Cautions This function fails if an invalid device handle is specified. If no stations are present on the module, 0xFF is returned. 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. 20 Dialogic Modular Station Interface API Library Reference May 2008

21 retrieve information about the MSI board ATMS_STATINFO( ) For information about error codes, refer to Chapter 5, Error Codes. Error defines can be found in dtilib.h or msilib.h. Example #include <windows.h> /* For Windows applications only */ #include "srllib.h" #include "dtilib.h" #include "msilib.h" int i; int devh; /* Board device handle */ unsigned char statinfo[4]; /* Open board 1, device */ if ((devh = ms_open("msib1",0)) == -1) { printf( "Cannot open MSI B1: system error/n"); /* * Continue processing */125 /* Get board Ids and number of stations */ if ((ATMS_STATINFO(devh,statinfo)== -1){ printf("error getting station info\n"); /* Close device and exit */ printf("number of stations = %d\n",statinfo[0]); for (i=0;i<4;i++){ switch (statinfo[i]){ case 0x01: printf("board #%d present\n",i); break; case 0xff: printf("board #%d not present\n",i); break; default: printf("invalid module number %d\n",i); break; /* * Continue Processing */ /* Done processing - close device */ if (ms_close(devh) == -1) { printf("cannot close device msib1: system error/n" ); See Also None. Dialogic Modular Station Interface API Library Reference May

22 ATMS_TSSGBIT( ) retrieve the current station hook status ATMS_TSSGBIT( ) retrieve the current station hook status Name: long ATMS_TSSGBIT (devh) Inputs: int devh Dialogic MSI station device handle Returns: state of channel on success -1 on failure Includes: srllib.h dtilib.h msilib.h Category: Extended Attribute Mode: synchronous Dialogic DI, HDSI, Springware Platform: Description The ATMS_TSSGBIT( ) function retrieves the current station hook status. Parameter Description devh the MSI station device handle returned by a call to ms_open( ) The returned bitmask represents the following: MS_ONHOOK MSI station is on-hook MS_OFFHOOK MSI station is off-hook These equates are defined in msilib.h. Cautions This function fails if an invalid device handle is specified. 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. For information about error codes, refer to Chapter 5, Error Codes. Error defines can be found in dtilib.h or msilib.h. 22 Dialogic Modular Station Interface API Library Reference May 2008

23 retrieve the current station hook status ATMS_TSSGBIT( ) Example #include <windows.h> /* For Windows applications only */ #include "srllib.h" #include "dtilib.h" #include "msilib.h" /* Basic error handler */ do_error( devh, funcname ) int devh; char *funcname; { int errorval = ATDV_LASTERR( devh ); printf( "Error while calling function %s.\n", funcname ); printf( "Error value = %d.", errorval ); printf( "\n" ); main() { int tsdev; /* Station device descriptor variable */ long tsbits; /* Time slot signaling bits */ /* * Open board 1 channel 1 device */ if ( ( tsdev = ms_open( "msib1c1", 0 ) ) == -1 ) { printf( "Cannot open station msib1c1: system error/n" ); exit( 1 ); /* * Get station signaling bits */ tsbits = ATMS_TSSGBIT( tsdev ); if ( tsbits == -1 ) { do_error( tsdev, "ATMS_TSSGBIT()" ); exit( 1 ); switch(tsbits) { case MS_ONHOOK: /* continue processing (on-hook) */ break; case MS_OFFHOOK: /* continue processing (off-hook) */ break; default: printf("undefined parameter value = %d\n", tsbits); break; /* * Continue processing *. *. *. */ /* Done processing - close device. */ if ( ms_close( tsdev ) == -1 ) { printf( "Cannot close station msib1c1: system error/n ); Dialogic Modular Station Interface API Library Reference May

24 ATMS_TSSGBIT( ) retrieve the current station hook status See Also None. 24 Dialogic Modular Station Interface API Library Reference May 2008

25 add one party to an existing conference ms_addtoconf( ) ms_addtoconf( ) add one party to an existing conference Name: int ms_addtoconf (devh, confid, cdt) Inputs: int devh Dialogic MSI board device handle int confid conference identifier MS_CDT *cdt pointer to conference descriptor table Returns: 0 on success -1 on failure Includes: srllib.h dtilib.h msilib.h Category: Conference Management Mode: synchronous Dialogic DI, Springware Platform: Description The ms_addtoconf( ) function adds one party to an existing conference. The conference identifier specifies the conference to which the party will be added. When this function completes successfully, a party is added to a conference which causes a conferencing resource to be used. Only one party at a time can be added using this function. Parameter devh confid cdt Description the Dialogic MSI board device handle the conference identifier number pointer to the conference descriptor table. See the MS_CDT data structure page for details. In SCbus mode, this function returns the listen TDM bus time slot number for the MSPN_TS party. The number is placed in the MS_CDT structure for the MSPN_TS party. For an MSPN_STATION party, such information is not returned because the conferenced signal is not placed on the TDM bus. In SCbus mode, the chan_attr field in the MS_CDT structure is redefined as follows: #define chan_lts chan_attr Note: In SCbus mode, the MS_CDT structure is reused to return the listen TDM bus time slot information. The application is responsible for maintaining the integrity of the data in the structure. Cautions This function fails when: The device handle specified is invalid Dialogic Modular Station Interface API Library Reference May

26 ms_addtoconf( ) add one party to an existing conference Too many parties are specified for a single conference The party is part of another conference The conference ID is invalid The board is out of DSP conferencing resources 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. For information about error codes, refer to Chapter 5, Error Codes. Error defines can be found in dtilib.h or msilib.h. Example #include <windows.h> /* For Windows applications only */ #include "srllib.h" #include "dtilib.h" #include "msilib.h" #define NUM_PARTIES 2 int dev1; /* Board dev descriptor variables */ int chdev2; /* Channel dev descriptor */ int tsdev1, tsdev2; /* Time slot dev desc */ MS_CDT cdt[num_parties]; /* Conf. desc. table */ int confid; /* Conf. ID */ SC_TSINFO tsinfo; /* Time slot info */ int ts1, ts2; /* SCbus time slots */ int station; /* Station number */ /* Open board 1 device */ if ((dev1 = ms_open("msib1",0)) == -1) { printf( "Cannot open MSI B1: system error/n ); /* Open board 1, channel 2 device */ if ((chdev2 = ms_open("msib1c2",0) == -1) { printf("cannot open MSIB1C2: system error/n ); /* Assume MSI/SC is connected to a DTI via SCbus. */ /* Need to do a dt_open() for DTI time slots */ /* followed by dt_getxmitslot() to get SCbus time slots */ /* These SCbus time slots are passed on to the CDT */ /* ts1 & ts2 are used as the time slots */ /* Set up CDT structure */ cdt[0].chan_num = station ; /* station is a valid station number */ cdt[0].chan_sel = MSPN_STATION; cdt[0].chan_attr = MSPA_NULL; /* SCbus time slot to be conferenced */ cdt[1].chan_num = ts1 ; /* ts1 should be a valid time slot */ cdt[1].chan_sel = MSPN_TS; cdt[1].chan_attr = MSPA_NULL; 26 Dialogic Modular Station Interface API Library Reference May 2008

27 add one party to an existing conference ms_addtoconf( ) /* Establish conference */ if (ms_estconf(dev1, cdt, NUM_PARTIES, MSCA_ND, &confid) == -1) { printf("error Message = %s",atdv_errmsgp(dev1)); /* Do a listen for the TS */ tsinfo.sc_numts = 1; tsinfo.sc_tsarrayp = &cdt[1].chan_lts; if (dt_listen(tsdev1, &tsinfo) == -1){ printf("error Message = %s",atdv_errmsgp(tsdev1)); /* Continue processing */ /* Add another party to conference */ cdt[0].chan_num = ts2; /* ts2 should be a valid time slot */ cdt[0].chan_sel = MSPN_TS; cdt[0].chan_attr = MSPA_RO MSPA_TARIFF; if (ms_addtoconf(dev1, confid,&cdt[0]) == -1) { printf("error Message = %s",atdv_errmsgp(dev1)); /* Do a listen for the TS */ tsinfo.sc_numts = 1; tsinfo.sc_tsarrayp = &cdt[0].chan_lts; if (dt_listen(tsdev2, &tsinfo) == -1){ printf("error Message = %s",atdv_errmsgp(tsdev2)); /* Continue processing */ See Also ms_delconf( ) ms_estconf( ) ms_monconf( ) ms_remfromconf( ) ms_addtoconf( ) Dialogic Modular Station Interface API Library Reference May

28 ms_chgxtder( ) change the attribute of the connection extender ms_chgxtder( ) change the attribute of the connection extender Name: int ms_chgxtder (devh, xid, cdt) Inputs: int devh Dialogic MSI board device handle int xid extended connection identifier MS_CDT *cdt pointer to descriptor table Returns: 0 on success -1 on failure Includes: srllib.h dtilib.h msilib.h Category: Extended Connection Mode: synchronous Dialogic Springware Platform: Description The ms_chgxtder( ) function changes the attribute of the connection extender. After an extended connection has been established, only the channel attributes of the connection extender may be changed. The signal that the connection extender should listen to is always present on the TDM bus, irrespective of the connection extender setting of the chan_sel field in the MS_CDT data structure. Note: There can be only one connection extender per extended connection. Parameter devh xid cdt Description the Dialogic MSI board device handle the extended connection identifier pointer to the conference descriptor table. See the MS_CDT data structure page for details. Cautions This function fails when: The device handle specified is invalid The board is not a Dialogic MSI board The connection ID is invalid 28 Dialogic Modular Station Interface API Library Reference May 2008

29 change the attribute of the connection extender ms_chgxtder( ) 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. For information about error codes, refer to Chapter 5, Error Codes. Error defines can be found in dtilib.h or msilib.h. Example #include <windows.h> /* For Windows applications only */ #include "srllib.h" #include "dtilib.h" #include "msilib.h" int dev1; /* Device handle for board */ int chdev2; /* Station dev descriptor */ int tsdev1,tsdev2; /* DTI time slot device handles */ MS_CDT cdt[3]; /* Connection descriptors */ int xid; /* Connection ID */ long lts; /* listen time slot */ SC_TSINFO tsinfo; /* Time slot information structure */ int rc; /* Return Code */ int station, ts1, ts2; /* Start System */ /* Assume that there is a DTI in the system. * Assume two DTI transmit time slots. ts1 and * ts2, are identified by device handles tsdev1 * and tsdev2, respectively. */ /* * Continue processing */ /* * Establish connection between a station and time slot ts1 */ if ((rc=nr_scroute(tsdev1,sc_dti,chdev2,sc_msi,sc_fulldup))== -1) { printf("error making connection between DTI timeslot\n"); printf("and MSI station. rc = 0x%x\n",rc); /* * Now extend the connection established earlier */ cdt[0].chan_num = station ; /* Use MSI station as connection identifier*/ cdt[0].chan_sel = MSPN_STATION; cdt[0].chan_attr = MSPA_PUPIL; cdt[1].chan_num = ts2; /* DTI time slot ts2 for connection extender */ cdt[1].chan_sel = MSPN_TS; cdt[1].chan_attr = MSPA_RO; /* Establish extended connection. Since the extender is in receive only mode, * the connection will be extended without interrupting the conversation between the * external party and the station */ Dialogic Modular Station Interface API Library Reference May

30 ms_chgxtder( ) change the attribute of the connection extender if (ms_estxtdcon(dev1,cdt,&xid) == -1) { printf("error Message = %s",atdv_errmsgp(dev1)); /* Make tsdev2 listen to time slot returned by the ms_estxtdcon function */ tsinfo.sc_numts = 1; tsinfo.sc_tsarrayp = &cdt[1].chan_lts; if (dt_listen(tsdev2,&tsinfo) == -1) { printf("error Message = %s",atdv_errmsgp(tsdev2)); /* Prepare cdt to change the attribute of the connection extender */ cdt[0].chan_num = ts2 ; /* Required station number */ cdt[0].chan_sel = MSPN_TS; cdt[0].chan_attr = MSPA_COACH; /* Change extender to coach */ if (ms_chgxtder(dev1,xid,cdt)== -1) { printf("error Message = %s",atdv_errmsgp(dev1)); See Also ms_delxtdcon( ) ms_estxtdcon( ) 30 Dialogic Modular Station Interface API Library Reference May 2008

31 close the MSI device ms_close( ) ms_close( ) close the MSI device Name: int ms_close (devh) Inputs: int devh Returns: 0 on success -1 on failure Includes: srllib.h dtilib.h msilib.h Category: Device Management Mode: synchronous Dialogic DI, HDSI, Springware Platform: Dialogic MSI device handle Description The ms_close( ) function closes the Dialogic Modular Station Interface (MSI) device previously opened by the calling process and ms_open( ). The devices are either Dialogic MSI boards or stations. The ms_close( ) function releases the handle and breaks the link between the calling process and the device. Parameter Description devh the valid Dialogic MSI device handle returned by a call to ms_open( ) Cautions This function fails if the device handle is invalid. The ms_close( ) function affects only the link between the calling process and the device. Other processes are unaffected by ms_close( ). If event notification is active for the device to be closed, call the SRL sr_dishdlr( ) function prior to calling ms_close( ). A call to ms_close( ) does not affect the configuration of the MSI. Devices should never be closed using close( ). 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. For information about error codes, refer to Chapter 5, Error Codes. Error defines can be found in dtilib.h or msilib.h. Dialogic Modular Station Interface API Library Reference May

32 ms_close( ) close the MSI device Example #include <windows.h> /* For Windows applications only */ #include "srllib.h" #include "dtilib.h" #include "msilib.h" main() { int bddev; /* Board device descriptor variable */ /* Open board 1 device */ if ( ( bddev = ms_open( "msib1", 0 ) ) == -1 ) { printf( "Cannot open board msib1: system error/n ); exit( 1 ); /* * Continue processing *. *. *. */ /* Done processing - close device */ if ( ms_close( bddev ) == -1 ) { printf( "Cannot close board msib1: system error/n ); See Also ms_open( ) 32 Dialogic Modular Station Interface API Library Reference May 2008

33 delete a conference ms_delconf( ) ms_delconf( ) delete a conference Name: int ms_delconf (devh, confid) Inputs: int devh Dialogic MSI board device handle int confid conference identifier Returns: 0 on success -1 on failure Includes: srllib.h dtilib.h msilib.h Category: Conference Management Mode: synchronous Dialogic DI, Springware Platform: Description The ms_delconf( ) function deletes a conference previously established. The conference ID is the value previously returned by ms_estconf( ). Parameter devh confid Description the Dialogic MSI board device handle the Dialogic MSI conference identifier Notes: 1. Calling this function frees all resources in use by the conference. 2. It is the responsibility of the application to perform an unlisten for each party of the conference. 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. For information about error codes, refer to Chapter 5, Error Codes. Error defines can be found in dtilib.h or msilib.h. Dialogic Modular Station Interface API Library Reference May

34 ms_delconf( ) delete a conference Example #include <windows.h> /* For Windows applications only */ #include "srllib.h" #include "dtilib.h" #include "msilib.h" #define NUM_PARTIES 3 int dev1; /* Board dev descriptor variables */ MS_CDT cdt[num_parties]; /* Conf. desc. table */ int confid; /* Conf. ID */ /* Open board 1 device */ if ((dev1 = ms_open("msib1",0)) == -1) { printf( "Cannot open MSI B1: system error/n ); /* * Continue processing */ /* Set up CDT structure */ /* station 2, 4 and 7 are used to establish a conference */ cdt[0].chan_num = 2; cdt[0].chan_sel = MSPN_STATION; cdt[0].chan_attr = MSPA_NULL; cdt[1].chan_num = 4; cdt[1].chan_sel = MSPN_STATION; cdt[1].chan_attr = MSPA_PUPIL; cdt[2].chan_num = 7; cdt[2].chan_sel = MSPN_STATION; cdt[2].chan_attr = MSPA_COACH; /* Establish conference */ if (ms_estconf(dev1, cdt, NUM_PARTIES, MSCA_ND, &confid)!= 0) { printf("error Message = %s",atdv_errmsgp(dev1)); /* * Continue processing */ if (ms_delconf(dev1, confid) == -1){ printf("error Message = %s",atdv_errmsgp(dev1)); /* Continue processing */ See Also ms_addtoconf( ) ms_estconf( ) ms_monconf( ) ms_remfromconf( ) ms_unmonconf( ) 34 Dialogic Modular Station Interface API Library Reference May 2008

35 delete an extended connection ms_delxtdcon( ) ms_delxtdcon( ) delete an extended connection Name: int ms_delxtdcon (devh, xid) Inputs: int devh Dialogic MSI board device handle int xid extended connection identifier Returns: 0 on success -1 on failure Includes: srllib.h dtilib.h msilib.h Category: Extended Connection Mode: synchronous Dialogic Springware Platform: Description The ms_delxtdcon( ) function deletes an extended connection. The connection extender is removed on successful completion of this function. Calling this function does not affect the integrity of the connection. The two parties will still remain in a connection. Parameter devh xid Description the Dialogic MSI board device handle the extended connection identifier number Notes: 1. It is the responsibility of the application to do an ms_unlisten( ) for the connection extender. 2. Calling this function frees three resources. Cautions This function fails when: The device handle specified is invalid The device is not a Dialogic MSI board The connection ID is invalid 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. Dialogic Modular Station Interface API Library Reference May

36 ms_delxtdcon( ) delete an extended connection For information about error codes, refer to Chapter 5, Error Codes. Error defines can be found in dtilib.h or msilib.h. Example #include <windows.h> /* For Windows applications only */ #include "srllib.h" #include "dtilib.h" #include "msilib.h" int dev1; /* Device handle for board */ int xid; /* Connection ID */ SC_TSINFO tsinfo; /* Time slot information structure */ /* Start System */ /* * Assume that there is an extended connection between a * station and a time slot. xid is obtained from the previous * extended connection. */ /* * Continue processing */ /* * Do an unlisten for the connection extender if it is a external * party */ /* * Delete the extended connection */ if (ms_delxtdcon(dev1,xid) == -1) { printf("error Message = %s",atdv_errmsgp(dev1)); /* * Continue processing */ See Also ms_chgxtder( ) ms_estxtdcon( ) 36 Dialogic Modular Station Interface API Library Reference May 2008

37 retrieve the available DSP resource count ms_dsprescount( ) ms_dsprescount( ) retrieve the available DSP resource count Name: int ms_dsprescount (devh, valuep) Inputs: int *devh Dialogic MSI board device handle int *valuep pointer to the memory location to receive the free DSP resource count Returns: 0 on success -1 on failure Includes: srllib.h dtilib.h msilib.h Category: Attribute Mode: synchronous Dialogic DI, HDSI, Springware Platform: Description The ms_dsprescount( ) function returns the available DSP resource count. Parameter devh valuep Description the Dialogic MSI board device handle pointer to the location containing the free DSP resource count Each DSP has a number of resources managed by the application. Calling certain Dialogic Modular Station Interface (MSI) API library functions may cause the available resource count to change. However, the channel selector of the party does not affect the resource usage. When zip tone support is enabled, one resource is used. Note: On Dialogic Springware boards, a conference is limited to eight parties. A monitor is counted as one of the eight parties. The following Dialogic MSI functions cause a change to the available resource count: ms_addtoconf( ) Uses one resource every time a party is added to a conference ms_remfromconf( ) Frees one resource ms_delconf( ) Frees all resources in use by the conference ms_delxtdcon( ) Frees three resources Dialogic Modular Station Interface API Library Reference May