Dialogic® Standard Runtime Library API Library Reference May 2008 05-1882-006 Copyright © 1992-2008, Dialogic Corporation. All Rights Reserved. You may not reproduce this document in whole or in part without permission in writing from Dialogic Corporation at the address provided below. 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 Dialogic Corporation 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. Due to differing national regulations and approval requirements, certain Dialogic products may be suitable for use only in specific countries, and thus may not function properly in other countries. You are responsible for ensuring that your use of such products occurs only in the countries where such use is suitable. For information on specific products, contact Dialogic Corporation at the address indicated below or on the web at www.dialogic.com. 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. 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, Making Innovation Thrive, Connecting People to Information, Connecting to Growth 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. The other names of actual companies and products mentioned herein are the trademarks of their respective owners. Publication Date: May 2008 Document Number: 05-1882-006 Dialogic® Standard Runtime Library API Library Reference – May 2008 Contents Revision History . 5 About This Publication . 9 Purpose . 9 Applicability . 9 Intended Audience. 9 How to Use This Publication . 10 Related Information . 10 1 Function Summary by Category . 11 1.1 Event Handling Functions . 11 1.2 Event Data Retrieval Functions . 12 1.3 Standard Runtime Library Parameter Functions . 12 1.4 Standard Attribute Functions . 13 1.5 Device Mapper Functions . 13 1.6 Device Grouping Functions . 14 1.7 Miscellaneous Functions . 14 2 Function Information . 15 2.1 Function Syntax Conventions . 15 ATDV_ERRMSGP( ) – return a pointer to an ASCIIZ string. 16 ATDV_IOPORT( ) – return the base port address . 18 ATDV_IRQNUM( ) – return the interrupt number (IRQ) . 20 ATDV_LASTERR( ) – indicate the last error that occurred . 22 ATDV_NAMEP( ) – return a pointer to an ASCIIZ string . 24 ATDV_SUBDEVS( ) – return the number of subdevices for the device . 26 sr_AddToThreadDeviceGroup( ) – add specified devices to group . 28 sr_createevtdatapcopy( ) – copy SRL event data block . 30 sr_CreateThreadDeviceGroup( ) – specify a list of devices to poll for events . 35 sr_DeleteThreadDeviceGroup( ) – remove all devices from the group . 37 sr_destroy( ) – free a copy of event data from the SRL . 39 sr_dishdlr( ) – disable the handler function. 44 sr_enbhdlr( ) – enable the handler function . 47 sr_getboardcnt( ) – retrieve the number of boards of a particular type . 50 sr_getevtdatap( ) – return the address of the variable data block . 53 sr_getevtdatapex( ) – return the address and optionally copy an event data block . 56 sr_getevtdev( ) – return the device handle . 63 sr_getevtlen( ) – return the length of the variable data. 66 sr_getevttype( ) – return the event type for the current event . 69 sr_getfdcnt( ) – return the total number of Linux file descriptors . 72 sr_getfdinfo( ) – populate the fdarray argument with Linux file descriptors . 74 sr_getparm( ) – return the value of a Standard Runtime Library parameter. 76 sr_GetThreadDeviceGroup( ) – retrieve all devices included in the group. 78 Dialogic® Standard Runtime Library API Library Reference – May 2008 3 Dialogic Corporation Contents sr_getUserContext( ) – return a user-supplied pointer . 80 sr_NotifyEvent( ) – send event notification to a window . 82 sr_putevt( ) – add an event to the Standard Runtime Library event queue. 85 sr_RemoveFromThreadDeviceGroup( ) – remove specified devices from group . 88 sr_setparm( ) – set the value of a Standard Runtime Library parameter . 90 sr_waitevt( ) – wait for any event to occur. 95 sr_waitevtEx( ) – wait for events on certain devices . 99 sr_WaitThreadDeviceGroup( ) – wait for events on devices in the group . 103 SRLGetAllPhysicalBoards( ) – return a list of all the physical boards . 105 SRLGetJackForR4Device( ) – return the jack number . 107 SRLGetPhysicalBoardName( ) – retrieve physical board name for specified AUID . 109 SRLGetSubDevicesOnVirtualBoard( ) – return a list of subdevices . 111 SRLGetVirtualBoardsOnPhysicalBoard( ) – return a list of virtual boards. 113 3Events. 115 4 Data Structures . 117 SRLDEVICEINFO – device information for mapping functions. 118 5 Error Codes . .119 Glossary . 121 Index . 123 4 Dialogic® Standard Runtime Library API Library Reference – May 2008 Dialogic Corporation Revision History This revision history summarizes the changes made in each published version of this document. Document No. Publication Date Description of Revisions 05-1882-006 May 2008 Function Summary by Category chapter: Added new sr_createevtdatapcopy( ) and sr_getevtdatapex( ) functions in Event Data Retrieval Functions section. Added new sr_destroy( ) function in Miscellaneous Functions section. sr_createevtdatapcopy( ) function: New function. sr_destroy( ) function: New function. sr_getevtdatapex( ) function: New function. sr_waitevt( ) function: Under Cautions, added that sr_waitevt( ) and sr_waitevtEx( ) should not be used in the same application, and added that sr_waitevt( ) is recommended for single-threaded applications. sr_waitevtEx( ) function: In the Description, added that sr_waitevtEx( ) is recommended for multithreaded applications. Under Cautions, added that sr_waitevt( ) provides better performance for single-threaded applications. 05-1882-005 November 2007 Global changes: Made global changes to reflect Dialogic brand. Corrected the code examples to show that the function prototype for user- supplied event handler functions in Linux is long usr_hdlr (void *parm). The examples were changed for the following functions: sr_dishdlr( ), sr_enbhdlr( ), sr_getevtdatap( ), sr_getevtdev( ), sr_getevtlen( ), sr_getevttype( ), sr_waitevt( ). (IPY00039889) sr_dishdlr( ) and sr_enbhdlr( ) functions: Added caution about enabling/disabling handlers from within handlers. (IPY00035369, IPY00035465) sr_waitevt( ) function: Deleted note about the Device Grouping functions providing an improved mechanism for managing events. Added caution that the application should not call blocking functions in the event handling loop. sr_waitevtEx( ) function: Revised the function description to indicate that using sr_waitevtEx( ) does not result in any performance improvements over using sr_waitevt( ). Deleted note about the Device Grouping functions providing an improved mechanism for managing events. Added recommendation that the same device should not be used across multiple threads. Creating.