tsapi

Telephony ServicesApplication Programming Interface(TSAPI)Version 2Issue 2.3 May 1999

Copyright 1999 Lucent Technologies Inc.All Rights ReservedPrinted in U.S.A.

Notice

Every effort was made to ensure that the information in this book was complete andaccurate at the time of printing. However, information is subject to change.

Your Responsibility for Your System’s Security

Toll fraud is the unauthorized use of your telecommunications system by anunauthorized party, for example, persons other than your company’s employees,agents, subcontractors, or persons working on your company’s behalf. Note that theremay be a risk of toll fraud associated with your telecommunications system and, if tollfraud occurs, it can result in substantial additional charges for your telecommunicationsservices.

You and your system manager are responsible for the security of your system, such asprogramming and configuring your equipment to prevent unauthorized use. Thesystem manager is also responsible for reading all installation, instruction, and systemadministration documents provided with this product in order to fully understand thefeatures that can introduce risk of toll fraud and the steps that can be taken to reducethat risk. Lucent Technologies does not warrant that this product is immune from or willprevent unauthorized use of common-carrier telecommunication services or facilitiesaccessed through or connected to it. Lucent Technologies will not be responsible forany charges that result from such unauthorized use.

Lucent Technologies Fraud Intervention

If you suspect that you are being victimized by toll fraud and you need technicalsupport or assistance, call Technical Service Center Toll Fraud Intervention Hotline at1 800 643 2353.

Trademarks

Novell, NetWare, the N-Design, MacIPX and the NetWare logotype are registeredtrademarks and NLM is a trademark of Novell, Inc.

Microsoft, DOS, Windows, Windows NT, and the Microsoft logotype are registeredtrademarks of Microsoft Corp.

Apple and Macintosh are registered trademarks and QuickTime is a trademark ofApple, Inc.

OS/2 and PowerPC are registered trademarks of International Business MachinesCorporation.

CallVisor, DEFINITY and the Lucent Technologies logotype are registered trademarksof Lucent Technologies.

UnixWare is a registered trademark of The Santa Cruz Operation.

All products and company names are trademarks or registered trademarks of theirrespective holders.

Obtaining Products

To learn more about Lucent Technologies products and to order products, contactLucent Direct, the direct-market organization of Lucent Technologies BusinessCommunications Systems. Access their web site at www.lucentdirect.com. Or call thefollowing number: customers 1 800 451 2100.

Warranty

Lucent Technologies provides a limited warranty on this product. Refer to the “LucentTechnologies Network Software License Agreement” provided with your package.

Comments

If you have comments, complete and return the comment card at the end of thisdocument.

Acknowledgment

This document was prepared by BCS Product Publications Group, LucentTechnologies, Middletown, NJ 07748-9972.

0AGE�I

Contents

1��Abstract

2��Introduction0URPOSE �� 0RODUCT�!RCHITECTURE��

4ELEPHONY�3ERVICES�!PPLICATIONS��

3��TSAPI Call Model4ERMINOLOGY ��

$EFINITIONS�� !CRONYMS��

!RCHITECTURE �� $ISTRIBUTION�OF�#OMPUTING�AND�3WITCHING�&UNCTIONS �� !0)�3ERVICES �� 3ERVICES�AND�/BJECTS �� &UNCTIONS�� 43!0)�3WITCHING�3UB $OMAIN�-ODEL��

43!0)�$EVICE�� #ALL �� 43!0)�#ONNECTIONS �� #ALL�3TATUS�%VENT�2EPORTS �� 43!0)�#ALL�3TATES��

$YNAMIC�)DENTIFIER�-ANAGEMENT��

4��Control Services/PENING��#LOSING�AND�!BORTING�AN�!#3�3TREAM�� 3ENDING�#34!�2EQUESTS�AND�2ESPONSES �� 2ECEIVING�%VENTS �� 43!0)�6ERSION�#ONTROL �� 0RIVATE�$ATA�6ERSION�#ONTROL��

0AGE�II

1UERYING�FOR�!VAILABLE�3ERVICES�� !0)�#ONTROL�3ERVICES��!#3�&UNCTIONS�AND�#ONFIRMATION�%VENTS��

ACS/PEN3TREAM�� !#3/PEN3TREAM#ONF%VENT�� ACS#LOSE3TREAM�� !#3#LOSE3TREAM#ONF%VENT �� !#35NIVERSAL&AILURE#ONF%VENT �� ACS!BORT3TREAM�� ACS'ET%VENT"LOCK�� ACS'ET%VENT0OLL�� ACS'ET&ILE��5NIX7ARE�AND�(0 58�� ACS3ET%32��7INDOWS�AND�.ET7ARE �� ACS3ET%32��7IN�� ACS3ET%32��-ACINTOSH�� ACS3ET%32��/3�� ACS%VENT.OTIFY��7INDOWS�� ACS%VENT.OTIFY��7IN�� ACS%VENT.OTIFY��-ACINTOSH�� ACS%VENT.OTIFY��/3�� ACS&LUSH%VENT1UEUE�� ACS%NUM3ERVER.AMES�� ACS%NUM3ERVER.AMES��-ACINTOSH�� ACS1UERY!UTH)NFO��

!#3�5NSOLICITED�%VENTS �� !#35NIVERSAL&AILURE%VENT��

!#3�$ATA�4YPES �� !#3�#OMMON�$ATA�4YPES�� !#3�%VENT�$ATA�4YPES ��

#34!�#ONTROL�3ERVICES�AND�#ONFIRMATION�%VENTS�� CSTA'ET!0)#APS�� #34!'ET!0)#APS#ONF%VENT �� CSTA'ET$EVICE,IST�� #34!'ET$EVICE,IST#ONF%VENT �� CSTA1UERY#ALL-ONITOR�� #34!1UERY#ALL-ONITOR#ONF%VENT��

#34!�%VENT�$ATA�4YPES��

5��Switching Function Services"ASIC�#ALL�#ONTROL�3ERVICES ��

#34!5NIVERSAL&AILURE#ONF%VENT�� CSTA!LTERNATE#ALL�� #34!!LTERNATE#ALL#ONF%VENT��

0AGE�III

CSTA!NSWER#ALL�� #34!!NSWER#ALL#ONF%VENT �� CSTA#ALL#OMPLETION�� #34!#ALL#OMPLETION#ONF%VENT�� CSTA#LEAR#ALL�� #34!#LEAR#ALL#ONF%VENT �� CSTA#LEAR#ONNECTION�� #34!#LEAR#ONNECTION#ONF%VENT �� CSTA#ONFERENCE#ALL�� #34!#ONFERENCE#ALL#ONF%VENT �� CSTA#ONSULTATION#ALL�� #34!#ONSULTATION#ALL#ONF%VENT �� CSTA$EFLECT#ALL�� #34!$EFLECT#ALL#ONF%VENT�� CSTA'ROUP0ICKUP#ALL�� #34!'ROUP0ICKUP#ALL#ONF%VENT �� CSTA(OLD#ALL�� #34!(OLD#ALL#ONF%VENT�� CSTA-AKE#ALL�� #34!-AKE#ALL#ONF%VENT�� CSTA-AKE0REDICTIVE#ALL�� #34!-AKE0REDICTIVE#ALL#ONF%VENT �� CSTA0ICKUP#ALL�� #34!0ICKUP#ALL#ONF%VENT�� CSTA2ECONNECT#ALL�� #34!2ECONNECT#ALL#ONF%VENT�� CSTA2ETRIEVE#ALL�� #34!2ETRIEVE#ALL#ONF%VENT �� CSTA4RANSFER#ALL�� #34!4RANSFER#ALL#ONF%VENT ��

4ELEPHONY�3UPPLEMENTARY�3ERVICES�� CSTA3ET-SG7AITING)ND�� #34!3ET-WI#ONF%VENT�� CSTA3ET$O.OT$ISTURB�� #34!3ET$ND#ONF%VENT �� CSTA3ET&ORWARDING�� #34!3ET&WD#ONF%VENT �� CSTA3ET!GENT3TATE�� #34!3ET!GENT3TATE#ONF%VENT�� CSTA1UERY-SG7AITING)ND�� #34!1UERY-WI#ONF%VENT�� CSTA1UERY$O.OT$ISTURB�� #34!1UERY$ND#ONF%VENT ��

0AGE�IV

CSTA1UERY&WD�� #34!1UERY&WD#ONF%VENT �� CSTA1UERY!GENT3TATE�� #34!1UERY!GENT3TATE#ONF%VENT�� CSTA1UERY,AST.UMBER�� #34!1UERY,AST.UMBER#ONF%VENT�� CSTA1UERY$EVICE)NFO�� #34!1UERY$EVICE)NFO#ONF%VENT��

6��Status Reporting Services3TATUS�2EPORTING�&UNCTIONS�AND�#ONFIRMATION�%VENTS ��

CSTA-ONITOR$EVICE�� CSTA-ONITOR#ALL�� CSTA-ONITOR#ALLS6IA$EVICE�� #34!-ONITOR#ONF%VENT �� CSTA-ONITOR3TOP�� #34!-ONITOR3TOP#ONF%VENT�� CSTA#HANGE-ONITOR&ILTER�� #34!#HANGE-ONITOR&ILTER#ONF%VENT�� #34!-ONITOR%NDED%VENT��

#ALL�%VENT�2EPORTS��5NSOLICITED �� #34!#ALL#LEARED%VENT �� #34!#ONFERENCED%VENT�� #34!#ONNECTION#LEARED%VENT �� #34!$ELIVERED%VENT �� #34!$IVERTED%VENT �� #34!%STABLISHED%VENT�� #34!&AILED%VENT �� #34!(ELD%VENT �� #34!.ETWORK2EACHED%VENT�� #34!/RIGINATED%VENT �� #34!1UEUED%VENT�� #34!2ETRIEVE%VENT�� #34!3ERVICE)NITIATED%VENT�� #34!4RANSFERRED%VENT ��

&EATURE�%VENT�2EPORTS��5NSOLICITED�� #34!#ALL)NFO%VENT�� #34!$O.OT$ISTURB%VENT �� #34!&ORWARDING%VENT�� #34!-ESSAGE7AITING%VENT ��

!GENT�3TATUS�%VENT�2EPORTS��5NSOLICITED �� #34!,OGGED/N%VENT ��

0AGE�V

#34!,OGGED/FF%VENT �� #34!.OT2EADY%VENT �� #34!2EADY%VENT �� #34!7ORK.OT2EADY%VENT �� #34!7ORK2EADY%VENT��

%VENT�2EPORT�$ATA�4YPES��5NSOLICITED�� #34!-ONITOR&ILTER?T �� #34!%VENT#AUSE?T ��

7��Snapshot Services#ALL�3NAPSHOT�3ERVICES��

CSTA3NAPSHOT#ALL2EQ�� #34!3NAPSHOT#ALL#ONF%VENT ��

$EVICE�3NAPSHOT�3ERVICE �� CSTA3NAPSHOT$EVICE2EQ�� #34!3NAPSHOT$EVICE#ONF%VENT ��

8��CSTA Computing Function Services43!0)�6ERSION��2OUTING�� !PPLICATION�#ALL�2OUTING �� 2OUTING�2EGISTRATION�&UNCTIONS�AND�%VENTS ��

CSTA2OUTE2EGISTER2EQ�� #34!2OUTE2EGISTER2EQ#ONF%VENT �� CSTA2OUTE2EGISTER#ANCEL�� #34!2OUTE2EGISTER#ANCEL#ONF%VENT�� #34!2OUTE2EGISTER!BORT%VENT ��

2OUTING�&UNCTIONS�AND�%VENTS �� 2EGISTER�2EQUEST�)$�AND�THE�2OUTING�#ROSS 2EFERENCE�)$�� #34!2OUTE2EQUEST%VENT�� #34!2E2OUTE2EQUEST%VENT �� CSTA2OUTE3ELECT��43!0)�6ERSION��/NLY �� CSTA2OUTE3ELECT)NV�� #34!2OUTE5SED%VENT �� #34!2OUTE%ND%VENT �� CSTA2OUTE%ND��43!0)�6ERSION��/NLY �� CSTA2OUTE%ND)NV��

9��Escape and Maintenance Services%SCAPE�3ERVICES �� -AINTENANCE�3ERVICES �� %SCAPE�3ERVICES��!PPLICATION�AS�#LIENT��

0AGE�VI

CSTA%SCAPE3ERVICE�� #34!%SCAPE3ERVICE#ONF%VENT �� #34!0RIVATE%VENT�� #34!0RIVATE3TATUS%VENT ��

%SCAPE�3ERVICE��$RIVER�3WITCH�AS�THE�#LIENT�� #34!%SCAPE3ERVICE2EQ�� CSTA%SCAPE3ERVICE#ONF�� CSTA3END0RIVATE%VENT��

-AINTENANCE�3ERVICES��$EVICE�3TATUS �� #34!"ACK)N3ERVICE%VENT�� #34!/UT/F3ERVICE%VENT ��

3YSTEM�3TATUS� �!PPLICATION�AS�THE�#LIENT �� CSTA3YS3TAT2EQ�� #34!3YS3TAT2EQ#ONF%VENT �� CSTA3YS3TAT3TART�� #34!3YS3TAT3TART#ONF%VENT�� CSTA3YS3TAT3TOP�� #34!3YS3TAT3TOP#ONF%VENT �� CSTA#HANGE3YS3TAT&ILTER�� #34!#HANGE3YS3TAT&ILTER#ONF%VENT�� #34!3YS3TAT%VENT �� CSTA3YS3TAT%NDED%VENT ��

3YSTEM�3TATUS��$RIVER�3WITCH�AS�THE�#LIENT�� #34!3YS3TAT2EQ%VENT�� CSTA3YS3TAT2EQ#ONF�� CSTA3YS3TAT%VENT��

10��Programming Notes43!0)�ON�-ACINTOSH ��

-ACINTOSH�0ROGRAMMING�/VERVIEW �� -ACINTOSH�$EVELOPMENT�0LATFORMS �� 43!0)�AND�'ESTALT �� $YNAMIC�,INKING��

��X��-ACINTOSH�$YNAMIC�,INKING �� 0OWER0#�-ACINTOSH�$YNAMIC�,INKING ��

5SING�!PPLICATION�#ONTROL�3ERVICES�� %VENT�.OTIFICATION �� 2ECEIVING�%VENTS��

"LOCKING�6ERSUS�0OLLING �� 2ECEIVING�%VENTS�&ROM�!NY�3TREAM��

43!0)�2ESOURCE�-ANAGEMENT �� 5SING�43!0)�)N�3TANDALONE�#ODE��

0AGE�VII

43!0)�ON�/3�� ACS%VENT.OTIFY� �� ACS3ET%32� ��

43!0)�ON�7IN�� 0ROGRAMMING�/VERVIEW �� $EVELOPMENT�0LATFORMS�� ,INKING�TO�THE�43!0)�,IBRARY �� 5SING�!PPLICATION�#ONTROL�3ERVICES�� %VENT�.OTIFICATION �� 2ECEIVING�%VENTS��


3HARING�!#3�3TREAMS�"ETWEEN�4HREADS �� -ESSAGE�4RACE ��

43!0)�ON�5NIX7ARE �� 0ROGRAMMING�/VERVIEW �� $EVELOPMENT�0LATFORMS�� ,INKING�TO�THE�43!0)�,IBRARY �� 5SING�!PPLICATION�#ONTROL�3ERVICES�� %VENT�.OTIFICATION �� 2ECEIVING�%VENTS��


-ESSAGE�4RACE �� 3AMPLE�#ODE ��

�43!0)�ON�(0 58�� 0ROGRAMMING�/VERVIEW �� $EVELOPMENT�0LATFORMS�� ,INKING�TO�THE�43!0)�,IBRARY �� 5SING�!PPLICATION�#ONTROL�3ERVICES�� %VENT�.OTIFICATION �� 2ECEIVING�%VENTS��


-ESSAGE�4RACE �� 5SING�(IGH�-EMORY�ON�7INDOWS�#LIENTS ��

11��CSTA Data Types$EVICE�)DENTIFIERS�� "ASIC�#ALL�#ONTROL�#ONFIRMATION�%VENTS��

#34!!LTERNATE#ALL#ONF%VENT�STRUCTURES �� #34!!NSWER#ALL#ONF%VENT�STRUCTURES��

0AGE�VIII

#34!#ALL#OMPLETION#ONF%VENT�STRUCTURES �� #34!#LEAR#ALL#ONF%VENT�STRUCTURES �� #34!#LEAR#ONNECTION#ONF%VENT�STRUCTURES�� #34!#ONFERENCE#ONF%VENT�STRUCTURES �� #34!#ONSULTATION#ALL#ONF%VENT�STRUCTURES�� #34!$EFLECT#ALL#ONF%VENT�STRUCTURES �� #34!'ROUP0ICKUP#ALL#ONF%VENT�STRUCTURES�� #34!(OLD#ALL#ONF%VENT�STRUCTURES�� #34!-AKE#ALL#ONF%VENT�STRUCTURES�� #34!-AKE0REDICITIVE#ALL#ONF%VENT�STRUCTURES�� #34!0ICKUP#ALL#ONF%VENT�STRUCTURES�� #34!2ECONNECT#ALL#ONF%VENT�STRUCTURES �� #34!2ETRIEVE#ALL#ONF%VENT�STRUCTURES �� #34!4RANSFER#ALL#ONF%VENT�STRUCTURES �� #34!5NIVERSAL&AILURE%VENT�STRUCTURES��

4ELEPHONY�3UPPLEMENTARY�#ONFIRMATION�%VENTS�� #34!3ET-SG7AITING#ONF%VENT�STRUCTURES�� #34!3ET$ND#ONF%VENT�STRUCTURES �� #34!3ET&WD#ONF%VENT�STRUCTURES �� #34!3ET!GENT3TATE#ONF%VENT�STRUCTURES�� #34!1UERY-SG7AITING)ND#ONF%VENT�STRUCTURES�� #34!1UERY$O.OT$ISTURB#ONF%VENT�STRUCTURES�� #34!1UERY&WD#ONF%VENT�STRUCTURES�� #34!1UERY!GENT3TATE#ONF%VENT�STRUCTURES �� #34!1UERY,AST.UMBER#ONF%VENT�STRUCTURES�� #34!1UERY$EVICE)NFO#ONF%VENT�STRUCTURES��

3TATUS�2EPORTING�#ONFIRMATION�%VENTS�� CSTA-ONITOR$EVICE�STRUCTURES �� CSTA-ONITOR#ALL�STRUCTURES�� CSTA-ONITOR#ALLS6IA$EVICE�STRUCTURES �� #34!-ONITOR#ONF%VENT�STRUCTURES �� #34!#HANGE-ONITOR&ILTER#ONF%VENT�STRUCTURES�� #34!-ONITOR3TOP#ONF%VENT�STRUCTURES �� #34!-ONITOR3TOP%VENT�STRUCTURES��

#ALL�%VENT�2EPORTS �� #ALL�%VENT�2EPORT�DATA�STRUCTURES �� #34!#ALL#LEARED%VENT�STRUCTURES �� #34!#ONFERENCED%VENT�STRUCTURES �� #34!#ONNECTION#LEARED%VENT�STRUCTURES�� #34!$ELIVERED%VENT�STRUCTURES�� #34!$IVERTED%VENT�STRUCTURES �� #34!%STABLISHED%VENT�STRUCTURES �� #34!&AILED%VENT�STRUCTURES ��

0AGE�IX

#34!(ELD%VENT�STRUCTURES �� #34!.ETWORK2EACHED%VENT�STRUCTURES�� #34!/RGINATED%VENT�STRUCTURES �� #34!1UEUED%VENT�STRUCTURES�� #34!2ETRIEVED%VENT�STRUCTURES�� #34!3ERVICE)NITIATED%VENT�STRUCTURES �� #34!4RANSFERRED%VENT�STRUCTURES��

&EATURE�%VENT�2EPORTS�� #34!#ALL)NFORMATION%VENT�STRUCTURES�� #34!$O.OT$ISTURB%VENT�STRUCTURES�� #34!&ORWARDING%VENT�STRUCTURES��

!GENT�3TATUS�2EPORT�%VENTS�� #34!,OGGED/N%VENT�STRUCTURES �� #34!,OGGED/FF%VENT�STRUCTURES�� #34!.OT2EADY%VENT�STRUCTURES �� #34!2EADY%VENT�STRUCTURES �� #34!7ORK.OT2EADY%VENT�STRUCTURES �� #34!7ORK2EADY%VENT�STRUCTURES ��

3NAPSHOT�3ERVICES �� #34!3NAPSHOT$EVICE#ONF%VENT�STRUCTURES�� #34!3NAPSHOT#ALL#ONF%VENT�STRUCTURES �� #34!3NAPSHOT$EVICE#ONF%VENT�STRUCTURES��

#OMPUTING�&UNCTION�3ERVICES �� CSTA2OUTE2EGISTER2EQ�STRUCTURES �� CSTA2OUTE2EGISTER2EQ#ONF%VENT��STRUCTURES �� CSTA2OUTE2EGISTER#ANCEL��STRUCTURES�� CSTA2OUTE2EGISTER#ANCEL#ONF%VENT��STRUCTURES�� CSTA2OUTE2EQUEST%VENT��STRUCTURES �� CSTA2OUTE3ELECT��STRUCTURES �� #34!2E2OUTE2EQUEST%VENT��STRUCTURES�� CSTA2OUTE5SED%VENT��STRUCTURES�� CSTA2OUTE%ND%VENT��STRUCTURES �� CSTA2OUTE%ND��STRUCTURES��

%SCAPE�3ERVICES�� CSTA%SCAPE3ERVICE��STRUCTURES �� #34!%SCAPE3ERVICE#ONF%VENT��STRUCTURES �� 0RIVATE%VENT��STRUCTURES �� 0RIVATE3TATUS%VENT��STRUCTURES �� CSTA0RIVATE3TATUS%VENT��STRUCTURES �� #34!%SCAPE3ERVICE%VENT��STRUCTURES �� CSTA%SCAPE3ERVICE#ONF��STRUCTURES �� CSTA3END0RIVATE%VENT��STRUCTURES ��

-AINTENANCE�3ERVICES ��

0AGE�X

#34!"ACK)N3ERVICE%VENT�STRUCTURES�� #34!/UT/F3ERVICE%VENT�STRUCTURES �� CSTA3YS3TAT2EQ�STRUCTURES �� #34!3YS3TAT2EQ#ONF%VENT�STRUCTURES �� CSTA3YS3TAT3TART�STRUCTURES �� #34!3YS3TAT3TART#ONF%VENT�STRUCTURES �� CSTA3YS3TAT3TOP�STRUCTURES �� #34!3YS3TAT3TOP#ONF%VENT�STRUCTURES �� CSTA#HANGE3YS3TAT&ILTER�STRUCTURES �� #34!#HANGE3YS3TAT&ILTER#ONF%VENT�STRUCTURES �� #34!3YS3TAT%VENT�STRUCTURES �� #34!3YS3TAT2EQ%VENT�STRUCTURES �� CSTA3YS3TAT2EQ#ONF�STRUCTURES �� CSTA3YS3TAT%VENT3END�STRUCTURES ��

#34!�#ONTROL�3ERVICES�� CSTA'ET!0)#APS�STRUCTURES �� #34!'ET!0)#APS#ONF%VENT��STRUCTURES �� CSTA'ET$EVICE,IST��STRUCTURES �� #34!'ET$EVICE,IST#ONF%VENT��STRUCTURES ��

#34!�%VENT�3TRUCTURES �� #34!�EVENT�TYPES�� #34!�2EQUEST�%VENT�STRUCTURE �� #34!�%VENT�2EPORT�STRUCTURE�� #34!�5NSOLICITED�%VENT�STRUCTURE �� #34!�#ONFIRMATION�%VENT�STRUCTURE�� #34!�%VENT?T�STRUCTURE��

12��References

List of Figures

4ELEPHONY�3ERVICES�!RCHITECTURE�� -ODEL�3HOWING�THE�2ELATIONSHIP�"ETWEEN�43!0)�%LEMENTS �� $OMAINS�AND�3UB $OMAINS ��

0AGE�XI

$OMAINS�AND�3UB $OMAINS �� 3IMPLE�#ONNECTION�3TATE�-ODEL �� 3AMPLE�#ONNECTION�3TATE�-ODEL�� !LTERNATE�#ALL�3ERVICE�� !NSWER�#ALL�3ERVICE �� #LEAR�#ALL�3ERVICE�� #LEAR�#ONNECTION�3ERVICE �� #ONFERENCE�#ALL�3ERVICE �� #ONSULTATION�#ALL�3ERVICE �� $EFLECT�#ALL�3ERVICE�� 'ROUP�0ICKUP�#ALL�3ERVICE �� (OLD�#ALL�3ERVICE �� -AKE�#ALL�3ERVICE �� -AKE�0REDICTIVE�#ALL�3ERVICE �� 0ICKUP�#ALL�3ERVICE �� 2ECONNECT�#ALL�3ERVICE�� 2ETRIEVE�#ALL�3ERVICE �� 4RANSFER�#ALL�3ERVICE �� #ALL�#LEARED�%VENT�2EPORT �� #ONFERENCED�%VENT�2EPORT�� #ONNECTION�#LEARED�%VENT�2EPORT �� $ELIVERED�%VENT�2EPORT �� $IVERTED�%VENT�2EPORT �� %STABLISHED�%VENT�2EPORT�� &AILED�%VENT�2EPORT �� (ELD�%VENT�2EPORT �� .ETWORK�2EACHED�%VENT�2EPORT �� /RIGINATED�%VENT�2EPORT �� 1UEUED�%VENT�2EPORT�� 2ETRIEVED�%VENT�2EPORT �� 3ERVICE�)NITIATED�%VENT�2EPORT�� 4RANSFERRED�%VENT�2EPORT �� #ALL�3NAPSHOT�3ERVICE�� $EVICE�3NAPSHOT�3ERVICE �� 2OUTING�0ROCEDURE �� %SCAPE�3ERVICES�-ODEL�� 3YSTEM�3TATUS�-AINTENANCE�3ERVICES ��

List of Tables

0AGE�XII

43!0)�3IMPLE�#ALL�3TATES�� #AUSE�#ODE�$EFINITIONS �� #34!�%VENT�2EPORT�#AUSE�2ELATIONSHIPS�� 3YSTEM�3TATUS�#AUSE�#ODES �� /VERALL�3YSTEM�3TATUS�#AUSE�#ODES �� %NUM�3ETTINGS�IN�-ACINTOSH�#OMPILERS�� 3TRUCTURE�!LIGNMENT�3ETTINGS�IN�-ACINTOSH�#OMPILERS��

4ELEPHONY�3ERVICES�!0) � �

C h a p t e r 1 Abstract

Telephony Services integrates server-based telephony control with desktop(client) or server applications on enterprise-wide networks. More specifically,Telephony Services logically integrates the existing telephones currently onthe user’s desktop (analog, ISDN, or those specific to a switch) withtelephony-enabled applications running in a client or server. Server and clientsoftware create and maintain this logical association; no special telephones,special telephone connectors, PC boards, or other hardware are necessary at aclient’s desktop. Server hardware terminates the physical control link betweenthe server and the switch (typically a Private Branch Exchange, or PBX) thatprovides telephony services to the user. The link between Telephony Servicesand the switch is a Computer Telephony Integration (CTI) link.

Software integration gives customers flexibility in deploying CTI applicationsin environments as varied as the multimedia desktop and call centers. TheTelephony Services Application Programming Interface (TSAPI) supportstelephony applications for many different environments.

Telephony Services and TSAPI support telephony control capabilities in ageneric, switch-independent way (e.g., support PBXs from various vendors).The architecture allows the incorporation of vendor-specific switch drivers todeliver Telephony Services across various switch environments.

The Telephony Services API is based on international standards for CTI te-lephony services. Specifically, the European Computer Manufacturers As-sociation (ECMA) CTI standard definition of Computer-Supported Tele-communications Applications (CSTA) is the foundation for TSAPI. TheCSTA standard is a technical agreement reached by an open, multi-vendorconsortium of major switch and computer vendors. Since CSTA Services and


Protocol definitions are the basis for TSAPI, TSAPI provides a generic,switch-independent API.

Various vendors may support a subset of the TSAPI programming interface ontheir CTI links. Programmers should consult corresponding vendordocumentation for application development.

The TSAPI programming interface definition incorporates ECMA CSTAtelephony call control services, call/device monitoring services, queryservices, and services. CSTA services logically integrate the two mostcommon pieces of equipment on users’ desktops: the telephone and personalcomputer.

Security administration for Telephony Services allows administrators to re-strict user access to TSAPI features in various ways. For example, an ad-ministrator may restrict a user to control and monitoring of the telephone attheir desktop. Similarly, an administrator can restrict a user to call control andmonitoring of the telephone at any desktop where they log in. Expandedsecurity permissions can increase a user’s control in support of work group ordepartmental telephony applications. Administrators can expand userpermissions even further to include any telephone or device that it is possibleto control on a CTI link. An administrator might assign an unrestrictedsecurity permission level to a server application that processes calls before calldelivery to user desktops in a call center environment. Of course, anadministrator can assign different users different permissions.

The Telephony Services API is compatible with the following clients:Microsoft Windows, Microsoft Windows 95, Microsoft WindowsNT, Novell NetWare, IBM OS/2, Apple Macintosh,UnixWare, and HP-UX UNIX clients. The Telephony Services API isalso compatible with Novell NetWare and Microsoft Windows NTserver environments. The Telephony architecture permits future growth intoother client and server environments while preserving the TSAPIprogramming interface.

Future releases might extend Telephony Services to include desktop com-munication services available from non-switch servers. Possible enhance-ments could provide desktop voice messaging capabilities from a voice mes-saging server, facsimile capabilities from a fax server, voice response ca-pabilities from a voice response server, etc.


C h a p t e r 2 Introduction

The native network operating systems (NOS) provide APIs that allow clientand server applications to offer users a variety of computing services (forexample, file and print services). Telephony Services expand the set of NOSservices and bring together the two most common pieces of equipment on anend user’s desktop, the telephone and personal computer. These twoenvironments are integrated using TSAPI, a switch-independent standards-based API.

0URPOSE

This document specifies Telephony Services Application ProgrammingInterface (TSAPI) services and C programming language syntax. TSAPI iscompatible with Microsoft Windows, Microsoft Windows 95, MicrosoftWindows NT, Novell NetWare, IBM OS/2, Apple Macintosh, UnixWare, andHP-UX UNIX clients. TSAPI is also compatible with Novell NetWare andMicrosoft Windows NT server environments. The Telephony architecturepermits future growth into other client and server environments whilepreserving the TSAPI programming interface.

The reader should be familiar with telephony and the ECMA Computer-Supported Telecommunications Application (CSTA) service, and protocoldefinitions, i.e., ECMA-179 and ECMA-180. The ECMA CSTA standard isthe basis for TSAPI service and parameter definition. Write to ECMA at theaddress below to obtain copies of these standards.


European Computer Manufacturers Association114 Rue du RhôneCH-1204 GenevaSwitzerlandTelephone: 41 22 735 36 34

"41" above is the United States International Calling code for Switzerland.

0RODUCT�!RCHITECTURE

This NOS environment, along with Telephony Services, supports stand-aloneor distributed telephony applications on multiple clients/servers. In the case ofa distributed application, client and server platforms contain the appropriateapplication components. For example, the client platform may embody theuser interface and local control of the user's telephone. The server platformmay use call information to route calls or look up caller information before theswitch delivers calls to users' telephones. The NOS supports the client/servercommunication and interaction between Telephony Services and theapplication (client or server based).

Since Telephony Services provides a standard API (TSAPI), it facilitates thedevelopment and use of telephony- enabled client and server applications.Figure 2-1 illustrates the architecture of Telephony Services. Note that aswitch-specific driver terminates the CTI link, thereby making the otherTelephony Services modules switch-independent.

.OTE


Figure 2-1Telephony Services Architecture

3ERVER BASED�!PPLICATIONS

4ELEPHONY�3ERVICES�,IBRARY

�/!�-�3ERVER

��&UNCTIONS

�!0)�-APPING

�#4)�,INK�$EVICE

��$RIVER

,!.�!DAPTER�#ARD

��X#4)�,INK�(ARDWARE

�,!.

7INDOWS�/3

4ELEPHONY#LIENT�,IBRARY

!PPLICATIONS

3WITCH�0"8

3ERVER�/�3

3WITCH$RIVER

3WITCH�$RIVER)NTERFACE

#4)�,INK!NALOG��)3$.��OR�0"8 SPECIFIC�LINES

�4ELEPHONY

4ELEPHONY�3ERVICES!0)

4ELEPHONY�3ERVICES�!0)

4ELEPHONY

3ERVICES

-ODULE

3ERVER

7INDOWS��/37INDOWS�.4�/3.ET7ARE�/3

5NIX7ARE�/3

/3��/3(0 58�/3

-ACINTOSH�/3

4ELEPHONY3ERVICES

#LIENT�-ODULES

Telephony Services consists of the following hardware and softwarecomponents (refer to Figure 2-1):

u CTI Link — a link that supports the Computer Telephony Integration(CTI) protocol that logically integrates the telephone and the client


workstation at users’ desktops. A CTI link connects link-specifichardware in the server and the switch. It provides sessions betweenTSAPI applications and the call processing software within the switch.The CTI link is PBX-specific.

u CTI Link Hardware — server hardware that terminates the CTI link toa switch. This hardware is PBX-vendor-specific.

u Switch Driver — a set of software modules that supports andterminates the switch-specific CTI link and protocol; maps the CTIprotocol to the TSAPI (if required); supports any Administration andMaintenance capabilities of the switch driver (if any); and supports adriver interface to the CTI Link Hardware. The Switch Driver modulesare PBX-vendor-specific.

u Switch Driver Interface — a software interface between the SwitchDriver and the Telephony Services module that passes messagesbetween applications and the switch driver. Typically, the messagesconsist of CSTA service requests, responses, and events for TSAPIclients. The messages may also be administration and maintenancerequests, responses, and events for an application doing PBX DriverAdministration or Maintenance. The Switch Driver Interface is PBX-independent and supports any Telephony Services compliant driver.

u Telephony Services module — a software module that providescommunication between multiple telephony-enabled applications andthe switch driver. The Telephony Services module routes messagesfrom the Switch Driver to the applications waiting for telephony eventsand passes the messages received from applications (TSAPI ServiceRequests) to the Switch Driver. All messages between clientapplications and a PBX Switch Driver pass across the Switch DriverInterface. The Telephony Services module enforces user restrictionsadministered in the Telephony Server's security database. This moduleis switch-independent and supports any Telephony Services-compliantdriver.

u Telephony Server — an instance of the Telephony Services modulesoftware running on a particular NOS server.

u Telephony Services API (TSAPI) — the CSTA-based, C languagedefinition of the functions (services), data types (parameters andstructures), and event messages that telephony-enabled applications use


to access Telephony Services. This document specifies TSAPI. TSAPIis switch-independent and supports any Telephony Services-compliantdriver.

u Telephony Services Library — server-based applications use thissoftware module to access TSAPI functions. This library acceptsTSAPI Service Requests and delivers responses and events to serverapplications. This library can run on the same physical NOS server asTelephony Services or on any NOS server in the network. This moduleis switch-independent and supports any Telephony Services-compliantdriver.

u Telephony Client Library — client-based applications use thissoftware module to access TSAPI functions. This library acceptsTSAPI Service Requests and delivers responses and events to clientapplications. This module is switch-independent and supports anyTelephony Services-compliant driver.

In summary, the following software modules and interfaces are switch-independent and support any Telephony Services-compliant driver:

♦ 3WITCH�$RIVER�)NTERFACE♦ 4ELEPHONY�3ERVICES♦ 4ELEPHONY�3ERVICES�!0)��43!0)♦ 4ELEPHONY�3ERVICES�,IBRARY♦ 4ELEPHONY�#LIENT�,IBRARY

The following software/hardware modules are switch-specific:

♦ #4)�,INK♦ #4)�,INK�(ARDWARE��AND�THE♦ 3WITCH�$RIVER

4ELEPHONY�3ERVICES�!PPLICATIONS

Telephony Services supports a variety of telephony-enabled applications. Itcan support voice control applications that allow the user to manage andcontrol incoming and outgoing calls at the desktop or more complexapplications for the office work group or call center environment. Applicationscan provide a variety of features to enhance user telephone control from theclient workstation. Application features may include:

♦ CALL�MANAGEMENT


♦ CALL�SCREENING♦ CALL�LOGGING♦ DIRECTORY�DIALING�FROM�PERSONAL��CLIENT��WORKGROUP��SERVER��AND

CORPORATE�DIRECTORIES♦ DIALING�AND�INTEGRATION�WITH�OTHER�APPLICATIONS��AND♦ INTEGRATION�OF�MESSAGE�WAITING�INDICATOR�FOR�EMAIL�OR�OTHER

MESSAGING�APPLICATIONS

Telephony-enabled applications can meet customer needs in many markets.For example, a customer service application can allow agents to interact withboth the ’’telephony" and "caller database" aspects of the job. An easy-to-usegraphical user interface (GUI) application can include the caller informationon a "screen pop" at agents’ PCs. Any server on the network (PC, mini-computer, or mainframe) can contain a caller database. The applicationintegrates access to all the different information (voice and data) needed tosupport an inbound customer service center. Another example of such anapplication is call routing. Here, the switch requests that the server provide adestination for incoming calls. Applications may also request outbound callsfor Outbound Call Management (OCM) applications such as predictivedialing.


C h a p t e r 3 TSAPI Call Model

This chapter describes concepts from the ECMA CSTA standard that areimportant for TSAPI application programming. The information presentedhere is summarized from the CSTA specifications. The complete specificationis available from ECMA at the address given in Chapter 2.

4ERMINOLOGY

The following sections provide TSAPI definitions and acronyms.

$EFINITIONS

ACD Agent: A telephony user that is a member of an inbound or outboundAutomatic Call Distribution (ACD) group. ACD Agents first sign on(Login) to an ACD group and then the ACD will distribute calls tothe agent.

Active Call: The call (at a station) that is connected (in a talking state) at thatstation. More specifically, the Connection (see Connection) for theActive Call is in the Connected State (see TSAPI Connectionssection, Connection State definition).


Alerting Call: A call that is ringing at a Device. More specifically, theConnection (see Connection) for an Alerting Call is in the AlertingState. When the Device is a telephone, the Alerting Call is ringing thetelephone instrument.

Application: A cooperative process distributed between a Switching Function(see Switching Function) and a Computing Function (see ComputingFunction).

Application Domain: The union of one Switching Sub-Domain (seeSwitching Sub-Domain) and one Computing Sub-Domain (seeComputing Sub-Domain).

Basic Call: A Call (see Call) between exactly two Devices (see Device).

Call (TSAPI programming object): A Switching Function communicationsrelationship. Typically, a Call is a communications relationshipbetween two or more Devices. Note, however, during call set-up andrelease, there may be only one Device on the Call. A Call is a TSAPIprogramming object.

Call Identifier: A TSAPI programming handle that identifies a Call.

Complex Call: A Call between more than two Devices.

Computing Domain: Those computers (and their Objects) accessible from aSwitching Function. Where a switch has multiple CTI links tomultiple computers, the Computing Domain is the union of allcomputers connected to the switch.

Computing Function: A computer or other resource in a Computing Sub-domain.

Computing Sub-Domain: Those computers (and their Objects) accessiblefrom the Switching Function using a specific CTI link. Where aswitch has multiple CTI links to multiple computers, the ComputingSub-Domain is a subset of the Computing Domain. Where the switchhas a single CTI link, the Computing Sub-Domain is equivalent to theComputing Domain.


Connection (TSAPI programming object): A relationship between a Calland a Device. A Connection is in one of a number of states (alerting,held, connected, etc.). Note that when a Call connects (for example)three Devices, there are three Connections for the Call. EachConnection reflects the state of the Call at one of the Devices.

Connection Identifier (TSAPI programming handle): A TSAPI pro-gramming handle that identifies a Connection. A Call Identifier and aDevice Identifier comprise a TSAPI Connection Identifier.

Device (TSAPI programming object): An Object that abstracts the interfacebetween a user and the communications signaling in the SwitchingFunction. A Device can be a single endpoint (such as a telephone), ormultiple endpoints that form a group (ACD group or trunk group).

Device Identifier (TSAPI programming handle): A TSAPI programminghandle that identifies a Device.

Directory Number: The phone number for a Device. Directory Numberstypically denote telephone station Devices, but ACD groups and otherDevices may have Directory Numbers also.

Domain: The union of a Switching Domain and a Computing Domain. It isthe switching and computing objects that an application can access.

Event: A stimulus of interest to an Application that (typically) causes achange in the state of a Device object.

Event Report: A message from a Switching Sub-Domain to a ComputingSub-Domain indicating that an Event has occurred.

Held Call: A call (at a station) that is held (in a hold state) at that station.More specifically, the Connection (see Connection) for a Held Call isin the Hold State (see TSAPI Connections section, Connection Statedefinition).

Interconnection Service Boundary: An abstraction of the boundary betweenthe Switching Domain and the Computing Domain. In practice, CTIlinks bridge the Interconnection Service Boundary.

Object: TSAPI programming objects include Connections, Calls, and De-vices. Each has a corresponding programming handle, or identifier.


Party: A telephony user. A Party may be a human, application, or other re-source (such as a port on a voice response unit).

Service: The benefit provided by an Application to a User.

Service Boundary: A specific CTI interface between a Computing Functionand a Switching Function. All Service boundaries cross the In-terconnection Service Boundary.

State: An object’s current condition. Specifically, TSAPI Connections havean associated state.

Switching Domain: Those switches (and their Objects) accessible from aComputing Function. Where a computer has multiple CTI links tomultiple switches, the Switching Domain is the union of all switchesconnected to the computer.

Switching Function: A switch in a Switching Sub-domain.

Switching Sub-Domain: Those switches (and their Objects) accessible froma Computing Function using a specific CTI link. Where a computerhas multiple CTI links to multiple switches, the Switching Sub-Domain is a subset of the Switching Domain. Where the computerhas a single CTI link, the Switching Sub-Domain is equivalent to theSwitching Domain.

User: A person, process or piece of equipment that receives direct benefit(e.g. new feature, improved performance) from an Application’sServices.

!CRONYMS

ACD: Automatic Call Distributor

CSTA: Computer-Supported Telecommunications Applications

ID: Identifier

ISDN: Integrated Services Digital Network


!RCHITECTURE

This section summarizes the functional architecture underlying ECMA CSTAand TSAPI. CSTA defines the interworking between Computing andSwitching Functions in a way that is independent of their physical imple-mentation. This section introduces the concepts of

u distribution of Computing and Switching Functions

u TSAPI Service

u client/server model

u TSAPI objects

An Application is a cooperative process distributed between a SwitchingFunction (switch) and a Computing Function (computer). This section de-scribes the interactions between them.

$ISTRIBUTION�OF�#OMPUTING�AND�3WITCHING�&UNCTIONS

One (or several) computers in a computing network provide the ComputingFunctions and one (or several) switches provide the Switching Functions for aTSAPI Application. The TSAPI application appears to a User (human ormachine) to be a single application, not as two separate functions on twoseparate networks (as it is, in fact, implemented).

Since the applications use distributed resources, communications must occurbetween the distributed entities. Figure 3-1 shows an abstract communicationsmodel. Note that each of the distributed functions is expanded into:

u a client application component that provides the TSAPI interactions

u a server communications component that exchanges messages

u networking support, or lower layer interconnection


Figure 3-1Model Showing the Relationship Between TSAPI Elements

#OMMUNICATIONS�0ROTOCOL

43!0)��$EFINITIONS

,OCAL�REPRESENTATION�OF3ERVICE�$EFINITIONS

,OCAL�REPRESENTATION�OF�0ROTOCOL

#OMMUNICATIONS#OMPONENT

#OMMUNICATIONS#OMPONENT

.ETWORKING�3UPPORT

!PPLICATION#OMPONENT

!PPLICATION#OMPONENT

Figure 3-1 shows that distributed Application components use TSAPI defi-nitions to interact with their peers. TSAPI defines the Service descriptions andprovides the service interface between the Application functions and theServer providing communications with the switch. TSAPI supports variousswitches, and as a consequence, some of the TSAPI elements are optional andtheir use is implementation-dependent.

!0)�3ERVICES

Unless otherwise qualified, the TSAPI definition uses the term ’Service’ torefer to the benefit that an application server provides to a client application.TSAPI Services are independent of the specific CTI link connecting the switchwith the application server. Since TSAPI is independent of the particulartelephone terminal types, the Switching Function must determine how tosupport a given TSAPI request for its specific telephone types. For example,TSAPI does not specify how to provide the Make Call Service for analog orISDN telephones. A Switching Function will use its existing service


definitions to provide TSAPI Services on telephones where that servicealready exists.

TSAPI definitions do not embody the specific details of how the SwitchingFunction accomplishes TSAPI Services. The Switching Function does providean abstraction to the TSAPI Service requester, via Event Reports, of the stepstaken to accomplish the Service.

3ERVICES�AND�/BJECTS

A server provides services to a client that consist of monitoring and control-ling Switching Sub-Domain objects. TSAPI defines the client application in-terface for monitoring and controlling these objects.

&UNCTIONS

A Domain is the union of a Switching Domain and a Computing Domain. Inother words, it is those switching and computing objects that an applicationcan access. Figure 3-2 shows an example of a Domain. A heavy line dividesthe Domain into Switching and Computing Domains. The Switching Domainconsists of Switching Functions S1, S2, and S3. Similarly, the ComputingDomain consists of Computing Functions C1, C2, and C3. Each Function hasa view of the Domain where it resides. Note that if multiple Functions providean application with the same view, then the Functions are in the same Sub-Domain. TSAPI Applications (shown in Figure 3-2 as "Application Domains")are distributed across at least one Switching Sub-Domain and at least oneComputing Sub-Domain.


Figure 3-2Domains and Sub-Domains

��#OMPUTING�$OMAIN��3WITCHING�$OMAIN

C

SwitchingSub-Domain

SwitchingSub-Domain

Computing

Sub-Domain

ComputingSub-Domain

ApplicationDomains

C

C

S

S

S

43!0)�3WITCHING�3UB $OMAIN�-ODEL

The Switching Sub-Domain Model defines an abstract view of a SwitchingFunction. TSAPI defines several Switching Sub-Domain Model Objects foruse in Application programming, Call, and Connection.

43!0)�$EVICE

A TSAPI application can monitor and control Devices of various types(including telephones). However, a TSAPI application may not be able tomonitor or control all Devices. In CSTA, a Device can refer to either aphysical device (such as buttons, lines, trunks, and stations) or a logical device


(such as groups of devices, pilot numbers, and ACDs). Devices have as-sociated attributes, which allow applications to monitor and control them.

TSAPI Device attributes are:

1. Device Type - A Device has one of the following types:

u !#$� �!N�!UTOMATIC�#ALL�$ISTRIBUTOR��!#$�IS�A�3WITCHING&UNCTION�MECHANISM�THAT�DISTRIBUTES�CALLS�TO�!#$�AGENTS��!N!#$��AS�OPPOSED�TO�!#$�GROUP�CONSISTS�ONLY�OF�THE�DISTRIBUTIONMECHANISM�AND�NOT�THE�!#$�AGENTS��OR�THEIR�$EVICES�TO�WHICHTHE�MECHANISM�CAN�DISTRIBUTE�CALLS�

u ACD group - An Automatic Call Distributor (ACD) group is themechanism that distributes calls within a Switching Function aswell as the ACD agent Devices to which that mechanism distrib-utes calls.

u Button - an instance of a call manipulation point at an individualstation. Simple analog stations often have no physical buttons butbehave as if they have one. Some advanced stations can emulateseveral analog stations and often represent those stations withseveral buttons. In some situations it is desirable to identify agiven button on a multi-button station. Note that a station withseveral line appearance buttons could have either the same tele-phone number or different telephone numbers assigned to thosebuttons.

u Button group - two or more instances of a Button at an individualstation.

u Line - a communications interface to one or more stationstypically associated with a directory number. In some situations itmay be impossible to identify individual stations that share a line(a single directory number).

u Line group - a set of communications interfaces to one or morestations.

u Operator - also known as Attendant, a device used to interact witha party to assist in call setup or to provide othertelecommunications service. This device is different from other

4ELEPHONY�3ERVICES�!0) � ��

devices in that it is often involved in setting up other calls, and isusually not part of the call after the call is connected.

u Operator group - two or more operator devices used inter-changeably or addressed identically.

u Station - the traditional telephone device. A station is a physicalunit of one or more buttons and one or more lines.

u Station group - two or more stations used interchangeably oraddressed identically.

u Trunk - a device that spans switching sub-domains. In order tomonitor and control calls that cross switching sub-domains, it maybe desirable to address the point at which the call crosses theboundary. This point is generally a trunk or trunk group.

u Trunk group - often, many trunks connect to the same place.These trunks are often placed in groups and accessed using asingle identifier. In such a configuration the individual trunks areused interchangeably.

2. Device Class - An application may monitor or control TSAPI Devices inthe various Device Classes in different ways. A Device must belong toone, and may belong to more than one, of the following classes:

u Data - a device that is used to make digital data calls (either cir-cuit switched or packet switched). This class includes computerinterfaces and G4 facsimile machines.

u Image - a device that is used to make digital data calls involvingimaging, or high-speed circuit-switched data in general. This classincludes video telephones and CODECs.

u Voice - a device that is used to make audio calls. This class in-cludes all normal telephones, as well as computer modems and G3facsimile machines.

u Other - a type of device not covered by data, image, or voice.


3. Device Identifier - a TSAPI programming handle for a Device thatallows an application to identify uniquely each device at the API. De-vices are identified using static and/or dynamic identifiers:

u Static Device Identifier - A Static Device Identifier is stable overtime. It remains constant and unique over calls. A Static DeviceIdentifier is typically the dialed number for the Device known byboth the Computing and Switching Functions.

It is sometimes useful for the Switching Function to convert longphone number identifiers to another, usually shorter, static formfor subsequent use in service interaction. An example of thiswould be the transformation of a Public Directory Number to aPrivate Directory Number.

This transformation allows service interactions to be independentof the identification mechanism and allows reduction in theamount of data exchanged. This transformed number is known asa Short Form Static Device Identifier.

Some Switching Functions allow the same dialed number to beassigned to Devices of different types. Thus, a TSAPI applicationmay also need to use the Device Type to uniquely address theDevice.

u Dynamic Device Identifier - A Switching Function may not al-ways make a Static Device Identifier available for every Deviceon a call. This may occur because a static identifier may not beavailable (there is no dialed number identifier for the device), orbecause a dialed number does not unambiguously refer to a singledevice (i.e. a group identifier). In these cases, the SwitchingFunction assigns a Dynamic Device Identifier as a handle for theDevice for the duration of the call. Management of the DynamicDevice Identifier is discussed in a later section, Dynamic IdentifierManagement.

4. Device State - a list of the Connection States for all the calls associatedwith the Device. For information about Connection states see TSAPIConnections later in this chapter.


#ALL

TSAPI applications can monitor and control calls (including call establishmentand release). In certain operations, such as conference and transfer, oneDevice in a Call is replaced with another Device or two Calls merged into asingle Call. In these situations, the TSAPI Call object is maintained as long asthe communications relationship remains across each operation (i.e., the callsurvives transfer, conference, and forwarding operations). TSAPI Call objectattributes are:

1. Call Identifier - a TSAPI programming handle that the SwitchingFunction assigns to each Call. The Call ID may or may not be uniqueamong all calls within a Switching Sub-Domain, but coupled with aDevice ID, the pair will form a unique Connection ID within aSwitching Sub-Domain. To allow reference to a nascent call, the switchwill assign a Call ID before a call is fully established. For example, aswitch will assign a Call ID to an incoming call when the called Deviceis Alerting (the assignment is done before the call is answered).

Certain Services merge multiple calls into a single call. Examples ofsuch TSAPI Services are Transfer and Conference. During operations ofServices that merge multiple calls, the call identifier may change, butthe call continues as a TSAPI object. The management of the callidentifier is described in a later section, Dynamic Identifier Man-agement.

�� #ALL�STATE� �A�LIST�OF�THE�#ONNECTION�STATES�FOR�ALL�THE�$EVICES�THAT�ARE�APART�OF�THE�#ALL�

&OR�SIMPLICITY��COMMON�CALL�STATES�FOR�TWO PARTY�CALLS�HAVE�BEEN�GIVEN�ASINGLE�DESCRIPTIVE�NAME��&OR�EXAMPLE��A�TWO PARTY�CALL�WITH�A#ONNECTION�3TATE�OF��#ONNECTED��AT�ONE�STATION�AND�A�#ONNECTION�3TATEOF��!LERTING��AT�THE�OTHER�HAS�A�#ALL�3TATE�OF��$ELIVERED��4ABLE�� GIVES�THE�MAPPING�OF�DESCRIPTIVE�NAMES�TO�#ONNECTION�3TATE�LISTS�FORTWO PARTY�CALLS��3IMPLE�CALL�STATES�ARE�PROVIDED�AS�SINGLE�VALUES�WHEREAS�UNCOMMON�CALL�STATES�ARE�PROVIDED�AS�A�LIST��&OR�MOREINFORMATION�ON�#ONNECTION�3TATES��SEE�THE�FOLLOWING�SECTION��43!0)#ONNECTIONS��4HE�#ALL�3TATES�SECTION�OF�THIS�CHAPTER�GIVES�FURTHERINFORMATION�ABOUT�#ALL�3TATES�


43!0)�#ONNECTIONS

A Connection is a relationship between a Call and a Device. A TSAPI appli-cation can monitor or control a Connection. For example, TSAPI ServicesHold Call, Reconnect Call, and Clear Call all control Connections. Connec-tions are TSAPI programming objects with the following attributes:

1. Connection Identifier – is a TSAPI handle that is made up of a CallIdentifier and Device Identifier. For a call, there are as many Connec-tion identifiers as there are associated devices. Similarly, for a devicethere are as many Connection identifiers as there are associated calls.The Connection Identifier is unique within a Switching Sub-Domain andwithin a single TSAPI server. A TSAPI application cannot use aConnection Identifier until it has received the identifier from theSwitching Function.

2. Connection State - is the state of a call at a Device. The Connectionstate always refers to a single Call/Device relationship. SnapshotServices report Connection States for Calls and Devices. Monitors re-port Events, which are changes in Connection States for the monitoredentity. Figure 3-3 shows a sample Connection state model. Note thatsince TSAPI is switch-independent, and since switch features vary fromswitch to switch (and therefore interact differently on differentswitches), there is no definitive TSAPI Connection State model to whichall switches comply.


Figure 3-3Sample Connection State Model

Queued

Initiated

Null

Alerting

Failed

HeldConnected

The transitions between states, shown by arrows, form the basis for providingEvent Reports.

The TSAPI Connection states are defined as follows.

u Null - the state where there is no relationship between the call and de-vice.

u Initiated - the state where the device is requesting service. Usually thisresults in the creation of a call. Often this is thought of as the "dialing"state.

u Alerting - the state where a device is alerting (ringing).

u Connected - the state where a device can communicate with otherDevices on a call (cannot be a held call).


u Held - the call is "on hold" at the Device.

u Queued - the state where normal state progression has been stalled. Forexample, a call being processed by an ACD that is waiting for an ACDagent to become available is "queued."

u Failed - the state where normal state progression has been aborted. A"Failed" state can result because of failure to connect to the calling(originator) device, failure to connect the called (destination) device,failure to create the call, and other reasons.

#ALL�3TATUS�%VENT�2EPORTS

The Switching Sub-Domain model is an abstract view of call states andevents. This abstract view is probably more detailed than most applicationsrequire, but it introduces a precise language for describing Event Reports, CallStates, and Service functional descriptions. Connection state changescorrespond to telecommunications signaling at a Device.

ISDN specifications model network access as a distributed state machine.ECMA CSTA borrows from this ISDN model. One part of this access statemachine resides in the Device. There is another similar distributed access statemachine which resides across the ISDN network at the egress device.

Thus, a call can be modeled as a collection of Connection state machines.Network signaling causes changes in the state machines across the network.When signaling occurs, a state change occurs at the affected Connection.

Many simple Connection events are of interest to applications. Certaintelecommunications operations involve changes to many Connections. TSAPIreports these compound events (such as Transfer, Conference and Clear Call)in a single Event Report. Each TSAPI Event Report defines whichConnections have changed state.

43!0)�#ALL�3TATES

A Call State is defined as the list of Connection states for all the Devices in-volved in the call. This list is also called the Compound Call State. Listingthe Connection states can describe any possible call state. However, most callsare often in a small number of widely recognized states.


TSAPI defines those states as the Simple Call States shown in Table 3-1.Note that Simple Call States can differ by the order of the Connection statelist. Alerting-Connected is not equal to Connected-Alerting. The first is theSimple Call State "Received" and the second is "Delivered".

Null can be a known Connection state, so for a "newly created" call it ispossible to have a Call state with only one non-Null Connection (see Table3-1).

For calls with two Connections, Table 3-1 summarizes the Simple Call Statesassigned to the combinations of Connection States. If there is no entry in Table3-1 for the combination of Connection states, then TSAPI provides the list.

For calls with more than two non-Null Connection states, the Call State is acompound call state. TSAPI (at times) simplifies the compound call state byrelating it to a particular device. The Connection State related to a particulardevice in this way is called the Local Connection State. Other ConnectionStates are not differentiated from one another. A three-party conference callthat is on hold at a given Device and connected to the other two devices has aLocal Connection State of "Held" at that given Device.

.OTE


Table 3-1TSAPI Simple Call States

Local Connection State Other Connection State Simple Call state

Alerting Connected Received

Alerting Hold Received-On Hold

Connected Alerting Delivered

Connected Connected Established

Connected Failed Failed

Connected Hold Established-On Hold

Connected Null Originated

Connected Queued Queued

Hold Alerting Delivered-Held

Hold Connected Established-Held

Hold Failed Failed-Held

Hold Queued Queued-Held

Initiated Null Pending

Null Null Null

$YNAMIC�)DENTIFIER�-ANAGEMENT

Since Connection Identifiers comprise a Device ID and a Call ID, propermanagement of Connection Identifiers will, in turn, provide proper man-agement of Dynamic Device Identifiers and Call Identifiers.


The Switching Function provides Connection Identifiers when either a newCall or Device Identifier is needed. When a call is made, the switch provides aConnection Identifier. The switch then provides the Connection ID in anyfollowing Event Reports that pertain to that call. Similarly, the switch providesConnection IDs containing a Device ID for a device involved in a call.

The switch updates identifiers when needed. If a Conference or Transfer(merging two calls) changes a Call ID, then the switch provides Event Reportscontaining Connection IDs that link the old call identifier to the new callidentifier. Similarly, if a Dynamic Device Identifier is changed, the switchprovides new Connection Identifiers for the devices in the call. Both ServiceAcknowledgments and Event Reports may contain information necessary tomanage identifiers.

Identifiers cease to be valid when their context vanishes. If a call ends, its callidentifier is no longer valid. Similarly, if a device is removed from service orfrom a call, its dynamic device identifier becomes invalid. Many EventReports and Services specify when a Connection Identifier has lost or will loseits context.

Identifiers can be reused. Once an identifier has lost its context it may be re-used to identify another object. Most implementations will not reuse identifiersimmediately.

Call and Device Identifiers can be, but are not guaranteed to be, globallyunique. The TSAPI server ensures that the combination of Call and DeviceIdentifier is globally unique within a Switching Sub-Domain. To accomplishthis, compliant PBX drivers ensure that either the call identifier or the deviceidentifier (or both) is globally unique. In many cases, the Connection Identifierrequires the use of both the Call and Device Identifiers to uniquely refer toConnections in a call.


C h a p t e r 4 Control Services

TSAPI provides two kinds of control services: API1 Control Services, orACS, and CSTA Control Services. Applications use ACS to manage theirinteractions with Telephony Services. While most applications will use ACSto access CSTA services, applications that administer PBX drivers use ACS tointerface to the PBX Driver. ACS functions manage the interface, whileCSTA functions (chapters 5 through 9) provide the CSTA services.Applications use ACS to:

u Open an ACS stream for CSTA services.

u Open an ACS stream to do PBX Driver administration.

u Close an ACS stream.

u Block or poll for events.

u Initialize an operating system event notification facility. On a Windows,Windows NT, OS/2, Macintosh, or NetWare client, this initializes anEvent Service Routine (ESR).

u Get a list of available advertised services (PBX Driver Services andPBX Driver administration services).

u Select the TSAPI version for use on the stream.

u Select a private data version for use on the stream

��!N�!0)�IS�AN�!PPLICATION�0ROGRAMMING�)NTERFACE�


Applications use the CSTA Control Services, discussed in the later sections ofthis chapter, to:

u Query for the CSTA Services available on an open ACS Stream

u Query for a list of Devices that CSTA Services can monitor, control orroute for on an open ACS Stream

u Query to determine if CSTA Call/Call Monitoring is available on anopen ACS Stream.

/PENING��#LOSING�AND�!BORTING�AN�!#3�3TREAM

To obtain Telephony Services, an application must open an ACS stream (orsession). This stream establishes a logical link between the application and callprocessing software on the switch. The application requests CSTA services(such as making a call) over the stream. Within a Telephony Server, theTelephony Server module and the PBX Driver module cooperate to provideACS Streams. The Telephony Server also does security checking to ensurethat an application receives CSTA services only for permitted Devices. Eachapplication must open an ACS Stream before it requests any services.

An application should only open one stream per advertised service. Anapplication may open multiple ACS streams to multiple advertised services.As PBX drivers initialize, they register the services that they offer(administrative as well as CSTA) with a Telephony Server. . The system thenadvertises these services to applications. An application opens an ACS Streamto use an advertised service. Each stream carries messages for the applicationto one advertised service. Since the PBX Drivers are switch specific, somedrivers may provide services on a single CTI link, while others provideservices on multiple CTI links. An application cannot correlate advertisedtelephony services with underlying physical CTI links.


Opening an ACS Stream

�� 4HE�APPLICATION�CALLS�ACS/PEN3TREAM��

ACS/PEN3TREAM��IS�A�REQUEST�TO�ESTABLISH�AN�!#3�3TREAM�WITH�A4ELEPHONY�3ERVER��4HE�ACS/PEN3TREAM��FUNCTION�RETURNS�ANACS(ANDLE�TO�THE�APPLICATION��4HE�APPLICATION�WILL�USE�THIS�ACS(ANDLE�TOACCESS�THE�!#3�3TREAM��MAKE�REQUESTS�AND�RECEIVE�EVENTS�

�� 4HE�APPLICATION�RECEIVES�AN�!#3/PEN3TREAM#ONF%VENT�EVENTMESSAGE�THAT�CORRESPONDS�TO�THE�ACS/PEN3TREAM��REQUEST�

4HE�APPLICATION�MONITORS�THE�ACS(ANDLE��RETURNED�FROM�THEACS/PEN3TREAM��REQUEST�FOR�THE�CORRESPONDING!#3/PEN3TREAM#ONF%VENT ��4HE�APPLICATION�SHOULD�NOT�REQUESTSERVICES�ON�THE�!#3�3TREAM�UNTIL�IT�RECEIVES�THIS�CORRESPONDING!#3/PEN3TREAM#ONF%VENT �

After an application successfully receives the ACSOpenStreamConfEvent, itmay request CSTA Services such as Device (telephone) monitoring.

The application should always check the ACSOpenStreamConfEvent toensure that the ACS Stream has been successfully established before makingany CSTA Service requests.

An application is responsible for releasing its ACS Stream(s). To release thesystem resources associated with an ACS Stream, the application may eitherclose the stream or abort the stream. Failing to release the resources maycorrupt the client system, resulting in client failure.

An acsHandle is a local process identifier and should not be shared acrossprocesses.

Closing an ACS Stream

�� 4HE�APPLICATION�CALLS�ACS#LOSE3TREAM��TO�INITIATE�THE�ORDERLYSHUTDOWN�OF�AN�!#3�3TREAM�

!FTER�THE�APPLICATION�CALLS�ACS#LOSE3TREAM��TO�CLOSE�AN�!#3�3TREAM�THE�APPLICATION�MAY�NOT�REQUEST�ANY�FURTHER�SERVICES�ON�THAT�3TREAM��4HE

123

123


ACS#LOSE3TREAM��FUNCTION�IS�A�NON BLOCKING�CALL��4HE�APPLICATIONPASSES�AN�ACS(ANDLE�INDICATING�WHICH�!#3�3TREAM�TO�CLOSE��!LTHOUGHTHE�APPLICATION�CANNOT�MAKE�REQUESTS�ON�THAT�3TREAM��THE�ACS(ANDLEREMAINS�VALID�UNTIL�THE�APPLICATION�RECEIVES�THE�CORRESPONDING!#3#LOSE3TREAM#ONF%VENT�

After an application calls acsCloseStream( ), it may still receive eventson the acsHandle for that ACS Stream. The application must continue topoll until it receives the ACSCloseStreamConfEvent so that the systemreleases all stream resources. The stream remains open until theapplication receives the ACSCloseStreamConfEvent.

�� 4HE�APPLICATION�RECEIVES�AN�!#3#LOSE3TREAM#ONF%VENT�EVENTMESSAGE�THAT�CORRESPONDS�TO�THE�ACS#LOSE3TREAM��REQUEST�

!N�!#3#LOSE3TREAM#ONF%VENT�INDICATES�THAT�THE�ACS(ANDLE�FOR�THE3TREAM�IS�NO�LONGER�VALID�AND�THAT�THE�SYSTEM�HAS�FREED�ALL�SYSTEMRESOURCES�ASSOCIATED�WITH�THE�!#3�3TREAM��4HE�LAST�EVENT�THE�APPLICATIONWILL�RECEIVE�ON�THE�!#3�3TREAM�IS�THE�!#3#LOSE3TREAM#ONF%VENT �#LOSING�AN�!#3�3TREAM�TERMINATES�ANY�#34!�CALL�CONTROL�SESSIONS�ONTHAT�3TREAM��4ERMINATING�#34!�CALL�CONTROL�SESSIONS�IN�THIS�WAY�DOESNOT�AFFECT�THE�SWITCH�PROCESSING�OF�CONTROLLED�CALLS��4HE�APPLICATION�CANNO�LONGER�CONTROL�THEM�ON�THIS�3TREAM�

Aborting an ACS Stream

�� 4HE�APPLICATION�CALLS�ACS!BORT3TREAM��

!N�APPLICATION�MAY�USE�ACS!BORT3TREAM��TO�UNILATERALLY��ANDSYNCHRONOUSLY�TERMINATE�AN�!#3�3TREAM�WHEN

u it does not require confirmation of successful Stream closure, and

u it does not need to receive any events that may be queued for it onthat Stream.

4HE�APPLICATION�PASSES�AN�ACS(ANDLE�INDICATING�WHICH�!#3�3TREAM�TOABORT��4HE�ACS!BORT3TREAM��FUNCTION�IS�NON BLOCKING�AND�RETURNS�TOTHE�APPLICATION�IMMEDIATELY��7HEN�ACS!BORT3TREAM��RETURNS��THEACS(ANDLE�IS�INVALID��UNLIKE�ACS#LOSE3TREAM��4HE�SYSTEM�FREES�ALLRESOURCES�ASSOCIATED�WITH�THE�ABORTED�!#3�3TREAM��INCLUDING�ANY�EVENTSQUEUED�ON�THIS�3TREAM��!BORTING�AN�!#3�3TREAM�TERMINATES�ANY�#34!

123


CALL�CONTROL�ON�THAT�3TREAM��!BORTING�#34!�CALL�CONTROL�IN�THIS�WAY�DOESNOT�AFFECT�THE�SWITCH�PROCESSING�OF�CONTROLLED�CALLS��)T�TERMINATES�THEAPPLICATION�S�CONTROL�OF�THEM�ON�THIS�3TREAM��4HERE�IS�NO�CONFIRMATIONEVENT�FOR�AN�ACS!BORT3TREAM��CALL�

3ENDING�#34!�2EQUESTS�AND�2ESPONSES

After an application opens an ACS Stream (including reception of theACSOpenStreamConfEvent) it may request CSTA services and receiveevents. In each service request, the application passes the acsHandle of theStream over which it is making the request.

Each service request requires an invokeID that the system will return in theconfirmation event (or failure event) for the function call. Since applicationsmay have multiple requests for the same service outstanding within the sameACS Stream, invokeIDs provide a way to match the confirmation event (orfailure event) to the corresponding request. When an application opens anACS Stream, it specifies (for that Stream) whether it will:

u specify whether it will generate and manage invokeIDs internally, or

u have the TSAPI library generate unique invokeID for each servicerequest.

Once an application specifies this invokeID type for an ACS stream, theapplication cannot change invokeID type for the stream.

In general, having the TSAPI library generate unique invokeIDs simplifiesapplication design. However, when service requests correspond to entries in adata structure, it may simplify application design to use indexes into the datastructure as invokeIDs. Application-generated invokeIDs might also point towindow handles. Application-generated invokeIDs may take on any 32-bitvalue.

Telephony Services API 4-6

Receiving Events

When an application successfully opens an ACS Stream, the TSAPI Libraryqueues the ACSOpenStreamConfEvent event message for the application.To receive this event, and subsequent event messages, the application must useone of two event reception methods:

u a blocking mode, which blocks the application from executing until anevent becomes available. Blocking is appropriate in threaded orpreemptive operating system environments only (e.g., Windows NT,Novell, etc.).

u a non-blocking mode that returns control to the application regardless ofwhether an event is available.

Blocking on event reports may be appropriate for applications that monitor aDevice and only require processing cycles when an event occurs. However,there may be operating system specific implications. For example, if aWindows application blocks waiting for CSTA events, then it cannot processevents from its Windows event queue.

Regardless of the mode that an application uses to receive events, it may electto receive an event either from a designated ACS Stream (that it opened) orfrom any ACS Stream (that it has opened). TSAPI gives the application theevents in chronological order from the selected Stream(s). Thus, if theapplication receives events from all ACS Streams, then it receives the eventsin chronological order from all the Streams.

Blocking Event Reception

1. The application calls acsGetEventBlock( )

acsGetEventBlock( ) function gets the next event or blocks if no eventsare available. The application passes an acsHandle parameter containingthe handle of an open ACS Stream or a zero value (indicating that itdesires events from any open ACS Stream).

2. acsGetEventBlock( ) returns when an event is available.

123


Non-Blocking Event Reception

�� 4HE�APPLICATION�CALLS�ACS'ET%VENT0OLL��

!PPLICATIONS�USE�ACS'ET%VENT0OLL��TO�POLL�FOR�EVENTS�AT�THEIR�OWNPACE��!N�APPLICATION�CALLS�ACS'ET%VENT0OLL��ANY�TIME�IT�WANTS�TOPROCESS�AN�EVENT��4HE�APPLICATION�PASSES�AN�ACS(ANDLE�CONTAINING�THEHANDLE�OF�AN�OPEN�!#3�3TREAM�OR�A�ZERO�VALUE��INDICATING�THAT�IT�DESIRESEVENTS�FROM�ANY�OPEN�!#3�3TREAM��)N�ADDITION��THE�NUMEVENTSPARAMETER�TELLS�THE�APPLICATION�HOW�MANY�EVENTS�ARE�ON�THE�QUEUE�

�� ACS'ET%VENT0OLL��RETURNS�IMMEDIATELY

A� )F�ONE�OR�MORE�EVENTS�ARE�AVAILABLE�ON�THE�!#3�3TREAM�ACS'ET%VENT0OLL��RETURNS�THE�NEXT�EVENT�FROM�THE�SPECIFIED3TREAM��OR�FROM�ANY�3TREAM��IF�THE�APPLICATION�SELECTED�THATOPTION�

B� 7HEN�THE�EVENT�QUEUE�IS�EMPTY��THE�FUNCTION�RETURNS�IMMEDIATELYWITH�A��NO�MESSAGE��INDICATION�

The application must receive events (using either the blocking or pollingmethod) frequently enough so that the event queue does not overflow . TSAPIwill stop acknowledging messages from the Telephony Server when the queuefills up, ultimately resulting in a loss of the stream. When a message isavailable, it does not matter which function an application uses to retrieve it.

In some operating system environments (Windows, Windows NT, OS/2,Macintosh, NetWare), an application can use an Event Service Routine (ESR)to receive asynchronous notification of arriving events. The ESR mechanismnotifies the application of arriving events. It does not remove the events fromthe event queue. The application must use acsGetEventBlock( ),acsGetEventPoll( ), or eventNotify( ) to receive the message. The applicationcan use an ESR to trigger a specific action when an event arrives in the eventqueue (i.e. post a Windows message for the application, or signal asemaphore in the NetWare environment). See the manual page foracsSetESR( ) for more information about ESR use in specific operatingsystem environments.

123


TSAPI makes one other event handling function available to applications:acsFlushEventQueue( ). An application uses acsFlushEventQueue( ) toflush all events from an ACS Stream event queue (or, if the applicationselects, from all ACS Stream event queues).

43!0)�6ERSION�#ONTROL

As TSAPI evolves over time to support more services, TSAPI will includenew functions and event reports. Similarly, PBX driver manufacturers willenhance their private data over time. To ensure that applications written toearlier versions of the system will continue to operate with newer TSAPIlibraries and newer PBX drivers, TSAPI provides Version Control.

An application provides a list of the TSAPI versions that it is willing to acceptin the apiVer parameter of the acsOpenStream( ) function. This parametercontains a string beginning with the characters “TS” followed by an ASCIIencoding of one or more version numbers. An application may use the “-”(hyphen) character to specify a range of versions and the “:” (colon) characterto separate a list of versions. For example, the string “TS1-3:5” specifies thatthe application is willing to accept TSAPI versions 1, 2, 3, or 5.

As the system processes the open stream request, each system componentchecks to see which of the requested versions it supports. If a componentcannot support a requested version, it removes that version from the listbefore passing the request on to the next component. The system opens thestream using the highest (latest) TSAPI version remaining and returns thatversion to the application in the ACSOpenStreamConfEvent. Once a streamis opened, the version is fixed for the duration of the stream. If the systemcannot find a suitable version, the open stream request fails and the applicationreceives an ACSUniversalFailureConfEvent.

The system returns the selected TSAPI version in the apiVer field of theACSOpenStreamConfEvent. The version begins with the letters “ST” (the“S” and the “T” are intentionally reversed) followed by a single TSAPIversion number. If the contents of the apiVer field do not begin with theletters “ST”, then the application should assume TSAPI version 1.


A set of function calls and events comprise a TSAPI version. New TSAPIfunctions are given new names, and new events are assigned new event typevalues. It is the programmer’s responsibility to ensure that the program usesonly TSAPI functions from the appropriate version set.

Releases 2.10 and 2.21 of Telephony Services provide two TSAPI versions:“TS1” and “TS2”.

Versions also exist on a stream-type basis. In Releases 2.10 and 2.21, whilethere are two TSAPI stream versions (“TS1” and “TS2”), there is a singleOAM stream version, version “TS1”.

0RIVATE�$ATA�6ERSION�#ONTROL

Private Data versions allow an application to request specific version(s) of aspecific vendor(s) private data. The application can also specify that a PBXDriver is not to provide any private data and thereby save the LAN bandwidththat the private data will consume.

Although similar in format to the TSAPI version negotiation, the Private Dataversion negotiation is independent.

To request specific version(s) of specific vendor(s) private data, an applicationpasses negotiation information in the private data of acsOpenStream( ). Toindicate that the private data is to negotiate the version, the application sets thevendor field in the Private Data structure to the null-terminated string“VERSION”. The application specifies the acceptable vendor(s) andversion(s) in the data field of the private data. The data field contains a onebyte manifest constant PRIVATE_DATA_ENCODING followed by a null-terminated ASCII string containing a list of vendors and versions. The stringcontains vendor/version pairs with the “#” character separating the vendor andversion. The “#” character also delimits the vendor/version pairs. The “:” and“-” characters are used as they are for TSAPI version negotiation. Forexample, the string “VENDORA#1-3#VENDORB#1:3-5” indicates that theapplication requests VENDORA private data versions 1, 2, or 3; or,VENDORB private data versions 1, 3, 4, or 5.


The Private Data in the ACSOpenStreamConfEvent indicates what vendorand version Private Data the PBX driver will provide on the stream. In thePrivate Data, the vendor field will contain the vendor name and the data fieldin the Private_Data_t structure contains a one byte discriminatorPRIVATE_DATA_ENCODING followed by an ASCII string identifying theversion of the private data that will be supplied.

An application that does not use Private Data should not pass any private datato the acsOpenStream( ) request. Drivers that do private data versionnegotiation interpret the lack of private data in the open stream request tomean that the application does not want private data. They will then refrainfrom sending private data on that stream, thereby saving the LAN bandwidththat the private data would otherwise consume. Applications that do not sendany private data in acsOpenStream( ) must be prepared to receive privatedata since they may request service from a PBX Driver that does not doprivate data version negotiation.

1UERYING�FOR�!VAILABLE�3ERVICES

Applications can use the acsEnumServerNames( ) function to obtain a list ofthe advertised service names. The presence of an advertised service name inthe list does not mean that it is available.


!0)�#ONTROL�3ERVICES��!#3�&UNCTIONS�AND�#ONFIRMATION%VENTS

This section defines the ACS function calls and their confirmation events.Applications use these functions to open ACS streams and to and manageevents on ACS Streams between client workstations and the TelephonyServer.


ACS/PEN3TREAM��

An application uses acsOpenStream( ) to open an ACS stream to anadvertised service. An application needs an ACS stream to access other ACSControl Services or CSTA Services. Thus, an application must callacsOpenStream( ) before requesting any other ACS or CSTA service.acsOpenStream( ) immediately returns an acsHandle; a confirmation eventarrives later.

3YNTAX

�INCLUDE��ACS�H��INCLUDE��CSTA�H�

2ET#ODE?T�ACS/PEN3TREAM�!#3(ANDLE?T ACS(ANDLE� ��2%452.��)NVOKE)$4YPE?T INVOKE)$4YPE� ��).054��)NVOKE)$?T INVOKE)$� ��).054��3TREAM4YPE?T STREAM4YPE� ��).054��3ERVER)$?T SERVER)$� ��).054��,OGIN)$?T LOGIN)$� ��).054��0ASSWD?T PASSWD� ��).054��!PP.AME?T APPLICATION.AME� ��).054��,EVEL?T ACS,EVEL2EQ ��).054��6ERSION?T API6ER� ��).054��UNSIGNED�SHORT SEND13IZE� ��).054��UNSIGNED�SHORT SEND%XTRA"UFS� ��).054��UNSIGNED�SHORT RECV13IZE� ��).054��UNSIGNED�SHORT RECV%XTRA"UFS ��).054��0RIVATE$ATA?T PRIVATE$ATA� ��).054��

Parameters

acsHandleACS/PEN3TREAM��RETURNS�THIS�VALUE�THAT�IDENTIFIES�THE�!#3�3TREAMTHAT�WAS�OPENED��43!0)�SETS�THIS�VALUE�SO�THAT�IT�IS�UNIQUE�TO�THE�!#33TREAM��/NCE�ACS/PEN3TREAM��IS�SUCCESSFUL��THE�APPLICATION�MUSTUSE�THIS�ACS(ANDLE�IN�ALL�OTHER�FUNCTION�CALLS�TO�43!0)�ON�THISSTREAM��)F�ACS/PEN3TREAM��IS�SUCCESSFUL��43!0)�GUARANTEES�THATTHE�APPLICATION�HAS�A�VALID�ACS(ANDLE��)F�ACS/PEN3TREAM��IS�NOTSUCCESSFUL��THEN�THE�FUNCTION�RETURN�CODE�GIVES�THE�CAUSE�OF�THEFAILURE�


invokeIDType4HE�APPLICATION�SETS�THE�TYPE�OF�INVOKE�IDENTIFIERS�USED�ON�THE�STREAMBEING�OPENED�

4HE�POSSIBLE�TYPES�ARE��!PPLICATION 'ENERATED�INVOKE)$S�!00?'%.?)$�OR�,IBRARY�GENERATED�INVOKE)$S��,)"?'%.?)$�

7HEN�!00?'%.?)$�IS�SELECTED�THEN�THE�APPLICATION�WILL�PROVIDE�ANINVOKE)$�WITH�EVERY�43!0)�FUNCTION�CALL�THAT�REQUIRES�AN�INVOKE)$�43!0)�WILL�RETURN�THE�SUPPLIED�INVOKE)$�VALUE�TO�THE�APPLICATION�INTHE�CONFIRMATION�EVENT�FOR�THE�SERVICE�REQUEST��!PPLICATION GENERATEDINVOKE)$�VALUES�CAN�BE�ANY�� BIT�VALUE�

7HEN�,)"?'%.?)$�IS�SELECTED��THE�!#3�,IBRARY�WILL�AUTOMATICALLYGENERATE�AN�INVOKE)$�AND�WILL�RETURN�ITS�VALUE�UPON�SUCCESSFULCOMPLETION�OF�THE�FUNCTION�CALL��4HE�VALUE�WILL�BE�THE�RETURN�FROM�THEFUNCTION�CALL��2ET#ODE?T��,IBRARY GENERATED�INVOKE�)$S�ARE�ALWAYSIN�THE�RANGE��TO��

invokeID4HE�APPLICATION�SUPPLIES�THIS�HANDLE�FOR�MATCHING�THEACS/PEN3TREAM��SERVICE�REQUEST�WITH�ITS�CONFIRMATION�EVENT��!NAPPLICATION�SUPPLIES�A�VALUE�FOR�INVOKE)$�ONLY�WHEN�THE�INVOKE)$TYPEPARAMETER�IS�SET�TO�!00?'%.?)$��43!0)�IGNORES�THE�INVOKE)$PARAMETER�WHEN�INVOKE)$TYPE�PARAMETER�IS�SET�TO�,)"?'%.?)$�

streamType4HE�APPLICATION�PROVIDES�THE��TYPE�OF�STREAM�IN�STREAM4YPE��4HEPOSSIBLE�VALUES�ARE�

34?#34!� � REQUESTS� A� #34!� CALL� CONTROL� STREAM�� 4HISSTREAM� CAN� BE� USED� FOR� 43!0)� SERVICE� REQUESTS� ANDRESPONSES�WHICH�BEGIN�WITH�THE�PREFIX��CSTA��OR��#34!��

34?/!-� �REQUESTS�AN�/!-�STREAM�

serverID4HE�APPLICATION�PROVIDES�A�NULL TERMINATED�STRING�OF�MAXIMUM�SIZE!#3?-!8?3%26)#%)$��4HIS�STRING�CONTAINS�THE�NAME�OF�ANADVERTISED�SERVICE��IN�!3#))�FORMAT��4HE�APPLICATION�MUST�ENSURETHAT�THE�SERVER)$�PROVIDES�SERVICES�OF�THE�TYPE�GIVEN�IN�THESTREAM4YPE�PARAMETER�


loginID4HE�APPLICATION�PROVIDES�A�POINTER�TO�A�NULL�TERMINATED�STRING�OFMAXIMUM�SIZE�!#3?-!8?,/').)$��4HIS�STRING�CONTAINS�THELOGIN�)$�OF�THE�USER�REQUESTING�ACCESS�TO�THE�ADVERTISED�SERVICE�GIVENIN�THE�SERVICE)$�PARAMETER�

passwd4HE�APPLICATION�PROVIDES�A�POINTER�TO�A�NULL�TERMINATED�STRING�OFMAXIMUM�SIZE�!#3?-!8?0!337/2$��4HIS�STRING�CONTAINS�THEPASSWORD�OF�THE�USER�GIVEN�LOGIN)$�

applicationName4HE�APPLICATION�PROVIDES�A�POINTER�TO�A�NULL�TERMINATED�STRING�OFMAXIMUM�SIZE�!#3?-!8?!00.!-%��4HIS�STRING�CONTAINS�ANAPPLICATION�NAME��4HE�SYSTEM�USES�THE�APPLICATION�NAME�ON�CERTAINADMINISTRATION�AND�MAINTENANCE�STATUS�DISPLAYS�

acsLevelReq4HIS�VERSION�OF�43!0)�IGNORES�THIS�PARAMETER�

apiVer!N�APPLICATION�GIVES�THE�VERSION�OF�43!0)�THAT�IT�DESIRES�IN�API6ER�

4HIS�PARAMETER�CONTAINS�A�STRING�BEGINNING�WITH�THE�CHARACTERS� 43FOLLOWED�BY�AN�!3#))�ENCODING�OF�ONE�OR�MORE�VERSION�NUMBERS��!NAPPLICATION�MAY�USE�THE� ��HYPHEN�CHARACTER�TO�SPECIFY�A�RANGE�OFVERSIONS�AND�THE� � ��COLON�CHARACTER�TO�SEPARATE�A�LIST�OF�VERSIONS�&OR�EXAMPLE��THE�STRING� 43� �� SPECIFIES�THAT�THE�APPLICATION�ISWILLING�TO�ACCEPT�43!0)�VERSIONS��OR��3EE�THE�PRECEDING43!0)�6ERSION�#ONTROL�SECTION�FOR�MORE�INFORMATION�ABOUT�VERSIONNEGOTIATION�

2ELEASES��AND��OF�4ELEPHONY�3ERVICES�SUPPORT�VERSIONS43� �AND� 43� �ON�#34!�STREAMS�AND�VERSION� 43� �ON�/!-STREAMS�

2ELEASE��APPLICATIONS�SHOULD�SUPPLY�THE�6ERSION��VALUE�FOR#34!?!0)?6%23)/.�IN�THE�6ERSION��CSTA�H�HEADER�FILE�INAPI6ER�


sendQSize4HE�APPLICATION�SPECIFIES�IN�SEND13IZE�THE�MAXIMUM�NUMBER�OFOUTGOING�MESSAGES�THE�43!0)�#LIENT�,IBRARY�WILL�QUEUE�BEFORERETURNING�!#3%22?15%5%?&5,,��)F�THE�APPLICATION�SUPPLIES�AZERO��VALUE��THEN�A�DEFAULT�QUEUE�SIZE�WILL�BE�USED��4HE�5NIX7ARE43!0)�CLIENT�LIBRARY�DOES�NOT�USE�THE�SEND13IZE�PARAMETER�

sendExtraBufs4HE�APPLICATION�SPECIFIES�THE�NUMBER�OF�ADDITIONAL�PACKET�BUFFERS43!0)�ALLOCATES�FOR�THE�SEND�QUEUE��)F�SEND%XTRA"UFS�IS�SET�TO�ZERO��THE�NUMBER�OF�BUFFERS�IS�EQUAL�TO�THE�QUEUE�SIZE��I�E��ONE�BUFFERPER�MESSAGE��)F�MESSAGES�WILL�EXCEED�THE�SIZE�OF�A�NETWORK�PACKET�AS�IN�THE�CASE�WHERE�PRIVATE�DATA�IS�USED�EXTENSIVELY��OR�THEAPPLICATION�FREQUENTLY�SEES�THE�!#3%22?./"5&&%23�ERROR��THENTHE�APPLICATION�DOES�NOT�USE�SEND%XTRA"UF�TO�ALLOCATE�ENOUGH�BUFFERS�4HE�5NIX7ARE�43!0)�CLIENT�LIBRARY�DOES�NOT�USE�THE�SEND%XTRA"UFSPARAMETER�

recvQSize4HE�APPLICATION�SPECIFIES�THE�MAXIMUM�NUMBER�OF�INCOMINGMESSAGES�THE�43!0)�#LIENT�,IBRARY�QUEUES�BEFORE�IT�CEASESACKNOWLEDGMENT�TO�THE�4ELEPHONY�3ERVER��43!0)�USES�A�DEFAULTQUEUE�SIZE�WHEN�RECV13IZE�IS�SET�TO�ZERO��4HE�5NIX7ARE�43!0)CLIENT�LIBRARY�DOES�NOT�USE�THE�RECV13IZE�PARAMETER�

recvExtraBufs4HE�APPLICATION�SPECIFIES�THE�NUMBER�OF�ADDITIONAL�PACKET�BUFFERS�THAT43!0)�ALLOCATES�FOR�THE�RECEIVE�QUEUE��)F�RECV%XTRA"UFS�IS�SET�TO�ZERO��THE�NUMBER�OF�BUFFERS�IS�EQUAL�TO�THE�QUEUE�SIZE��I�E��ONE�BUFFERPER�MESSAGE��)F�MESSAGES�WILL�EXCEED�THE�SIZE�OF�A�NETWORK�PACKET�AS�IN�THE�CASE�WHERE�PRIVATE�DATA�IS�USED�EXTENSIVELY��OR�THEAPPLICATION�FREQUENTLY�SEES��!#3%22?342%!-?&!),%$��THENTHE�APPLICATION�DOES�NOT�USE�RECV%XTRA"UFS�TO�ALLOCATE�ENOUGHBUFFERS��4HE�5NIX7ARE�43!0)�CLIENT�LIBRARY�DOES�NOT�USE�THERECV%XTRA"UFS�PARAMETER�


privateData4HE�APPLICATION�MAY�PROVIDE�A�POINTER�TO�A�DATA�STRUCTURE�THATCONTAINS�ANY�IMPLEMENTATION SPECIFIC��0"8�$RIVER�SPECIFICINITIALIZATION��43!0)�DOES�NOT�INTERPRET�THE�DATA�IN�THIS�STRUCTURE�3OME�0"8�$RIVERS�MAY�USE�0RIVATE�$ATA�AS�AN� ESCAPE�MECHANISMTO�PROVIDE�IMPLEMENTATION�SPECIFIC�INFORMATION�BETWEEN�THEAPPLICATION�AND�THE�0"8�$RIVER��!N�APPLICATION�GIVES�A�.5,,POINTER�WHEN�0RIVATE�$ATA�IS�NOT�PRESENT�

)N�AN�OPEN�STREAM�REQUEST��AN�APPLICATION�MAY�USE�THE�PRIVATE�DATA�TONEGOTIATE�A�SPECIFIC�VERSION�S�OF�A�SPECIFIC�VENDOR�S�PRIVATE�DATA�ONTHE�STREAM�

4O�INDICATE�THAT�THE�PRIVATE�DATA�IS�TO�NEGOTIATE�THE�VERSION��THEAPPLICATION�SETS�THE�VENDOR�FIELD�IN�THE�0RIVATE$ATA�STRUCTURE�TO�THENULL TERMINATED�STRING� 6%23)/. ��4HE�APPLICATION�SPECIFIES�THEACCEPTABLE�VENDOR�S�AND�VERSION�S�IN�THE�DATA�FIELD�OF�THE�PRIVATEDATA��4HE�DATA�FIELD�CONTAINS�A�ONE�BYTE�MANIFEST�CONSTANT02)6!4%?$!4!?%.#/$).'�FOLLOWED�BY�A�NULL�TERMINATED!3#))�STRING�CONTAINING�A�LIST�OF�VENDORS�AND�VERSIONS��4HE�STRINGCONTAINS�VENDOR�VERSION�PAIRS�WITH�THE� � �CHARACTER�SEPARATING�THEVENDOR�AND�VERSION��4HE� � �CHARACTER�ALSO�DELIMITS�THEVENDOR�VERSION�PAIRS��4HE� � �AND� �CHARACTERS�ARE�USED�AS�THEY�AREFOR�43!0)�VERSION�NEGOTIATION��&OR�EXAMPLE��THE�STRING6%.$/2!�� 6%.$/2"�� INDICATES�THAT�THE�APPLICATIONREQUESTS�6%.$/2!�PRIVATE�DATA�VERSIONS��OR��OR��6%.$/2"PRIVATE�DATA�VERSIONS��OR��.O�PRIVATE�DATA�ON�AN�OPEN�STREAMREQUEST�IS�A�REQUEST�TO�THE�0"8�DRIVER�NOT�TO�SEND�ANY�PRIVATE�DATA�/NLY�THOSE�0"8�DRIVERS�THAT�SUPPORT�PRIVATE�DATA�VERSION�NEGOTIATIONWILL�HONOR�THIS�REQUEST�

3EE�THE�PRECEDING�0RIVATE�$ATA�6ERSION�#ONTROL�SECTION�FORINFORMATION�ON�PRIVATE�DATA�VERSION�NEGOTIATION�

Return Values

ACS/PEN3TREAM��RETURNS�THE�FOLLOWING�VALUES�DEPENDING�ONWHETHER�THE�APPLICATION�IS�USING�LIBRARY�OR�APPLICATION GENERATEDINVOKE�IDENTIFIERS�


Library-generated invokeIDs - if the function call completessuccessfully it will return a positive value, i.e. the invokeidentifier. If the call fails a negative error (<0) condition willbe returned. For library-generated identifiers the return willnever be zero (0).

Application-generated invokeIDs - if the function callcompletes successfully it will return a zero (0) value. If thecall fails a negative error (<0) condition will be returned.For application-generated identifiers the return will never bepositive (>0).

!N�APPLICATION�SHOULD�ALWAYS�CHECK�THE!#3/PEN3TREAM#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�4ELEPHONY3ERVER�HAS�ACKNOWLEDGED�THE�ACS/PEN3TREAM��REQUEST�

ACS/PEN3TREAM��RETURNS�THE��NEGATIVE�ERROR�CONDITIONS�BELOW�

!#3%22?!0)6%2$%.)%$4HE�REQUESTED�!0)�VERSION��API6ER�IS�INVALID�OR�THE�CLIENTLIBRARY�DOES�NOT�SUPPORT�IT�

!#3%22?"!$0!2!-%4%2/NE�OR�MORE�OF�THE�PARAMETERS�IS�INVALID�

!#3%22?./$2)6%2.O�43!0)�#LIENT�,IBRARY�$RIVER�WAS�FOUND�OR�INSTALLED�ONTHE�SYSTEM�

!#3%22?./3%26%24HE�ADVERTISED�SERVICE��SERVER)$�IS�NOT�AVAILABLE�IN�THENETWORK�

!#3%22?./2%3/52#%4HERE�ARE�INSUFFICIENT�RESOURCES�TO�OPEN�A�!#3�3TREAM�


Comments

!N�APPLICATION�USES�ACS/PEN3TREAM��TO�OPEN�A�NETWORK�OR�LOCALCOMMUNICATION�CHANNEL��!#3�3TREAM�WITH�AN�ADVERTISED�SERVICE�0"8�$RIVER��4HE�STREAM�WILL�ESTABLISH�AN�!#3�CLIENT�SERVER�SESSIONBETWEEN�THE�APPLICATION�AND�THE�SERVER��4HE�APPLICATION�CAN�USE�THE!#3�STREAM�TO�ACCESS�ALL�THE�SERVER PROVIDED�SERVICES��E�G��FOR�ATYPICAL�0"8�$RIVER�THIS�WOULD�INCLUDE�CSTA-AKE#ALL�CSTA4RANSFER#ALL��ETC��ACS/PEN3TREAM��RETURNS�AN�ACS(ANDLE�FORTHE�STREAM��4HE�APPLICATION�USES�THE�ACS(ANDLE�TO�WAIT�FOR�A!#3/PEN3TREAM#ONF%VENT�� 4HE�APPLICATION�USES�THE!#3/PEN3TREAM#ONF%VENT� TO�DETERMINE�WHETHER�THE�STREAMOPENED�SUCCESSFULLY��4HE�APPLICATION�THEN�USES�THE�ACS(ANDLE�IN�ANYFURTHER�REQUESTS�THAT�IT�SENDS�OVER�THE�STREAM��!N�APPLICATION�SHOULDONLY�OPEN�ONE�STREAM�FOR�ANY�ADVERTISED�SERVICE�

7HEN�AN�APPLICATION�CALLS�ACS/PEN3TREAM��THE�CALL�MAY�BLOCK�FORUP�TO�TEN��SECONDS�WHILE�43!0)�OBTAINS�NAMES�AND�ADDRESSESFROM�THE�NETWORK�.AME�3ERVER�

!PPLICATIONS�SHOULD�NOT�OPEN�MULTIPLE�STREAMS�TO�THE�SAME�ADVERTISEDSERVICE�SINCE�THIS�RESULTS�IN�INEFFICIENT�USE�OF�SYSTEM�RESOURCES�

The UnixWare TSAPI client library does not use the sendQsize,sendExtraBufs, recvQsize, or recvExtraBufs parameters.

Application Notes

!�4ELEPHONY�3ERVER�ADVERTISES�SERVICES�FOR�EACH�REGISTERED�0"8$RIVER��!�0"8�$RIVER�MAY�SUPPORT�A�SINGLE�#4)�LINK�OR�MULTIPLE�#4)LINKS��%ACH�ADVERTISED�SERVICE�NAME�IS�UNIQUE�ON�THE�NETWORK�

43!0)�GUARANTEES�THAT�THE�!#3/PEN3TREAM#ONF%VENT� IS�THE�FIRSTEVENT�THE�APPLICATION�WILL�RECEIVE�ON�!#3�3TREAM�IF�NO�ERRORSOCCURRED�DURING�THE�!#3�3TREAM�INITIALIZATION�PROCESS�

4HE�APPLICATION�IS�RESPONSIBLE�FOR�TERMINATING�!#3�STREAMS��4O�DOSO��AN�APPLICATION�EITHER�CALLS�ACS#LOSE3TREAM��AND�RECEIVES�THE!#3#LOSE3TREAM#ONF%VENT��OR�CALLS�ACS!BORT3TREAM��)T�ISIMPERATIVE�THAT�AN�APPLICATION�CLOSE�ALL�ACTIVE�STREAM�S�DURING�ITS�EXITOR�CLEANUP�ROUTINE�IN�ORDER�TO�FREE�RESOURCES�IN�THE�CLIENT�AND�SERVERFOR�OTHER�APPLICATIONS�ON�THE�NETWORK�

.OTE


4HE�APPLICATION�MUST�BE�PREPARED�TO�RECEIVE�AN!#35NIVERSAL&AILURE#ONF%VENT� �FOR�ANY�STREAM�TYPE�#34!5NIVERSAL&AILURE#ONF%VENT ��FOR�A�#34!�STREAM�TYPE�OR�AN!#35NIVERSAL&AILURE%VENT��FOR�ANY�STREAM�TYPE�ANYTIME�AFTER�THEACS/PEN3TREAM��FUNCTION�COMPLETES��4HESE�EVENTS�INDICATE�THAT�AFAILURE�HAS�OCCURRED�ON�THE�STREAM�


!#3/PEN3TREAM#ONF%VENT

This event is generated in response to the acsOpenStream( ) function andprovides the application with status information regarding the requested openof an ACS Stream with the Telephony Server. The application may onlyperform the ACS functions acsEventNotify( ), acsSetESR( ),acsGetEventBlock( ), acsGetEventPoll( ), and acsCloseStream( ) on anacsHandle until this confirmation event has been received.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�SECTION��!#3�$ATA�4YPES�AND��#34!�$ATA�4YPES�FOR�A�MORE�COMPLETE�DESCRIPTION�OF�THE�EVENTSTRUCTURE�

TYPEDEF�STRUCT[

!#3(ANDLE?T ACS(ANDLE�%VENT#LASS?T EVENT#LASS�%VENT4YPE?T EVENT4YPE�

]�!#3%VENT(EADER?T�

TYPEDEF�STRUCT[

!#3%VENT(EADER?T EVENT(EADER�UNION[

STRUCT[

)NVOKE)$?T INVOKE)$�UNION[

!#3/PEN3TREAM#ONF%VENT?T ACSOPEN�]�U�

]��ACS#ONFIRMATION�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT�!#3/PEN3TREAM#ONF%VENT?T[

6ERSION?T API6ER�6ERSION?T LIB6ER�6ERSION?T TSRV6ER�6ERSION?T DRVR6ER�

]�!#3/PEN3TREAM#ONF%VENT?T�


Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�!#3�3TREAM�

eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�!#3#/.&)2-!4)/.��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�!#3�CONFIRMATION�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�!#3?/0%.?342%!-?#/.&��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�!#3/PEN3TREAM#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION�OREVENT��)T�IS�USED�TO�MATCH�A�SPECIFIC�FUNCTION�REQUEST�WITH�ITSCONFIRMATION�EVENTS�

apiVer4HIS�PARAMETER�INDICATES�WHICH�VERSION�OF�THE�!0)�WAS�GRANTED��4HEVERSION�BEGINS�WITH�THE�LETTERS� 34 ��THE� 3 �AND�THE� 4 �AREINTENTIONALLY�REVERSED��.OTE�THAT�THE�APPLICATION�SUPPLIED�STRING�HADTHE�LETTERS�IN�THE�ORDER� 43 �FOLLOWED�BY�A�SINGLE�43!0)�VERSIONNUMBER��)F�THE�CONTENTS�OF�THE�API6ER�FIELD�DO�NOT�BEGIN�WITH�THELETTERS� 34 ��THEN�THE�APPLICATION�SHOULD�ASSUME�43!0)�VERSION��3EE�THE�PRECEDING�0RIVATE�$ATA�6ERSION�#ONTROL�SECTION�FORINFORMATION�ON�PRIVATE�DATA�VERSION�NEGOTIATION�

libVer4HIS�PARAMETER�INDICATES�WHICH�VERSION�OF�THE�,IBRARY�IS�RUNNING�

tsrvVer4HIS�PARAMETER�INDICATES�WHICH�VERSION�OF�THE�43%26%2�IS�RUNNING�

drvrVer4HIS�PARAMETER�INDICATES�WHICH�VERSION�OF�THE�$RIVER�IS�RUNNING�


Comments

4HIS�MESSAGE�IS�AN�INDICATION�THAT�THE�!#3�3TREAM�REQUESTED�BY�THEAPPLICATION�VIA�THE�ACS/PEN3TREAM��FUNCTION�IS�AVAILABLE�TOPROVIDE�COMMUNICATION�WITH�THE�4ELEPHONY�3ERVER��4HE�APPLICATIONMAY�NOW�REQUEST�CALL�CONTROL�SERVICES�FROM�THE�4ELEPHONY�3ERVER�ONTHE�ACS(ANDLE�IDENTIFYING�THIS�!#3�3TREAM��4HIS�MESSAGE�CONTAINSTHE�,EVEL�OF�THE�STREAM�OPENED��THE�IDENTIFICATION�OF�THE�SERVER�THAT�ISPROVIDING�SERVICE��AND�ANY�0RIVATE�DATA�RETURNED�BY�THE�4ELEPHONY3ERVER�

4HE�0RIVATE�$ATA�IN�THE�!#3/PEN3TREAM#ONF%VENT �INDICATES�WHATVENDOR�AND�VERSION�0RIVATE�$ATA�THE�0"8�DRIVER�WILL�PROVIDE�ON�THESTREAM��)N�THE�0RIVATE�$ATA��THE�VENDOR�FIELD�WILL�CONTAIN�THE�VENDORNAME�AND�THE�DATA�FIELD�IN�THE�0RIVATE?$ATA?T�STRUCTURE�CONTAINS�A�ONEBYTE�DISCRIMINATOR�02)6!4%?$!4!?%.#/$).'�FOLLOWED�BY�AN!3#))�STRING�IDENTIFYING�THE�VERSION�OF�THE�PRIVATE�DATA�THAT�WILL�BESUPPLIED�

Application Notes

4HE�!#3/PEN3TREAM#ONF%VENT� IS�GUARANTEED�TO�BE�THE�FIRST�EVENTON�THE�!#3�3TREAM�THE�APPLICATION�WILL�RECEIVE�IF�NO�ERRORS�OCCURREDDURING�THE�!#3�3TREAM�INITIALIZATION�


ACS#LOSE3TREAM��

This function closes an ACS Stream to the Telephony Server. The applicationwill be unable to request services from the Telephony Server after theacsCloseStream( ) function has returned. The acsHandle is valid on thisstream after the acsCloseStream( ) function returns, but can only be used toreceive events via the acsGetEventBlock( ) or acsGetEventPoll( ) functions.The application must receive the ACSCloseStreamConfEvent associatedwith this function call to indicate that the ACS Stream associated with thespecified acsHandle has been terminated and to allow stream resources to befreed.

Syntax


2ET#ODE?T�ACS#LOSE3TREAM��!#3(ANDLE?T ACS(ANDLE� ��).054��)NVOKE)$?T INVOKE)$� ��).054��0RIVATE$ATA?T PRIVATE$ATA� ��).054��

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�ACTIVE�!#3�3TREAM�WHICH�IS�TO�BE�CLOSED�/NCE�THE�CONFIRMATION�EVENT�ASSOCIATED�WITH�THIS�FUNCTION�RETURNS��THEHANDLE�IS�NO�LONGER�VALID�

invokeID!�HANDLE�PROVIDED�BY�THE�APPLICATION�TO�BE�USED�FOR�MATCHING�ASPECIFIC�INSTANCE�OF�A�FUNCTION�SERVICE�REQUEST�WITH�ITS�ASSOCIATEDCONFIRMATION�EVENT��4HIS�PARAMETER�IS�ONLY�USED�WHEN�THE�)NVOKE�)$MECHANISM�IS�SET�FOR�!PPLICATION GENERATED�)$S�IN�THEACS/PEN3TREAM��4HE�PARAMETER�IS�IGNORED�BY�THE�!#3�,IBRARYWHEN�THE�3TREAM�IS�SET�FOR�,IBRARY GENERATED�INVOKE�)$S�


privateData4HIS�POINTS�TO�A�DATA�STRUCTURE�WHICH�DEFINES�ANY�IMPLEMENTATION SPECIFIC�INFORMATION�NEEDED�BY�THE�SERVER��4HE�DATA�IN�THIS�STRUCTURE�ISNOT�INTERPRETED�BY�THE�!0)�#LIENT�,IBRARY�AND�CAN�BE�USED�AS�ANESCAPE�MECHANISM�TO�PROVIDE�IMPLEMENTATION�SPECIFIC�COMMANDSBETWEEN�THE�APPLICATION�AND�THE�4ELEPHONY�3ERVER�

Return Values

4HIS�FUNCTION�RETURNS�THE�FOLLOWING�VALUES�DEPENDING�ON�WHETHER�THEAPPLICATION�IS�USING�LIBRARY�OR�APPLICATION GENERATED�INVOKEIDENTIFIERS�

,IBRARY GENERATED�)DENTIFIERS� �IF�THE�FUNCTION�CALL�COMPLETESSUCCESSFULLY��IT�WILL�RETURN�A�POSITIVE�VALUE��I�E��THE�INVOKEIDENTIFIER��)F�THE�CALL�FAILS��A�NEGATIVE�ERROR��CONDITION�WILL�BERETURNED��&OR�LIBRARY GENERATED�IDENTIFIERS��THE�RETURN�WILL�NEVERBE�ZERO��

!PPLICATION GENERATED�)DENTIFIERS� �IF�THE�FUNCTION�CALL�COMPLETESSUCCESSFULLY��IT�WILL�RETURN�A�ZERO��VALUE��)F�THE�CALL�FAILS��ANEGATIVE�ERROR��CONDITION�WILL�BE�RETURNED��&OR�APPLICATION GENERATED�IDENTIFIERS��THE�RETURN�WILL�NEVER�BE�POSITIVE��

4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE!#3#LOSE3TREAM#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�

ACS#LOSE3TREAM��RETURNS�THE��NEGATIVE�ERROR�CONDITIONS�BELOW�

!#3%22?"!$($,4HIS�INDICATES�THAT�THE�ACS(ANDLE�BEING�USED�IS�NOT�A�VALIDHANDLE�FOR�AN�ACTIVE�!#3�3TREAM��.O�CHANGES�OCCUR�IN�ANYEXISTING�STREAMS�IF�A�BAD�HANDLE�IS�PASSED�WITH�THIS�FUNCTION�

Comments

/NCE�THIS�FUNCTION�RETURNS��THE�APPLICATION�MUST�ALSO�CHECK�THE!#3#LOSE3TREAM#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�!#33TREAM�WAS�CLOSED�PROPERLY�AND�TO�SEE�IF�ANY�0RIVATE�$ATA�WASRETURNED�BY�THE�SERVER�


.O�OTHER�SERVICE�REQUEST�WILL�BE�ACCEPTED�TO�THE�SPECIFIED�ACS(ANDLEAFTER�THIS�FUNCTION�SUCCESSFULLY�RETURNS��4HE�HANDLE�IS�AN�ACTIVE�ANDVALID�HANDLE�UNTIL�THE�APPLICATION�HAS�RECEIVED�THE!#3#LOSE3TREAM#ONF%VENT �

Application Notes

4HE�#LIENT�IS�RESPONSIBLE�FOR�RECEIVING�THE�!#3#LOSE3TREAM#ONF% VENT�WHICH�INDICATES�RESOURCES�HAVE�BEEN�FREED�

4HE�APPLICATION�MUST�BE�PREPARED�TO�RECEIVE�MULTIPLE�EVENTS�ON�THE!#3�3TREAM�AFTER�THE�ACS#LOSE3TREAM��FUNCTION�HAS�COMPLETED��BUTTHE�!#3#LOSE3TREAM#ONF%VENT �IS�GUARANTEED�TO�BE�THE�LAST�EVENTON�THE�!#3�3TREAM�

4HE�ACS'ET%VENT"LOCK��AND�ACS'ET%VENT0OLL��FUNCTIONS�CANONLY�BE�CALLED�AFTER�THE�ACS#LOSE3TREAM��FUNCTION�HAS�RETURNEDSUCCESSFULLY�


!#3#LOSE3TREAM#ONF%VENT

This event is generated in response to the acsCloseStream( ) function andprovides information regarding the closing of the ACS Stream The acsHandleis no longer valid after this event has been received by the application, so theACSCloseStreamConfEvent is the last event the application will receive forthis ACS Stream.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�SECTION��!#3�$ATA�4YPES�AND��#34!�$ATA�4YPES�FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[)NVOKE)$?T INVOKE)$�

UNION[

!#3#LOSE3TREAM#ONF%VENT?T��ACSCLOSE�]�U�

]�ACS#ONFIRMATION�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT�!#3#LOSE3TREAM#ONF%VENT?T[.ULLTYPE NULL�

]�!#3#LOSE3TREAM#ONF%VENT?T�

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�OPENED�!#3�3TREAM�



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�!#3?#,/3%?342%!-?#/.&��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�!#3#LOSE3TREAM#ONF%VENT �

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION��)T�ISUSED�TO�MATCH�A�SPECIFIC�ACS#LOSE3TREAM��FUNCTION�REQUEST�WITH�ITSCONFIRMATION�EVENT�

Comments

4HIS�MESSAGE�INDICATES�THAT�THE�!#3�3TREAM�TO�THE�4ELEPHONY�3ERVERHAS�CLOSED�AND�THAT�THE�ASSOCIATED�ACS(ANDLE�IS�NO�LONGER�VALID��4HISMESSAGE�CONTAINS�ANY�0RIVATE�DATA�RETURNED�BY�THE�4ELEPHONY�3ERVER�


!#35NIVERSAL&AILURE#ONF%VENT

This event can occur at any time in place of a confirmation event for any ofthe CSTA functions which have their own confirmation event and indicates aproblem in the processes of the requested function. It does not indicate afailure or loss of the ACS Stream with the Telephony Server. If the ACSStream has failed, then an ACSUniversalFailureEvent (unsolicited version ofthis confirmation event) is sent to the application.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�SECTION�!#3�$ATA�4YPES�AND�#34!$ATA�4YPES�FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

UNION[!#35NIVERSAL&AILURE#ONF%VENT?T FAILURE%VENT�]�U�

]�ACS#ONFIRMATION�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT[

!#35NIVERSAL&AILURE?T ERROR�]�!#35NIVERSAL&AILURE#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE!#3?5.)6%23!,?&!),52%?#/.&��WHICH�IDENTIFIES�THISMESSAGE�AS�AN�!#35NIVERSAL&AILURE#ONF%VENT �

error4HIS�PARAMETER�INDICATE�THE�CAUSE�VALUE�FOR�THE�FAILURE�OF�THE�ORIGINAL4ELEPHONY�REQUEST��4HESE�CAUSE�VALUES�ARE�THE�SAME�SET�AS�THOSESHOWN�FOR�!#35NIVERSAL&AILURE%VENT �

Comments

4HIS�EVENT�WILL�OCCUR�ANYTIME�WHEN�A�NON TELEPHONY�PROBLEM��NOMEMORY��4SERVER�3ECURITY�CHECK�FAILED��ETC��IN�PROCESSING�A4ELEPHONY�REQUEST�IN�ENCOUNTERED�AND�IS�SENT�IN�PLACE�OF�THECONFIRMATION�EVENT�THAT�WOULD�NORMALLY�BE�RECEIVED�FOR�THAT�FUNCTION�I�E��#34!-AKE#ALL#ONF%VENT �IN�RESPONSE�TO�A�CSTA-AKE#ALL��REQUEST��)F�THE�PROBLEM�WHICH�PREVENTS�THE�TELEPHONY�FUNCTION�FROMBEING�PROCESSED�IS�TELEPHONY�BASED��THEN�A#34!5NIVERSAL&AILURE#ONF%VENT �WILL�BE�RECEIVED�INSTEAD�


ACS!BORT3TREAM��

This function unilaterally closes an ACS Stream to the Telephony Server. Theapplication will be unable to request services from the Telephony Server orreceive events after the acsAbortStream( ) function has returned. TheacsHandle is invalid on this stream after the acsAbortStream( ) functionreturns. There is no associated confirmation event for this function.

Syntax


2ET#ODE?T�ACS!BORT3TREAM��!#3(ANDLE?T ACS(ANDLE� ��).054��0RIVATE$ATA?T PRIVATE$ATA� ��).054��

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�ACTIVE�!#3�3TREAM�WHICH�IS�TO�BE�CLOSED�4HERE�IS�NO�CONFIRMATION�EVENT�FOR�THIS�FUNCTION��/NCE�THIS�FUNCTIONRETURNS�SUCCESS��THE�!#3�3TREAM�IS�NO�LONGER�VALID�

privateData4HIS�POINTS�TO�A�DATA�STRUCTURE�WHICH�DEFINES�ANY�IMPLEMENTATION SPECIFIC�INFORMATION�NEEDED�BY�THE�SERVER��4HE�DATA�IN�THIS�STRUCTURE�ISNOT�INTERPRETED�BY�THE�!0)�#LIENT�,IBRARY�AND�CAN�BE�USED�AS�ANESCAPE�MECHANISM�TO�PROVIDE�IMPLEMENTATION�SPECIFIC�COMMANDSBETWEEN�THE�APPLICATION�AND�THE�4ELEPHONY�3ERVER�

Return Values

4HIS�FUNCTION�ALWAYS�RETURNS�ZERO��IF�SUCCESSFUL�

4HE�FOLLOWING�ARE�POSSIBLE�NEGATIVE�ERROR�CONDITIONS�FOR�THIS�FUNCTION�



Comments

/NCE�THIS�FUNCTION�RETURNS��THE�!#3�STREAM�IS�DISMANTLED�AND�THEACS(ANDLE�IS�INVALID�


ACS'ET%VENT"LOCK��

This function is used when an application wants to receive an event in aBlocking mode. In the Blocking mode, the application will be blocked untilthere is an event from the ACS Stream indicated by the acsHandle. If theacsHandle is set to zero (0), then the application will block until there is anevent from any ACS stream opened by this application. The function willreturn after the event has been copied into the applications data space.

Syntax


2ET#ODE?T ACS'ET%VENT"LOCK��!#3(ANDLE?T ACS(ANDLE� ��).054��VOID EVENT"UF� ��).054��UNSIGNED�SHORT EVENT"UF3IZE� ��).054�2%452.��0RIVATE$ATA?T PRIVATE$ATA� ��2%452.��UNSIGNED�SHORT NUM%VENTS�� 2%452.��

Parameters

acsHandle4HIS�IS�THE�VALUE�OF�THE�UNIQUE�HANDLE�TO�THE�OPENED�!#3�3TREAM��)F�AHANDLE�OF�ZERO��IS�GIVEN��THEN�THE�NEXT�MESSAGE�ON�ANY�OF�THE�OPEN!#3�3TREAMS�FOR�THIS�APPLICATION�IS�RETURNED�

eventBuf4HIS�IS�A�POINTER�TO�AN�AREA�IN�THE�APPLICATION�ADDRESS�SPACE�LARGEENOUGH�TO�HOLD�ONE�INCOMING�EVENT�THAT�IS�RECEIVED�BY�THEAPPLICATION��4HIS�BUFFER�SHOULD�BE�LARGE�ENOUGH�TO�HOLD�THE�LARGESTEVENT�THE�APPLICATION�EXPECTED�TO�RECEIVE��4YPICALLY�THE�APPLICATIONWILL�RESERVE�A�SPACE�LARGE�ENOUGH�TO�HOLD�A�#34!%VENT?T�

eventBufSize4HIS�PARAMETER�INDICATES�THE�SIZE�OF�THE�USER�BUFFER�POINTED�TO�BYEVENT"UF��)F�THE�EVENT�IS�LARGER�THE�EVENT"UF��THEN�THIS�PARAMETER�WILLBE�RETURNED�WITH�THE�SIZE�OF�THE�BUFFER�REQUIRED�TO�RECEIVE�THE�EVENT�4HE�APPLICATION�SHOULD�CALL�THIS�FUNCTION�AGAIN�WITH�A�LARGER�BUFFER�


privateData4HIS�PARAMETER�POINTS�TO�A�BUFFER�WHICH�WILL�RECEIVE�ANY�PRIVATE�DATATHAT�ACCOMPANIES�THIS�EVENT��4HE�LENGTH�FIELD�OF�THE�0RIVATE$ATA?TSTRUCTURE�MUST�BE�SET�TO�THE�SIZE�OF�THE�DATA�BUFFER��)F�THE�APPLICATIONDOES�NOT�WISH�TO�RECEIVE�PRIVATE�DATA��THEN�PRIVATE$ATA�SHOULD�BE�SETTO�.5,,�

numEvents4HE�LIBRARY�WILL�RETURN�THE�NUMBER�OF�EVENTS�QUEUED�FOR�THEAPPLICATION�ON�THIS�!#3�3TREAM��NOT�INCLUDING�THE�CURRENT�EVENT�VIATHE�NUM%VENTS�PARAMETER��)F�THIS�PARAMETER�IS�.5,,��THEN�NO�VALUEWILL�BE�RETURNED�

/N�A�5NIX7ARE�CLIENT��NUM%VENTS�WILL�HAVE�A�VALUE�OF��OR��INDICATING�THAT�THE�EVENT�QUEUE�IS�EMPTY�OR�NON EMPTY��RESPECTIVELY�THIS�VALUE�ON�A�5NIX7ARE�CLIENT�DOES�NOT�INDICATE�THE�NUMBER�OFEVENTS�IN�THE�QUEUE��/N�A�5NIX7ARE�CLIENT�WHEN�ACS(ANDLE�IS��THENUM%VENTS�VALUE�REFERS�ONLY�TO�THE�STREAM�FOR�WHICH�THE�EVENT�WASRETRIEVED��AND�IS�NOT�AN�AGGREGATE�COUNT�

Return Values

4HIS�FUNCTION�RETURNS�A�POSITIVE�ACKNOWLEDGMENT�OR�A�NEGATIVE�ERRORCONDITION��4HERE�IS�NO�CONFIRMATION�EVENT�FOR�THIS�FUNCTION��4HEPOSITIVE�RETURN�VALUE�IS�

!#30/3)4)6%?!#+4HE�FUNCTION�COMPLETED�SUCCESSFULLY�AS�REQUESTED�BY�THEAPPLICATION��AND�AN�EVENT�HAS�BEEN�COPIED�TO�THE�APPLICATIONDATA�SPACE��.O�ERRORS�WERE�DETECTED�

0OSSIBLE�LOCAL�ERROR�RETURNS�ARE��NEGATIVE�RETURNS�


!#3%22?5"5&3-!,,4HE�USER�BUFFER�SIZE�INDICATED�IN�THE�EVENT"UF3IZE�PARAMETERWAS�SMALLER�THAN�THE�SIZE�OF�THE�NEXT�AVAILABLE�EVENT�FOR�THEAPPLICATION�ON�THE�!#3�STREAM��4HE�EVENT"UF3IZE�VARIABLEHAS�BEEN�RESET�BY�THE�!0)�,IBRARY�TO�THE�SIZE�OF�THE�NEXTMESSAGE�ON�THE�!#3�STREAM��4HE�APPLICATION�SHOULD�CALL


ACS'ET%VENT"LOCK��AGAIN�WITH�A�LARGER�BUFFER��4HE�!#3EVENT�IS�STILL�ON�THE�!0)�,IBRARY�QUEUE�

Comments

4HE�ACS'ET%VENT"LOCK��AND�ACS'ET%VENT0OLL��FUNCTIONS�CAN�BEINTERMIXED�BY�THE�APPLICATION��&OR�EXAMPLE��IF�BURSTY�EVENT�MESSAGETRAFFIC�IS�EXPECTED��AN�APPLICATION�MAY�DECIDE�TO�BLOCK�INITIALLY�FOR�THEFIRST�EVENT�AND�WAIT�UNTIL�IT�ARRIVES��7HEN�THE�FIRST�EVENT�ARRIVES�THEBLOCKING�FUNCTION�RETURNS��AT�WHICH�TIME�THE�APPLICATION�CAN�PROCESSTHIS�EVENT�QUICKLY�AND�POLL�FOR�THE�OTHER�EVENTS�WHICH�MAY�HAVE�BEENPLACED�IN�QUEUE�WHILE�THE�FIRST�EVENT�WAS�BEING�PROCESSED��4HEPOLLING�CAN�BE�CONTINUED�UNTIL�A�!#3%22?./-%33!'%�ISRETURNED�BY�THE�POLLING�FUNCTION��!T�THIS�TIME�THE�APPLICATION�CAN�THENCALL�THE�BLOCKING�FUNCTION�AGAIN�AND�START�THE�WHOLE�CYCLE�OVER�AGAIN�

4HERE�IS�NO�CONFIRMATION�EVENT�FOR�THIS�FUNCTION�

Application Notes

4HE�APPLICATION�IS�RESPONSIBLE�FOR�CALLING�THE�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��FUNCTION�FREQUENTLY�ENOUGH�THAT�THE�!0)�#LIENT,IBRARY�DOES�NOT�OVERFLOW�ITS�RECEIVE�QUEUE�AND�REFUSE�INCOMINGEVENTS�FROM�THE�4ELEPHONY�3ERVER�


ACS'ET%VENT0OLL��

This function is used when an application wants to receive an event in a Non-Blocking mode. In the Non-Blocking mode the oldest outstanding event fromany active ACS Stream will be copied into the applications data space andcontrol will be returned to the application. If no events are currently queuedfor the application, the function will return control immediately to theapplication with an error code indicating that no events were available.

Syntax


2ET#ODE?T ACS'ET%VENT0OLL��!#3(ANDLE?T ACS(ANDLE� ��).054��VOID EVENT"UF� ��).054��UNSIGNED�SHORT EVENT"UF3IZE� ��).054�2%452.��0RIVATE$ATA?T PRIVATE$ATA� ��2%452.��UNSIGNED�SHORT NUM%VENTS�� 2%452.��

Parameters

acsHandle4HIS�IS�THE�VALUE�OF�THE�UNIQUE�HANDLE�TO�THE�OPENED�!#3�3TREAM��)F�AHANDLE�OF�ZERO��IS�GIVEN��THEN�THE�NEXT�MESSAGE�ON�ANY�OF�THE�OPEN!#3�3TREAMS�FOR�THIS�APPLICATION�IS�RETURNED�

eventBuf4HIS�IS�A�POINTER�TO�AN�AREA�IN�THE�APPLICATION�ADDRESS�SPACE�LARGEENOUGH�TO�HOLD�ONE�INCOMING�EVENT�THAT�IS�RECEIVED�BY�THEAPPLICATION��4HIS�BUFFER�SHOULD�BE�LARGE�ENOUGH�TO�HOLD�THE�LARGESTEVENT�THE�APPLICATION�EXPECTED�TO�RECEIVE��4YPICALLY�THE�APPLICATIONWILL�RESERVE�A�SPACE�LARGE�ENOUGH�TO�HOLD�A�#34!%VENT?T�

eventBufSize4HIS�PARAMETER�INDICATES�THE�SIZE�OF�THE�USER�BUFFER�POINTED�TO�BYEVENT"UF��)F�THE�EVENT�IS�LARGER�THE�EVENT"UF��THEN�THIS�PARAMETER�WILLBE�RETURNED�WITH�THE�SIZE�OF�THE�BUFFER�REQUIRED�TO�RECEIVE�THE�EVENT�4HE�APPLICATION�SHOULD�CALL�THIS�FUNCTION�AGAIN�WITH�A�LARGER�BUFFER�


privateData4HIS�PARAMETER�POINTS�TO�A�BUFFER�WHICH�WILL�RECEIVE�ANY�PRIVATE�DATATHAT�ACCOMPANIES�THIS�EVENT��4HE�LENGTH�FIELD�OF�THE�0RIVATE$ATA?TSTRUCTURE�MUST�BE�SET�TO�THE�SIZE�OF�THE�DATA�BUFFER��)F�THE�APPLICATIONDOES�NOT�WISH�TO�RECEIVE�PRIVATE�DATA��THEN�PRIVATE$ATA�SHOULD�BE�SETTO�.5,,�

numEvents4HE�LIBRARY�WILL�RETURN�THE�NUMBER�OF�EVENTS�QUEUED�FOR�THEAPPLICATION�ON�THIS�!#3�3TREAM��NOT�INCLUDING�THE�CURRENT�EVENT�VIATHE�NUM%VENTS�PARAMETER��)F�THIS�PARAMETER�IS�.5,,��THEN�NO�VALUEWILL�BE�RETURNED�

Return Values


!#30/3)4)6%?!#+4HE�FUNCTION�COMPLETED�SUCCESSFULLY�AS�REQUESTED�BY�THEAPPLICATION��AND�AN�EVENT�HAS�BEEN�COPIED�TO�THE�APPLICATIONDATA�SPACE��.O�ERRORS�WERE�DETECTED�



!#3%22?./-%33!'%4HERE�WERE�NO�MESSAGES�AVAILABLE�TO�RETURN�TO�THEAPPLICATION�

!#3%22?5"5&3-!,,4HE�USER�BUFFER�SIZE�INDICATED�IN�THE�EVENT"UF3IZE�PARAMETERWAS�SMALLER�THAN�THE�SIZE�OF�THE�NEXT�AVAILABLE�EVENT�FOR�THEAPPLICATION�ON�THE�!#3�STREAM��4HE�EVENT"UF3IZE�VARIABLEHAS�BEEN�RESET�BY�THE�!0)�,IBRARY�TO�THE�SIZE�OF�THE�NEXTMESSAGE�ON�THE�!#3�STREAM��4HE�APPLICATION�SHOULD�CALLACS'ET%VENT0OLL��AGAIN�WITH�A�LARGER�BUFFER��4HE�!#3EVENT�IS�STILL�ON�THE�!0)�,IBRARY�QUEUE�


Comments

7HEN�THIS�FUNCTION�IS�CALLED��IT�RETURNS�IMMEDIATELY��AND�THE�USERMUST�EXAMINE�THE�RETURN�CODE�TO�DETERMINE�IF�A�MESSAGE�WAS�COPIEDINTO�THE�USER�S�DATA�SPACE��)F�AN�EVENT�WAS�AVAILABLE��THE�FUNCTION�WILLRETURN�!#30/3)4)6%?!#+�

)F�NO�EVENTS�EXISTED�ON�THE�!#3�3TREAM�FOR�THE�APPLICATION��THISFUNCTION�WILL�RETURN�!#3%22?./-%33!'%�

4HE�ACS'ET%VENT"LOCK��AND�ACS'ET%VENT0OLL��FUNCTIONS�CAN�BEINTERMIXED�BY�THE�APPLICATION��&OR�EXAMPLE��IF�BURSTY�EVENT�MESSAGETRAFFIC�IS�EXPECTED��AN�APPLICATION�MAY�DECIDE�TO�BLOCK�INITIALLY�FOR�THEFIRST�EVENT�AND�WAIT�UNTIL�IT�ARRIVES��7HEN�THE�FIRST�EVENT�ARRIVES�THEBLOCKING�FUNCTION�RETURNS��AT�WHICH�TIME�THE�APPLICATION�CAN�PROCESSTHIS�EVENT�QUICKLY�AND�POLL�FOR�THE�OTHER�EVENTS�WHICH�MAY�HAVE�BEENPLACED�IN�QUEUE�WHILE�THE�FIRST�EVENT�WAS�BEING�PROCESSED��4HEPOLLING�MAY�CONTINUE�UNTIL�THE�!#3%22?./-%33!'%�IS�RETURNEDBY�THE�POLLING�FUNCTION��!T�THIS�TIME�THE�APPLICATION�CAN�THEN�CALL�THEBLOCKING�FUNCTION�AGAIN�AND�START�THE�WHOLE�CYCLE�OVER�AGAIN�


Application Notes

4HE�APPLICATION�IS�RESPONSIBLE�FOR�CALLING�THE�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��FUNCTION�FREQUENTLY�ENOUGH�THAT�THE�!0)�#LIENT,IBRARY�DOES�NOT�OVERFLOW�ITS�RECEIVE�QUEUE�AND�REFUSES�INCOMINGEVENTS�FROM�THE�4ELEPHONY�3ERVER�


ACS'ET&ILE��5NIX7ARE�AND�(0 58

The acsGetFile( ) function returns the Unix file descriptor associated with anACS stream. This is to enable multiplexing of input sources via, for example,the POLL� system call.

Syntax


2ET#ODE?T�ACS'ET&ILE��!#3(ANDLE?T�ACS(ANDLE�

Parameters

acsHandle4HIS�IS�THE�VALUE�OF�THE�UNIQUE�HANDLE�TO�THE�OPENED�!#3�3TREAMWHOSE�5NIX�FILE�DESCRIPTOR�IS�TO�BE�RETURNED�

Return Values

4HIS�FUNCTION�RETURNS�EITHER�A�5NIX�FILE�DESCRIPTOR�GREATER�THAN�OREQUAL�TO�ZERO��OR�!#3%22?"!$($,�IF�THE�ACS(ANDLE�BEINGUSED�IS�NOT�A�VALID�HANDLE�FOR�AN�ACTIVE�!#3�3TREAM�

Application Notes

4HE�ACS'ET&ILE��FUNCTION�RETURNS�THE�5.)8�FILE�DESCRIPTOR�USED�BYAN�!#3�STREAM��4HIS�ENABLES�AN�APPLICATION�TO�SIMULTANEOUSLY�BLOCKON�THE�STREAM�AND�ANY�OTHER�FILE ORIENTED�INPUT�SOURCES�BY�USINGPOLL��SELECT��8T!DD)NPUT��OR�SIMILAR�MULTIPLEXINGFUNCTIONS��4HE�APPLICATION�SHOULD�NEVER�PERFORM�ANY�DIRECT�)�/OPERATIONS�ON�THIS�FILE�DESCRIPTOR�



ACS3ET%32��7INDOWS�AND�.ET7AREÊ

The acsSetESR( ) function also allows the application to designate an EventService Routine (ESR) that will be called when an incoming event isavailable.

Syntax (Windows)


�TYPEDEF�VOID��%SR&UNC�UNSIGNED�SHORT�ESR0ARAM

2ET#ODE?T ACS3ET%32��!#3(ANDLE?T ACS(ANDLE�%SR&UNC ESR�UNSIGNED� SHORT ESR0ARAM�"OOLEAN NOTIFY!LL�

Syntax (NetWare)


2ET#ODE?T��ACS3ET%32��!#3(ANDLE?T ACS(ANDLE�

VOID��ESR�UNSIGNED�LONG�ESR0ARAM�UNSIGNED� LONG ESR0ARAM�"OOLEAN NOTIFY!LL�

Parameters

acsHandle4HIS�IS�THE�VALUE�OF�THE�UNIQUE�HANDLE�TO�THE�OPENED�3TREAM�FOR�WHICHTHIS�%32�ROUTINE�WILL�APPLY��/NLY�ONE�%32�IS�ALLOWED�PER�ACTIVEACS(ANDLE�

esr4HIS�IS�A�POINTER�TO�THE�%32��THE�ADDRESS�OF�A�FUNCTION��!NAPPLICATION�PASSES�A�.5,,�POINTER�INDICATES�TO�CLEAR�AN�EXISTING�%32�

esrParam4HIS�IS�A�USER DEFINED�PARAMETER�WHICH�WILL�BE�PASSED�TO�THE�%32WHEN�IT�IS�CALLED�


notifyAll)F�THIS�PARAMETER�IS�425%�THEN�THE�%32�WILL�BE�CALLED�FOR�EVERYEVENT��)F�IT�IS�&!,3%�THEN�THE�%32�WILL�ONLY�BE�CALLED�EACH�TIME�THERECEIVE�QUEUE�BECOMES�NON EMPTY��I�E��THE�QUEUE�COUNT�CHANGES�FROMZERO��TO�ONE��4HIS�OPTION�MAY�BE�USED�TO�REDUCE�THE�OVERHEADOF�NOTIFICATION�

Return Values


!#30/3)4)6%?!#+4HE�FUNCTION�COMPLETED�SUCCESSFULLY�AS�REQUESTED�BY�THEAPPLICATION��.O�ERRORS�WERE�DETECTED�



Comments

4HE�%32�MECHANISM�CAN�BE�USED�BY�THE�APPLICATION�TO�RECEIVE�ANASYNCHRONOUS�NOTIFICATION�OF�THE�ARRIVAL�OF�AN�INCOMING�EVENT�FROMTHE�!#3�3TREAM��4HE�%32�ROUTINE�WILL�RECEIVE�ONE�USER DEFINEDPARAMETER��7INDOWS�CALLS�THE�%32�FUNCTION�WITH�INTERRUPTS�DISABLED�NOT�NORMAL�APPLICATION�CONTEXT��4HE�%32�SHOULD�NOT�CALL�!#3FUNCTIONS��43!0)�FUNCTIONS��AND�MANY�OF�THE�7INDOWS�!0)S�OR�THERESULTS�WILL�BE�INDETERMINATE��4HE�%32�SHOULD�NOTE�THE�ARRIVAL�OF�THEINCOMING�EVENT��AND�COMPLETE�ITS�OPERATION�AS�QUICKLY�AS�POSSIBLE�4HE�APPLICATION�MUST�STILL�CALL�ACS'ET%VENT"LOCK��ORACS'ET%VENT0OLL��TO�RETRIEVE�THE�EVENT�FROM�THE�#LIENT�!0)�,IBRARYQUEUE�

)F�THERE�ARE�ALREADY�EVENTS�IN�THE�RECEIVE�QUEUE�WAITING�TO�BE�RETRIEVEDWHEN�ACS3ET%32��IS�CALLED��THE�ESR�WILL�BE�CALLED�FOR�EACH�OF�THEM�

4HE�ESR�IN�THE�ACS3ET%32��FUNCTION�WILL�REPLACE�THE�CURRENT�%32MAINTAINED�BY�THE�!0)�#LIENT�,IBRARY��!�.5,,�ESR�WILL�DISABLE�THECURRENT�%32�MECHANISM�



Application Notes

4HE�APPLICATION�CAN�USE�THE�%32�MECHANISM�TO�TRIGGER�PLATFORMSPECIFIC�EVENTS��E�G��POST�A�7INDOWS�MESSAGE�FOR�THE�APPLICATION�OR�SIGNAL�A�SEMAPHORE�IN�THE�.ET7ARE�ENVIRONMENT�

4HE�APPLICATION�MAY�USE�THE�%32�MECHANISM�FOR�ASYNCHRONOUSNOTIFICATION�OF�THE�ARRIVAL�OF�INCOMING�EVENTS��BUT�MOST�!0)�,IBRARYENVIRONMENTS�PROVIDE�OTHER�MECHANISMS�FOR�RECEIVING�ASYNCHRONOUSNOTIFICATION�

4HE�APPLICATION�SHOULD�NOT�CALL�!#3�FUNCTIONS�FROM�WITHIN�THE�%32�

4HE�APPLICATION�SHOULD�COMPLETE�ITS�%32�PROCESSING�AS�QUICKLY�ASPOSSIBLE�

4HE�%32�FUNCTION�MAY�BE�CALLED�WHILE��SOME�LEVEL�OF�INTERRUPTS�AREDISABLED��4HIS�IS�!0)�IMPLEMENTATION�SPECIFIC��SO�THE�APPLICATIONPROGRAMMER�SHOULD�CONSULT�THE�!0)�DOCUMENTATION��5NDER7INDOWS��THE�%32�FUNCTION�MUST�BE�EXPORTED�AND�ITS�ADDRESSOBTAINED�FROM�-AKE0ROC)NSTANCE��

Windows Client Note:

5SE�ACS3ET%32��WITH�CARE��%32�CODE�AND�DATA�MUST�BE�IMMUNE�TOSWAPPING��I�E��FIXED�AND�PAGE�LOCKED��4HE�%32�MUST�RESIDE�IN�A$,,�SO�AS�TO�BE�FIXED��)NTERRUPTS�ARE�DISABLED�WHEN�AN�%32�IS�CALLED�7ITHIN�THE�%32��DO�NOT�CALL�ANY�FUNCTION�THAT�MAY�ENABLE�INTERRUPTS�INCLUDING�MOST�7INDOWS�!0)S�OR�WHICH�IS�NOT� NAILED�DOWN �


ACS3ET%32��7IN��

The acsSetESR( ) function also allows the application to designate an EventService Routine (ESR) that will be called when an incoming event isavailable.

Syntax


TYPEDEF�VOID��%SR&UNC�UNSIGNED�LONG�ESR0ARAM

2ET#ODE?T�ACS3ET%32��!#3(ANDLE?T ACS(ANDLE�%SR&UNC ESR�UNSIGNED�LONG ESR0ARAM�"OOLEAN NOTIFY!LL�

Parameters


esr4HIS�IS�A�POINTER�TO�THE�%32��THE�ADDRESS�OF�A�FUNCTION��!NAPPLICATION�PASSES�A�.5,,�POINTER�INDICATES�TO�CLEAR�AN�EXISTING�%32�




Return Values





Comments

4HE�%32�MECHANISM�CAN�BE�USED�BY�THE�APPLICATION�TO�RECEIVE�ANASYNCHRONOUS�NOTIFICATION�OF�THE�ARRIVAL�OF�AN�INCOMING�EVENT�FROMTHE�!#3�3TREAM��4HE�%32�ROUTINE�WILL�RECEIVE�ONE�USER DEFINEDPARAMETER��4HE�%32�SHOULD�NOT�CALL�43!0)�FUNCTIONS��OR�THE�RESULTSWILL�BE�INDETERMINATE��4HE�%32�SHOULD�NOTE�THE�ARRIVAL�OF�THEINCOMING�EVENT��AND�COMPLETE�ITS�OPERATION�AS�QUICKLY�AS�POSSIBLE�4HE�APPLICATION�MUST�STILL�CALL�ACS'ET%VENT"LOCK��ORACS'ET%VENT0OLL��TO�RETRIEVE�THE�EVENT�FROM�THE�#LIENT�!0)�,IBRARYQUEUE�

5SE�ACS3ET%32��WITH�CARE��4HE�%32�CODE�WILL�BE�EXECUTED�IN�THECONTEXT�OF�A�BACKGROUND�THREAD�CREATED�BY�THE�!0)�#LIENT�,IBRARY�NOT�AN�APPLICATION�THREAD�





ACS3ET%32��-ACINTOSH

The acsSetESR( ) function allows application to designate an Event ServiceRoutine (ESR) that will be called when an incoming event is available.

Syntax


TYPEDEF�PASCAL�VOID��%SR&UNC�UNSIGNED�LONG�ESR0ARAM

ENUM�[UPP%32&UNC0ROC)NFO��K0ASCAL3TACK"ASED

\�2%35,4?3):%�3):%?#/$%��\�34!#+?2/54).%?0!2!-%4%2��3):%?#/$%�SIZEOF�LONG

]�

�IF�53%32/54).%$%3#2)04/23TYPEDEF�5NIVERSAL0ROC0TR�%SR&UNC500�

�DEFINE�.EW%SR&UNC0ROC�USER2OUTINE�%SR&UNC500�.EW2OUTINE$ESCRIPTOR��0ROC0TR�USER2OUTINE�

UPP%SR&UNC0ROC)NFO��'ET#URRENT)3!��ELSETYPEDEF�%SR&UNC� %SR&UNC500��DEFINE�.EW%SR&UNC0ROC�USER2OUTINE

�%SR&UNC500�USER2OUTINE�ENDIF

2ET#ODE?T� ACS3ET%32�� !#3(ANDLE?T ACS(ANDLE�%SR&UNC500 ESR�UNSIGNED�LONG ESR0ARAM�"OOLEAN NOTIFY!LL��

Parameters


esr4HIS�IS�A�UNIVERSAL�PROCEDURE�POINTER�TO�THE�%32��THE�ADDRESS�OF�A��X��FUNCTION�OR�ROUTINE�DESCRIPTOR��!N�APPLICATION�PASSES�A�.5,,POINTER�INDICATES�TO�CLEAR�AN�EXISTING�%32��




Return Values





Comments

4HE�%32�MECHANISM�CAN�BE�USED�BY�THE�APPLICATION�TO�RECEIVE�ANASYNCHRONOUS�NOTIFICATION�OF�THE�ARRIVAL�OF�AN�INCOMING�EVENT�FROMTHE�!#3�3TREAM��4HE�%32�ROUTINE�WILL�RECEIVE�ONE�USER DEFINEDPARAMETER��4HE�%32�SHOULD�NOT�CALL�!#3�FUNCTIONS��OTHERWISE�THERESULTS�WILL�BE�INDETERMINATE��4HE�%32�SHOULD�NOTE�THE�ARRIVAL�OF�THEINCOMING�EVENT��AND�COMPLETE�ITS�OPERATION�AS�QUICKLY�AS�POSSIBLE�4HE�APPLICATION�MUST�STILL�CALL�ACS'ET%VENT"LOCK��ORACS'ET%VENT0OLL��TO�RETRIEVE�THE�EVENT�FROM�THE�#LIENT�!0)�,IBRARYQUEUE�





Application Notes

4HE�APPLICATION�MAY�USE�THE�%32�MECHANISM�FOR�ASYNCHRONOUSNOTIFICATION�OF�THE�ARRIVAL�OF�INCOMING�EVENTS��PARTICULARLY�WHEN�RAPIDNOTIFICATION�IS�DESIRED��"Y�USING�THE�%32�TO�SET�AN�APPLICATION�GLOBAL�THE�APPLICATION�MAY�DETERMINE�WHETHER�EVENTS�HAVE�ARRIVED�BYEXAMINING�THAT�GLOBAL�RATHER�THAN�USING�ACS'ET%VENT0OLL��ORACS'ET%VENT"LOCK��

4HE�%32�FUNCTION�IS�DEFINED�AS�A�UNIVERSAL�PROCEDURE�POINTER��5NDER00#��PROVIDING�A�NATIVE�OR�FAT�ROUTINE�DESCRIPTOR�WILL�RESULT�IN�THE�BESTPERFORMANCE�AS�THERE�WILL�BE�NO�MODE�SWITCH�INVOLVED�WHEN�CALLINGTHE�%32�

4HE�APPLICATION�MAY�NOT�CALL�!#3�FUNCTIONS�FROM�WITHIN�THE�%32�

4HE�APPLICATION�SHOULD�COMPLETE�ITS�%32�PROCESSING�AS�QUICKLY�ASPOSSIBLE�

4HE�%32�FUNCTION�MAY�BE�CALLED�WHILE��SOME�LEVEL�OF�INTERRUPTS�AREDISABLED��REFER�TO�)NSIDE�-ACINTOSH�FOR�INFORMATION�ABOUTPROGRAMMING�WITH�INTERRUPTS�DISABLED��%NSURE�THAT�THE�%32�FUNCTION�AND�ROUTINE�DESCRIPTOR�UNDER�00#� �REMAIN�LOADED�AND�PAGE

LOCKED�IN�MEMORY��)N�PARTICULAR��DO�NOT�MAKE�SYNCHRONOUS�)�/�CALLSOR�ACCESS�MEMORY�THAT�IS�NOT�PAGE LOCKED�

/N�-ACINTOSH� �AS�WITH�OTHER�INTERRUPT�SERVICE�ROUTINES� �THE�%32IS�PROHIBITED�FROM�USING�THE�-ACINTOSH�MEMORY�MANAGER� �DIRECTLYOR�INDIRECTLY��)N�ADDITION��THE�%32�MUST�SET�ANY�GLOBAL�CONTEXT�ITNEEDS��/N�THE��X��-ACINTOSH��THIS�MEANS�THAT�THE�%32�MUST�SET!��OR�!��BEFORE�ACCESSING�APPLICATION�GLOBALS�OR�MAKING�INTER SEGMENT�JUMPS��BEFORE�RETURNING��THE�%32�MUST�RESTORE�!��OR�!��TOITS�VALUE�ON�ENTRY��/N�A�0OWER0#��THE�RUNTIME�MODEL�AUTOMATICALLYMANAGES�THIS�CONTEXT��3EE�REFERENCES��;�=AND�;�=�FOR�MOREINFORMATION�


ACS3ET%32��/3��

The acsSetESR( ) function allows the application to designate an EventService Routine (ESR) that will be called when an incoming event isavailable.

Syntax

�INCLUDE��OS��H��INCLUDE��ACS�H��INCLUDE��CSTA�H�

TYPEDEF�VOID��%SR&UNC�UNSIGNED�LONG�ESR0ARAM

43!0)ACS3ET%32��!#3(ANDLE?T ACS(ANDLE�

%SR&UNC� ESR�UNSIGNED�LONG� ESR0ARAM�UNSIGNED�CHAR NOTIFY!LL�

Parameters


esr4HIS�IS�A�POINTER�TO�THE�%32��THE�ADDRESS�OF�A�FUNCTION��4HE�CALLINGCONVENTION�FOR�THIS�FUNCTION�SHOULD�BE�SPECIFIED�AS�?3YSTEM��OR?SYSCALL��!�MULTI THREADED�APPLICATION�THAT�REGISTERS�THE�SAME�%32FOR�MULTIPLE�OPEN�STREAMS�NEEDS�TO�ENSURE�THAT�THIS�FUNCTION�ISREENTRANT��!�.5,,�POINTER�IS�USED�TO�DISABLE�THE�CURRENT�%32MECHANISM�




Return Values





Comments

4HE�%32�MECHANISM�CAN�BE�USED�BY�THE�APPLICATION�TO�RECEIVE�ANASYNCHRONOUS�NOTIFICATION�OF�THE�ARRIVAL�OF�AN�INCOMING�EVENT�FROMTHE�/PEN�!#3�3TREAM��4HE�APPLICATION�CAN�USE�THE�%32�MECHANISMTO�TRIGGER��SPECIFIC�EVENTS��E�G��POST�AN�EVENT�SEMAPHORE��4HE�%32ROUTINE�WILL�RECEIVE�ONE�USER DEFINED�PARAMETER��4HE�%32�SHOULD�NOTCALL�!#3�FUNCTIONS��OTHERWISE�THE�RESULTS�WILL�BE�INDETERMINATE��4HEAPPLICATION�MUST�STILL�CALL�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��TO�ACTUALLY�RETRIEVE�THE�EVENT�FROM�THE�#LIENT�!0)�,IBRARY�QUEUE�

)F�THERE�ARE�ALREADY�EVENTS�IN�THE�RECEIVE�QUEUE�WAITING�TO�BE�RETRIEVED�WHENACS3ET%32��IS�CALLED��THE�ESR�WILL�BE�CALLED�FOR�EACH�EVENT�IF�NOTIFY!LL�HASBEEN�SET�TO�425%�OR�ONLY�ONCE�IF�NOTIFY!LL�HAS�BEEN�SET�TO�&!,3%�




ACS%VENT.OTIFY��7INDOWS��

The acsEventNotify( ) function allows a Windows application to request thata message be posted to its application queue when an incoming ACS event isavailable.

Syntax


2ET#ODE?T ACS%VENT.OTIFY��!#3(ANDLE?TACS(ANDLE�(7.$ HWND�5).4 MSG�"OOLEAN NOTIFY!LL�

Parameters

acsHandle4HIS�IS�THE�VALUE�OF�THE�UNIQUE�HANDLE�TO�THE�OPENED�!#3�3TREAM�FORWHICH�EVENT�NOTIFICATION�MESSAGES�WILL�BE�POSTED�

hwnd4HIS�IS�THE�HANDLE�OF�THE�WINDOW�WHICH�IS�TO�RECEIVE�EVENTNOTIFICATION�MESSAGES��)F�THIS�PARAMETER�IS�.5,,��EVENT�NOTIFICATIONIS�DISABLED�

msg4HIS�IS�THE�USER DEFINED�MESSAGE�TO�BE�POSTED�WHEN�AN�INCOMINGEVENT�BECOMES�AVAILABLE��4HE�W0ARAM�AND�L0ARAM�PARAMETERS�OF�THEMESSAGE�WILL�CONTAIN�THE�FOLLOWING�MEMBERS�OF�THE!#3%VENT(EADER?T�STRUCTURE�

W0ARAM ACS(ANDLE()7/2$�L0ARAM EVENT#LASS,/7/2$�L0ARAM EVENT4YPE


notifyAll)F�THIS�PARAMETER�IS�425%�THEN�A�MESSAGE�WILL�BE�POSTED�FOR�EVERYEVENT��)F�IT�IS�&!,3%�THEN�A�MESSAGE�WILL�ONLY�BE�POSTED�EACH�TIMETHE�RECEIVE�QUEUE�BECOMES�NON EMPTY��I�E��THE�QUEUE�COUNT�CHANGESFROM�ZERO��TO�ONE��4HIS�OPTION�MAY�BE�USED�TO�REDUCE�THEOVERHEAD�OF�NOTIFICATION��OR�THE�LIKELIHOOD�OF�OVERFLOWING�THEAPPLICATION�S�MESSAGE�QUEUE��SEE�BELOW�

Return Values





Application Notes

4HIS�FUNCTION�ONLY�ENABLES�NOTIFICATION�OF�AN�INCOMING�EVENT��5SEACS'ET%VENT0OLL��TO�ACTUALLY�RETRIEVE�THE�COMPLETE�EVENT�STRUCTURE�

)F�THERE�ARE�ALREADY�EVENTS�IN�THE�RECEIVE�QUEUE�WAITING�TO�BE�RETRIEVEDWHEN�ACS%VENT.OTIFY��IS�CALLED��A�MESSAGE�WILL�BE�POSTED�FOR�EACHOF�THEM�

!PPLICATIONS�WHICH�PROCESS�A�HIGH�VOLUME�OF�INCOMING�EVENTS�MAYCAUSE�THE�DEFAULT�APPLICATION�QUEUE��MESSAGES�MAX�TO�OVERFLOW��)NTHIS�CASE��USE�THE�7INDOWS�!0)�CALL�3ET-ESSAGE1UEUE��TO�INCREASETHE�SIZE�OF�THE�APPLICATION�QUEUE��!LSO��THE�RATE�OF�NOTIFICATIONS�MAYBE�REDUCED�BY�SETTING�NOTIFY!LL�TO�&!,3%�



Example

4HIS�EXAMPLE�USES�THE�ACS%VENT.OTIFY�FUNCTION�TO�ENABLE�EVENTNOTIFICATION�

�DEFINE�7-?!#3%6%.4�7-?53%2��OR�USE�2EGISTER7INDOW-ESSAGE�

LONG�&!2�0!3#!,7ND0ROC��(7.$�HWND��5).4�MSG��70!2!-�W0ARAM��,0!2!-� L0ARAM[

��DECLARE�LOCAL�VARIABLES��

SWITCH��MSG[CASE�7-?#2%!4%�

��POST�7-?!#3%6%.4�TO�THIS�WINDOW��WHENEVER�AN�!#3�EVENT�ARRIVES

ACS%VENT.OTIFY��ACS(ANDLE��HWND��7-?!#3%6%.4��425%�

��OTHER�INITIALIZATION��ETC��RETURN��

CASE�7-?!#3%6%.4�

��W0ARAM�CONTAINS�AN�!#3(ANDLE?T��()7/2$�L0ARAM�CONTAINS�AN�%VENT#LASS?T��,/7/2$�L0ARAM�CONTAINS�AN�%VENT4YPE?T

��DISPATCH�THE�EVENT�TO�USER DEFINED��HANDLER�FUNCTION�HERE

RETURN��

��PROCESS�OTHER�WINDOW�MESSAGES��

]RETURN�$EF7INDOW0ROC��HWND��MSG��W0ARAM��L0ARAM�

]


ACS%VENT.OTIFY��7IN��

The acsEventNotify( ) function allows a Win32 application to request that amessage be posted to its application queue when an incoming ACS event isavailable.

Syntax


2ET#ODE?T�ACS%VENT.OTIFY��!#3(ANDLE?T ACS(ANDLE�(7.$ HWND�5).4 MSG�"OOLEAN NOTIFY!LL�

Parameters



msg4HIS�IS�THE�USER DEFINED�MESSAGE�TO�BE�POSTED�WHEN�AN�INCOMINGEVENT�BECOMES�AVAILABLE��4HE�W0ARAM�AND�L0ARAM�PARAMETERS�OF�THEMESSAGE�WILL�CONTAIN�THE�FOLLOWING�MEMBERS�OF�THE!#3%VENT(EADER?T�STRUCTURE�

W0ARAM ACS(ANDLE()7/2$�L0ARAM EVENT#LASS,/7/2$�L0ARAM EVENT4YPE



Return Values





Application Notes


)F�THERE�ARE�ALREADY�EVENTS�IN�THE�RECEIVE�QUEUE�WAITING�TO�BE�RETRIEVEDWHEN�ACS%VENT.OTIFY��IS�CALLED��A�MESSAGE�WILL�BE�POSTED�FOR�EACHOF�THEM�

4HE�RATE�OF�NOTIFICATIONS�MAY�BE�REDUCED�BY�SETTING�NOTIFY!LL�TO&!,3%�



Example


�DEFINE�7-?!#3%6%.4�7-?53%2��OR�USE�2EGISTER7INDOW-ESSAGE�

LONG�&!2�0!3#!,7ND0ROC��(7.$�HWND��5).4�MSG��70!2!-�W0ARAM��,0!2!-� L0ARAM[






CASE�7-?!#3%6%.4�

��W0ARAM�CONTAINS�AN�!#3(ANDLE?T��()7/2$�L0ARAM�CONTAINS�AN�%VENT#LASS?T��,/7/2$�L0ARAM�CONTAINS�AN�%VENT4YPE?T


RETURN��


]RETURN�$EF7INDOW0ROC��HWND��MSG��W0ARAM��L0ARAM�

]


ACS%VENT.OTIFY��-ACINTOSH

The acsEventNotify( ) function allows a Macintosh application to request thatit receive an Apple Event when an incoming ACS event is available.

Syntax

�INCLUDE��ACS�H��INCLUDE��CSTA�H��INCLUDE��%00#�H� ��FOR�!PPLE�%VENT�TYPES��

2ET#ODE?T�ACS%VENT.OTIFY��!#3(ANDLE?T ACS(ANDLE�!%!DDRESS$ESC TARGET!DDR�"OOLEAN NOTIFY!LL��

Parameters


targetAddr4HIS�IS�A�POINTER�TO�AN�!%!DDRESS$ESC�DATA�STRUCTURE��4HE�EVENTNOTIFICATION�!PPLE�%VENTS�WILL�BE�SENT�TO�THE�ADDRESS�SPECIFIED�BY�THE!%!DDRESS$ESC��!�.5,,�TARGET!DDR�INDICATES�NO�NOTIFICATION�

notifyAll)F�THIS�PARAMETER�IS�425%�THEN�A�MESSAGE�WILL�BE�POSTED�FOR�EVERYEVENT��)F�IT�IS�&!,3%�THEN�A�MESSAGE�WILL�ONLY�BE�POSTED�EACH�TIMETHE�RECEIVE�QUEUE�BECOMES�NON EMPTY��I�E��THE�QUEUE�COUNT�CHANGESFROM�ZERO��TO�ONE��4HIS�OPTION�MAY�BE�USED�TO�REDUCE�THEOVERHEAD�OF�NOTIFICATION��SEE�BELOW�

Return Values






Application Notes

4HE�!PPLE�%VENTS�POSTED�AS�THE�RESULT�OF�CALLING�ACS%VENT.OTIFY��HAVE�THE�FOLLOWING�ATTRIBUTES�

%VENT�#LASS K43!0)%VENT#LASS

%VENT�)$ K43!0)%VENT!RRIVED

2EQUIRED�0ARAMETER

+EYWORD� KEY43!0)%VENT#LASS

$ESCRIPTOR�4YPE� TYPE3HORT)NTEGER

$ATA� 4HE�%VENT#LASS?TCORRESPONDING�TO�THEINCOMING�43!0)�EVENT�


+EYWORD� KEY43!0)%VENT4YPE

$ESCRIPTOR�4YPE� TYPE3HORT)NTEGER

$ATA� 4HE�%VENT4YPE?TCORRESPONDING�TO�THEINCOMING�43!0)�EVENT�


+EYWORD� KEY3TREAM(ANDLE

$ESCRIPTOR�4YPE� TYPE,ONG)NTEGER

$ATA� 4HE�!#3(ANDLE?T�THATMAY�BE�USED�TO�RETRIEVETHE�INCOMING�43!0)EVENT�

3EE�REFERENCE�;�=�FOR�INFORMATION�ON�HOW�TO�CREATE�AN!%!DDRESS$ESC�AND�EXTRACT�INFORMATION�FROM�THE�NOTIFICATION�!PPLE%VENTS�


!FTER�CALLING�ACS%VENT.OTIFY��PROPERLY�DISPOSE�OF�THE!%!DDRESS$ESC�SPECIFIED�BY�TARGET!DDR�


)F�THERE�ARE�ALREADY�EVENTS�IN�THE�RECEIVE�QUEUE�WAITING�TO�BE�RETRIEVEDWHEN�ACS%VENT.OTIFY��IS�CALLED��AN�!PPLE�%VENT�WILL�BE�SENT�FOREACH�OF�THEM�

!PPLICATIONS�WHICH�PROCESS�A�HIGH�VOLUME�OF�INCOMING�EVENTS�SHOULDEITHER�SET�NOTIFY!LL�TO�425%�OR�USE�ACS3ET%32��THE�CURRENTTHEORETICAL�UPPER�BOUND�ON�SENDING�!PPLE�%VENTS�IS�SIXTY�MESSAGESPER�SECOND��)N�PRACTICE� �DEPENDING�ON�PROCESSOR�SPEED�ANDAVAILABLE�MEMORY� �THIS�NUMBER�MAY�BE�SIGNIFICANTLY�LOWER�



Example


��HANDLE43!0)%VENT� �INSTALL�AS�!PPLE%VENT�HANDLER��CALLBACK��BEFORE�USING�ACS%VENT.OTIFY��

PASCAL�/3%RRHANDLE43!0)%VENT� CONST�!PPLE%VENT THE!PPLE%VENT�

CONST�!PPLE%VENT REPLY�LONG HANDLER2EFCON

[%VENT#LASS?T THE43!0)#LASS�%VENT4YPE?TTHE43!0)4YPE�!#3(ANDLE?TTHE3TREAM�$ESC4YPE ACTUAL4YPE� ��SCRATCH��3IZE ACTUAL3IZE� ��SCRATCH��/3%RR MY%RR��OTHER�LOCAL�VARIABLES��

��EXTRACT�43!0)�EVENT�CLASS��

MY%RR��!%'ET0ARAM0TR��THE!PPLE%VENT��KEY43!0)%VENT#LASS�TYPE3HORT)NTEGER��ACTUAL4YPE��THE43!0)#LASS�SIZEOF�THE43!0)#LASS��ACTUAL3IZE��

IF��MY%RR��NO%RR�RETURN�MY%RR�

��EXTRACT�43!0)�EVENT�TYPE��

MY%RR��!%'ET0ARAM0TR��THE!PPLE%VENT��KEY43!0)%VENT4YPE�TYPE3HORT)NTEGER��ACTUAL4YPE��THE43!0)4YPE��SIZEOF�THE43!0)4YPE��ACTUAL3IZE��


��EXTRACT�STREAM�HANDLE��

MY%RR��!%'ET0ARAM0TR��THE!PPLE%VENT��KEY3TREAM(ANDLE�TYPE,ONG)NTEGER��ACTUAL4YPE��THE3TREAM��SIZEOF�THE3TREAM��ACTUAL3IZE��


��$ISPATCH�EVENT�TO�USER DEFINED�HANDLER�FUNCTION�HERE��RETURN�NO%RR�

]


��EXAMPLE� �CONT��

/3%RR)NSTALL43!0)%VENT(ANDLER��VOID�[

��4HIS�CODE�ONLY�WORKS�WHEN�COMPILED�FOR��+��IT�NEEDS�A��ROUTINE�DESCRIPTOR�FOR�HANDLE43!0)%VENT�TO�WORK�WITH�THE��-IXED�-ODE�MANAGER��

RETURN�!%)NSTALL%VENT(ANDLER��K43!0)%VENT#LASS�K43!0)%VENT!RRIVED

�!%%VENT(ANDLER500HANDLE43!0)%VENT�

��&!,3%��

]


ACS%VENT.OTIFY��/3��

The acsEventNotify( ) function allows an OS/2 PM application to request thata message be posted to its application queue when an incoming ACS event isavailable.

Syntax


2ET#ODE?T��ACS%VENT.OTIFY��!#3(ANDLE?TACS(ANDLE�(7.$ HWND�5,/.' MSG�"OOLEAN NOTIFY!LL�

Parameter



msg4HIS�IS�THE�USER DEFINED�MESSAGE�TO�BE�POSTED�WHEN�AN�INCOMINGEVENT�BECOMES�AVAILABLE��4HE�MP��AND�MP��PARAMETERS�OF�THEMESSAGE�WILL�CONTAIN�THE�FOLLOWING�MEMBERS�OF�THE!#3%VENT(EADER?T�STRUCTURE�

MP� ACS(ANDLE3(/24�&2/--0�MP� EVENT#LASS3(/24�&2/--0�MP� EVENT4YPE



Return Values


!#30/3)4)6%?!#+4HE�FUNCTION�COMPLETED�SUCCESSFULLY�AS�REQUESTED�BY�THEAPPLICATION��.O�ERRORS�WERE�DETECTED�0OSSIBLE�LOCAL�ERROR�RETURNS�ARE��NEGATIVE�RETURNS�


Application Notes


)F�THERE�ARE�ALREADY�EVENTS�IN�THE�RECEIVE�QUEUE�WAITING�TO�BE�RETRIEVEDWHEN�ACS%VENT.OTIFY��IS�CALLED��A�MESSAGE�WILL�BE�POSTED�FOR�EACHOF�THEM�IF�NOTIFY!LL�HAS�BEEN�SET�TO�425%�OR�A�SINGLE�MESSAGE�WILL�BEPOSTED�IF�NOTIFY!LL�HAS�BEEN�SET�TO�&!,3%�

!PPLICATIONS�WHICH�PROCESS�A�HIGH�VOLUME�OF�INCOMING�EVENTS�MAYCAUSE�THE�DEFAULT�APPLICATION�QUEUE��MESSAGES�MAX�TO�OVERFLOW�)N�THIS�CASE��INCREASE�THE�SIZE�OF�THE�APPLICATION�QUEUE�THAT�IS�CREATEDBY�SPECIFYING�A�LARGER�SIZE�IN�THE�7IN#REATE-SG1UEUE��FUNCTION��4HIS�MAY�NOT�BE�POSSIBLE�IF�AN�APPLICATION�FRAMEWORK�IS�GENERATINGTHE�MESSAGE�QUEUE�FOR�YOU��!LSO��THE�RATE�OF�NOTIFICATIONS�MAY�BEREDUCED�BY�SETTING�NOTIFY!LL�TO�&!,3%�



Example


�DEFINE�7-?!#3%6%.4�7-?53%2��

-2%35,4�%80%.4297ND0ROC��(7.$�HWND��5,/.'�MSG��-0!2!-�MP��-0!2!-�MP�[






CASE�7-?!#3%6%.4�

��MP��CONTAINS�AN�!#3(ANDLE?T��3(/24�&2/--0�MP��CONTAINS�AN�%VENT#LASS?T��3(/24�&2/--0�MP��CONTAINS�AN�%VENT4YPE?T


RETURN��


]RETURN�7IN$EF7INDOW0ROC��HWND��MSG��MP��MP��

]


ACS&LUSH%VENT1UEUE��

This function removes all events for the application on a ACS Streamassociated with the given handle and maintained by the API Client Library.Once this function returns the application may receive any new events thatarrive on this ACS Stream.

Syntax


2ET#ODE?T�!#3&LUSH%VENT1UEUE��!#3(ANDLE?T�ACS(ANDLE�

Parameters

acsHandle4HIS�IS�THE�HANDLE�TO�AN�ACTIVE�!#3�3TREAM��)F�THE�ACS(ANDLE�ISZERO��THEN�43!0)�WILL�FLUSH�ALL�ACTIVE�!#3�3TREAMS�FOR�THISAPPLICATION�

Return Values





Comments

/NCE�THIS�FUNCTION�RETURNS�THE�!0)�#LIENT�,IBRARY�WILL�NOT�HAVE�ANYEVENTS�QUEUED�FOR�THE�APPLICATION�ON�THE�SPECIFIED�!#3�3TREAM��4HEAPPLICATION�IS�READY�TO�START�RECEIVING�NEW�EVENTS�FROM�THE�4ELEPHONY3ERVER�



Application Notes

4HE�APPLICATION�SHOULD�EXERCISE�CAUTION�WHEN�CALLING�THIS�FUNCTION�SINCE�ALL�EVENTS�FROM�THE�SWITCH�ON�THE�ASSOCIATED�!#3�3TREAM�HAVEBEEN�DISCARDED��4HE�APPLICATION�HAS�NO�WAY�TO�DETERMINE�WHAT�KINDSOF�EVENTS�HAVE�BEEN�DESTROYED��AND�MAY�HAVE�LOST�EVENTS�THAT�RELAYIMPORTANT�STATUS�INFORMATION�FROM�THE�SWITCH�

4HIS�FUNCTION�DOES�NOT�DELETE�THE�!#3#LOSE3TREAM#ONF%VENT �SINCE�THIS�FUNCTION�CAN�NOT�BE�CALLED�AFTER�THE�ACS#LOSE3TREAM��FUNCTION�

4HE�ACS&LUSH%VENT1UEUE��FUNCTION�WILL�DELETE�ALL�OTHER�EVENTSQUEUED�TO�THE�APPLICATION�ON�THE�!#3�3TREAM��4HE!#35NIVERSAL&AILURE%VENT �AND�THE#34!5NIVERSAL&AILURE#ONF%VENT ��IN�PARTICULAR��WILL�BE�DELETED�IFTHEY�ARE�CURRENTLY�QUEUED�TO�THE�APPLICATION�


ACS%NUM3ERVER.AMES��

This function is used to enumerate the names of all the advertised services of aspecified stream type. This function is a synchronous call and has noassociated confirmation event.

Syntax

�INCLUDE��ACS�H�

TYPEDEF�"OOLEAN��%NUM3ERVER.AMES#" �CHAR SERVER.AME�UNSIGNED�LONG L0ARAM�

2ET#ODE?T ACS%NUM3ERVER.AMES �3TREAM4YPE?T STREAM4YPE�%NUM3ERVER.AMES#" CALLBACK��UNSIGNED�LONG L0ARAM�

Parameters

streamTypeINDICATES�THE�TYPE�OF�STREAM�REQUESTED��4HE�CURRENTLY�DEFINED�STREAMTYPES�ARE�34?#34!�AND�34?/!-�

callback4HIS�IS�A�POINTER�TO�A�CALLBACK�FUNCTION�WHICH�WILL�BE�INVOKED�FOREACH�OF�THE�ENUMERATED�SERVER�NAMES��ALONG�WITH�THE�USER DEFINEDPARAMETER�L0ARAM��)F�THE�CALLBACK�FUNCTION�RETURNS�&!,3%��ENUMERATION�WILL�TERMINATE�

lParam!�USER DEFINED�PARAMETER�WHICH�IS�PASSED�ON�EACH�INVOCATION�OF�THECALLBACK�FUNCTION�

Return Values

4HIS�FUNCTION�RETURNS�A�POSITIVE�ACKNOWLEDGMENT�OR�A�NEGATIVE�ERRORCONDITION��4HERE�IS�NO�CONFIRMATION�EVENT�FOR�THIS�FUNCTION�4HE�POSITIVE�RETURN�VALUE�IS�




!#3%22?5.+./7.4HE�REQUEST�HAS�FAILED�DUE�TO�UNKNOWN�NETWORK�PROBLEMS�

!#3%22?./3%26%24HE�REQUEST�HAS�FAILED�BECAUSE�THE�CLIENT�IS�USING�4#0�)0AND�)0�ADDRESSES�ARE�NOT�CONFIGURED�PROPERLY�

Comments

4HIS�FUNCTION�ENUMERATES�ALL�THE�KNOWN�ADVERTISED�SERVICES��INVOKINGTHE�CALLBACK�FUNCTION�FOR�EACH�ADVERTISED�SERVICE�NAME��4HESERVER.AME�PARAMETER�POINTS�TO�AUTOMATIC�STORAGE��THE�CALLBACKFUNCTION�MUST�MAKE�A�COPY�IF�IT�NEEDS�TO�PRESERVE�THIS�DATA��5NDER7INDOWS��THE�CALLBACK�FUNCTION�MUST�BE�EXPORTED�AND�ITS�ADDRESSOBTAINED�FROM�-AKE0ROC)NSTANCE��

!N�ACTIVE�!#3�3TREAM�IS�./4�REQUIRED�TO�CALL�THIS�FUNCTION�


ACS%NUM3ERVER.AMES��-ACINTOSH

This function is used to enumerate the names of all the advertised services of aspecified stream type. This function is a synchronous call and has noassociated confirmation event.

Syntax


�IF�53%32/54).%$%3#2)04/23ENUM[

UPP%NUM3ERVER.AMES0ROC)NFO��K0ASCAL3TACK"ASED\�2%35,4?3):%�3):%?#/$%��\�34!#+?2/54).%?0!2!-%4%2��3):%?#/$%�SIZEOF�UNSIGNED

LONG\�34!#+?2/54).%?0!2!-%4%2��3):%?#/$%�SIZEOF�CHAR�

TYPEDEF�5NIVERSAL0ROC0TR �%NUM3ERVER.AMES#"�

�DEFINE�.EW%NUM3ERVER.AMES0ROC�USER2OUTINE�<�%NUM3ERVER.AMES#"�<

.EW2OUTINE$ESCRIPTOR��0ROC0TR�USER2OUTINE�<UPP%NUM3ERVER.AMES0ROC)NFO��'ET#URRENT)3!�

�ELSETYPEDEF�PASCAL�"OOLEAN��%NUM3ERVER.AMES#" �

CHAR SERVER.AME�UNSIGNED�LONG L0ARAM�

�ENDIF

2ET#ODE?T ACS%NUM3ERVER.AMES �3TREAM4YPE?T STREAM4YPE�%NUM3ERVER.AMES#" CALLBACK��UNSIGNED�LONG L0ARAM�

Parameters

streamTypeINDICATES�THE�TYPE�OF�STREAM�REQUESTED��4HE�CURRENTLY�DEFINED�STREAMTYPES�ARE�34?#34!�AND�34?/!-�


callback4HIS�IS�A�UNIVERSAL�PROCEDURE�POINTER�TO�THE�CALLBACK�FUNCTION��THEADDRESS�OF�A��X��FUNCTION�OR�ROUTINE�DESCRIPTOR��WHICH�WILL�BEINVOKED�FOR�EACH�OF�THE�ENUMERATED�SERVER�NAMES��ALONG�WITH�THEUSER DEFINED�PARAMETER�L0ARAM��)F�THE�CALLBACK�FUNCTION�RETURNS&!,3%��ENUMERATION�WILL�TERMINATE�

lParam!�USER DEFINED�PARAMETER�WHICH�IS�PASSED�ON�EACH�INVOCATION�OF�THECALLBACK�FUNCTION�

Return Values

4HIS�FUNCTION�RETURNS�A�POSITIVE�ACKNOWLEDGMENT�OR�A�NEGATIVE�ERRORCONDITION��4HERE�IS�NO�CONFIRMATION�EVENT�FOR�THIS�FUNCTION�4HE�POSITIVE�RETURN�VALUE�IS�



!#3%22?5.+./7.4HE�REQUEST�HAS�FAILED�DUE�TO�UNKNOWN�NETWORK�PROBLEMS�

Comments

4HIS�FUNCTION�ENUMERATES�ALL�THE�KNOWN�ADVERTISED�SERVICES��INVOKINGTHE�CALLBACK�FUNCTION�FOR�EACH�ADVERTISED�SERVICE�NAME��4HESERVER.AME�PARAMETER�POINTS�TO�AUTOMATIC�STORAGE��THE�CALLBACKFUNCTION�MUST�MAKE�A�COPY�IF�IT�NEEDS�TO�PRESERVE�THIS�DATA

!N�ACTIVE�!#3�3TREAM�IS�./4�REQUIRED�TO�CALL�THIS�FUNCTION�


ACS1UERY!UTH)NFO��

Use acsQueryAuthInfo( ) to determine the login and password requirementswhen opening an ACS stream to a particular advertised CSTA service. Thisfunction call places the result of a query in a user-provided structure beforereturning; there is no confirmation event.

3YNTAX


2ET#ODE?T�ACS1UERY!UTH)NFO�3ERVER)$?T SERVER)$� ��).054��!#3!UTH)NFO?T AUTH)NFO� ��2%452.��

Parameters

serverID4HE�APPLICATION�PROVIDES�A�NULL TERMINATED�STRING�OF�MAXIMUM�SIZE!#3?-!8?3%26)#%)$��4HIS�STRING�CONTAINS�THE�NAME�OF�ANADVERTISED�#34!�SERVICE��IN�!3#))�FORMAT�

authInfo4HE�APPLICATION�PROVIDES�A�POINTER�TO�A�PRE ALLOCATED�STRUCTURE�INTOWHICH�THE�ACS1UERY!UTH)NFO��RETURNS�AUTHENTICATION�INFORMATIONABOUT�THE�#34!�SERVICE�NAMED�IN�SERVER)$��4HE�!#3!UTH)NFO?TSTRUCTURE�IS�DEFINED�AS�FOLLOWS�

TYPEDEF�ENUM[

2%15)2%3?%84%2.!,?!54(�� !54(?,/').?)$?/.,9��!54(?,/').?)$?)3?$%&!5,4��.%%$?,/').?)$?!.$?0!337$��!.9?,/').?)$��

]�!#3!UTH4YPE?T�

TYPEDEF�STRUCT[

!#3!UTH4YPE?T AUTH4YPE�,OGIN)$?T AUTH,OGIN)$�

]�!#3!UTH)NFO?T�


Return Values

ACS1UERY!UTH)NFO��RETURNS�THE�NEGATIVE�ERROR�CONDITIONS�BELOW�

!#3%22?"!$0!2!-%4%2/NE�OR�MORE�OF�THE�PARAMETERS�IS�INVALID�

!#3%22?./$2)6%2.O�43!0)�#LIENT�,IBRARY�$RIVER�WAS�FOUND�OR�INSTALLED�ONTHE�SYSTEM�

!#3%22?./3%26%24HE�ADVERTISED�SERVICE��SERVER)$�IS�NOT�AVAILABLE�IN�THENETWORK�

!#3%22?./2%3/52#%4HERE�ARE�INSUFFICIENT�RESOURCES�TO�QUERY�THE�ADVERTISEDSERVICE�

Background

4HE�4ELEPHONY�3ERVICES�ARCHITECTURE�ALLOWS�NETWORK�ADMINISTRATORSTO�GRANT�TELEPHONY�PRIVILEGES�TO�USERS��$EPENDING�ON�THEIMPLEMENTATION�OF�A�TELEPHONY�SERVER�AND�ITS�CLIENT�LIBRARIES��A�USERMAY�CONVINCE�TELEPHONY�SERVERS�OF�HIS�OR�HER�IDENTITY��AUTHENTICATE�BY�DIFFERENT�MEANS�

6ERSION��OF�43!0)�REQUIRED�APPLICATIONS�TO�SUPPLY�A�LOGIN�NAME�ANDPASSWORD�WHEN�CALLING�ACS/PEN3TREAM��THE�POINT�AT�WHICH�ATELEPHONY�SERVER�MUST�BE�CONVINCED�OF�A�USER�S�IDENTITY�

6ERSION��AND�FUTURE�VERSIONS�OFFER�SUPPORT�FOR�MULTIPLE�TYPES�OFAUTHENTICATION��!�TELEPHONY�SERVICE�MAY�STILL�REQUIRE��OR�SIMPLYACCEPT��A�LOGIN�AND�PASSWORD��OR�IT�MAY�RELY�ON�AN�EXTERNALAUTHENTICATION�SERVICE�TO�ESTABLISH�A�USER�S�IDENTITY�

4HE�4ELEPHONY�3ERVICES�ARCHITECTURE�OFFERS�SUPPORT�FOR�BOTH�METHODSIN�ANY�COMBINATION�

Usage

#ALL�ACS1UERY!UTH)NFO��TO�DETERMINE�THE�AUTHENTICATIONREQUIREMENTS�FOR�AN�ADVERTISED�SERVICE��0"8�$RIVER��4HE�CALLERMUST�PROVIDE�THE�NAME�OF�THE�ADVERTISED�SERVICE�AND�A�POINTER�TOSTORAGE�INTO�WHICH�ACS1UERY!UTH)NFO��WILL�PLACE�THE�QUERY�RESULTS�


7HEN�AN�APPLICATION�CALLS�ACS1UERY!UTH)NFO��THE�APPLICATION�MAYBLOCK�WHILE�THE�TELEPHONY�SERVICES�LIBRARY�QUERIES�THE�SPECIFIEDSERVICE�

%XAMINE�AUTH)NFO�AUTH4YPE�UPON�RETURN�FROM�ACS1UERY!UTH)NFO��TO�DETERMINE�WHAT�LOGIN)$�AND�PASSWD�PARAMETERS�TO�SUPPLY�TOACS/PEN3TREAM��FOR�THE�SERVICE�QUERIED�

2%15)2%3?%84%2.!,?!54(�

4HE�SERVICE�SPECIFIED�IN�THE�QUERY�REQUIRES�THE�USER�TOAUTHENTICATE�WITH�AN�EXTERNAL�AUTHENTICATION�SERVICE�BEFOREOPENING�A�STREAM��)F�AUTH)NFO�AUTH4YPE�CONTAINS�THIS�VALUE�ACS/PEN3TREAM��WILL�FAIL�FOR�THE�SERVICE�QUERIED�

!54(?,/').?)$?/.,9�

4HE�APPLICATION�CAN�ONLY�OPEN�A�STREAM�USING�THE�LOGIN)$RETURNED�IN�AUTH)NFO�AUTH,OGIN)$�

ACS/PEN3TREAM��WILL�IGNORE�PASSWD�FOR�THE�QUERIED�SERVICE�4HE�LOGIN)$�MUST�CONTAIN�THE�SAME�VALUE�ASAUTH)NFO�AUTH,OGIN)$��!N�APPLICATION�SHOULD�NOT�COLLECT�APASSWORD�FROM�ITS�USER�FOR�THIS�SERVICE�

!54(?,/').?)$?)3?$%&!5,4�

4HE�LOGIN)$�RETURNED�IN�AUTH)NFO�AUTH,OGIN)$�IS�THE�DEFAULTUSER�FOR�THIS�SERVICE��)F�THE�APPLICATION�SUBSEQUENTLY�SPECIFIESTHIS�LOGIN)$�OR�A�.5,,�POINTER�AS�LOGIN)$�TOACS/PEN3TREAM��PASSWD�WILL�BE�IGNORED�AND�MAY�BE�.5,,�

!LTERNATIVELY��TO�OPEN�A�STREAM�AS�A�DIFFERENT�USER�THANAUTH)NFO�AUTH,OGIN)$��THE�APPLICATION�MUST�SUPPLY�LOGIN)$�ANDPASSWD�TO�ACS/PEN3TREAM��

An application should take care to not collect a password if its user wants tobe identified as authInfo.authLoginID. If an application does not rememberthe last loginID selected by its user in a preferences file or other persistentstorage, the application should use authInfo.authLoginID as the defaultloginID when prompting its user for login information.


.%%$?,/').?)$?!.$?0!337$�

4HE�APPLICATION�MUST�SUPPLY�LOGIN)$�AND�PASSWD�TOACS/PEN3TREAM��

!.9?,/').?)$�

4HE�APPLICATION�MAY�SUPPLY�ANY�LOGIN)$�TO�ACS/PEN3TREAM��PASSWD�SHOULD�NOT�BE�COLLECTED�AND�WILL�BE�IGNORED�!PPLICATIONS�SHOULD�DEFAULT�TO�AUTH)NFO�AUTH,OGIN)$�IF�IT�ISNON EMPTY�


!#3�5NSOLICITED�%VENTS

4HIS�SECTION�DESCRIBES�UNSOLICITED�!#3�3TATUS�%VENTS�


!#35NIVERSAL&AILURE%VENT

This event can occur at any time (unsolicited) and can indicate, among otherthings, a failure or loss of the ACS Stream with the Telephony Server.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�THE�!#3�$ATA�4YPES�AND�#34!�$ATA4YPES�SECTIONS�FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

UNION[��!#35NIVERSAL&AILURE%VENT?T�FAILURE%VENT�]�U�

]�ACS5NSOLICITED�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT[

!#35NIVERSAL&AILURE?T�ERROR�]!#35NIVERSAL&AILURE%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�!#35.3/,)#)4%$��WHICH�IDENTIFIESTHIS�MESSAGE�AS�AN�!#3�UNSOLICITED�EVENT�


eventType4HIS�IS�A�TAG�WITH�THE�VALUE�!#3?5.)6%23!,?&!),52%��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�!#35NIVERSAL&AILURE%VENT �

error4HIS�PARAMETER�CONTAINS�A�4SERVER�OPERATION�ERROR��OR� CAUSE�VALUE �4SERVER�SECURITY�DATABASE�ERROR��OR�DRIVER�ERROR�FOR�THE�!#3�3TREAMGIVEN�IN��ACS(ANDLE�

Not all of the errors listed below will occur in an ACS Universal Failuremessage. Some of the errors occur only in error logs generated by theTserver.

4HE�POSSIBLE�VALUES�ARE�

TYPEDEF�ENUM�!#35NIVERSAL&AILURE?T�[43%26%2?342%!-?&!),%$��43%26%2?./?4(2%!$��43%26%2?"!$?$2)6%2?)$��43%26%2?$%!$?$2)6%2��43%26%2?-%33!'%?()'(?7!4%2?-!2+��43%26%2?&2%%?"5&&%2?&!),%$��43%26%2?3%.$?4/?$2)6%2��43%26%2?2%#%)6%?&2/-?$2)6%2��43%26%2?2%')342!4)/.?&!),%$��43%26%2?308?&!),%$��43%26%2?42!#%��43%26%2?./?-%-/29��43%26%2?%.#/$%?&!),%$��43%26%2?$%#/$%?&!),%$��43%26%2?"!$?#/..%#4)/.��43%26%2?"!$?0$5��43%26%2?./?6%23)/.��43%26%2?%#"?-!8?%8#%%$%$��43%26%2?./?%#"3��43%26%2?./?3$"��43%26%2?./?3$"?#(%#+?.%%$%$��43%26%2?3$"?#(%#+?.%%$%$��43%26%2?"!$?3$"?,%6%,��43%26%2?"!$?3%26%2)$��43%26%2?"!$?342%!-?490%��43%26%2?"!$?0!337/2$?/2?,/').��43%26%2?./?53%2?2%#/2$��43%26%2?./?$%6)#%?2%#/2$��43%26%2?$%6)#%?./4?/.?,)34��43%26%2?53%23?2%342)#4%$?(/-%��43%26%2?./?!7!90%2-)33)/.��43%26%2?./?(/-%0%2-)33)/.��43%26%2?./?!7!9?7/2+4/0��43%26%2?"!$?$%6)#%?2%#/2$��43%26%2?$%6)#%?./4?3500/24%$��


43%26%2?).35&&)#)%.4?0%2-)33)/.��43%26%2?./?2%3/52#%?4!'��43%26%2?).6!,)$?-%33!'%��43%26%2?%8#%04)/.?,)34��43%26%2?./4?/.?/!-?,)34��43%26%2?0"8?)$?./4?).?3$"��43%26%2?53%2?,)#%.3%3?%8#%%$%$��43%26%2?/!-?$2/0?#/..%#4)/.��43%26%2?./?6%23)/.?2%#/2$��43%26%2?/,$?6%23)/.?2%#/2$��43%26%2?"!$?0!#+%4��43%26%2?/0%.?&!),%$��43%26%2?/!-?).?53%��43%26%2?$%6)#%?./4?/.?(/-%?,)34��43%26%2?$%6)#%?./4?/.?#!,,?#/.42/,?,)34��43%26%2?$%6)#%?./4?/.?!7!9?,)34��43%26%2?$%6)#%?./4?/.?2/54%?,)34��43%26%2?$%6)#%?./4?/.?-/.)4/2?$%6)#%?,)34��43%26%2?$%6)#%?./4?/.?-/.)4/2?#!,,?$%6)#%?,)34��43%26%2?./?#!,,?#!,,?-/.)4/2?0%2-)33)/.��43%26%2?(/-%?$%6)#%?,)34?%-049��43%26%2?#!,,?#/.42/,?,)34?%-049��43%26%2?!7!9?,)34?%-049��43%26%2?2/54%?,)34?%-049��43%26%2?-/.)4/2?$%6)#%?,)34?%-049��43%26%2?-/.)4/2?#!,,?$%6)#%?,)34?%-049��43%26%2?53%2?!4?(/-%?7/2+4/0��43%26%2?$%6)#%?,)34?%-049��43%26%2?"!$?'%4?$%6)#%?,%6%,��43%26%2?$2)6%2?5.2%')34%2%$��43%26%2?./?!#3?342%!-��43%26%2?$2/0?/!-��43%26%2?%#"?4)-%/54��43%26%2?"!$?%#"��43%26%2?!$6%24)3%?&!),%$��43%26%2?.%47!2%?&!),52%��43%26%2?4$)?15%5%?&!5,4��43%26%2?$2)6%2?#/.'%34)/.��43%26%2?./?4$)?"5&&%23��43%26%2?/,$?).6/+%)$��43%26%2?(7-!2+?4/?,!2'%��43%26%2?3%4?%#"?4/?,/7��43%26%2?./?2%#/2$?).?&),%��43%26%2?%#"?/6%2$5%��43%26%2?"!$?07?%.#2904)/.��43%26%2?"!$?43%26?02/4/#/,��43%26%2?"!$?$2)6%2?02/4/#/,��43%26%2?"!$?42!.30/24?490%��43%26%2?0$5?6%23)/.?-)3-!4#(��43%26%2?6%23)/.?-)3-!4#(��43%26%2?,)#%.3%?-)3-!4#(��43%26%2?"!$?!442)"54%?,)34��43%26%2?"!$?4,)34?490%��43%26%2?"!$?02/4/#/,?&/2-!4��43%26%2?/,$?43,)"��


43%26%2?"!$?,)#%.3%?&),%��43%26%2?./?0!4#(%3��43%26%2?3934%-?%22/2��43%26%2?/!-?,)34?%-049��_43%26%2?4#0?&!),%$��43%26%2?308?$)3!",%$��43%26%2?4#0?$)3!",%$��43%26%2?2%15)2%$?-/$5,%3?./4?,/!$%$��

�� 43%26%2?42!.30/24?).?53%?"9?/!-�� 43%26%2?./?.$3?/!-?0%2-)33)/.�� 43%26%2?/0%.?3$"?,/'?&!),%$�� 43%26%2?).6!,)$?,/'?3):%�� 43%26%2?72)4%?3$"?,/'?&!),%$�� 43%26%2?.4?&!),52%�� 43%26%2?,/!$?,)"?&!),%$�� 43%26%2?).6!,)$?$2)6%2�� 43%26%2?2%')3429?%22/2�� 43%26%2?$50,)#!4%?%.429�� 43%26%2?$2)6%2?,/!$%$��

$2)6%2?$50,)#!4%?!#3(!.$,%��$2)6%2?).6!,)$?!#3?2%15%34��$2)6%2?!#3?(!.$,%?2%*%#4)/.��$2)6%2?).6!,)$?#,!33?2%*%#4)/.��$2)6%2?'%.%2)#?2%*%#4)/.��$2)6%2?2%3/52#%?,)-)4!4)/.��$2)6%2?!#3(!.$,%?4%2-).!4)/.��$2)6%2?,).+?5.!6!),!",%��$2)6%2?/!-?).?53%��

]�!#35NIVERSAL&AILURE?T�

Tserver Operation errors

4SERVER�OPERATION�ERRORS�INDICATE�THAT�THERE�IS�AN�ERROR�IN�THE�3ERVICE2EQUEST��4HESE�INCLUDE�THE�FOLLOWING�SPECIFIC�ERROR�VALUES�

43%26%2?342%!-?&!),%$4HE�#LIENT�,IBRARY�DETECTED�THAT�THE�!#3�3TREAM�FAILED�

43%26%2?./?4(2%!$/NE�OR�MORE�THE�THREADS��PROCESSES�THAT�MAKE�UP�THE4SERVER�COULD�NOT�BE�CREATED�

43%26%2?"!$?$2)6%2?)$/NE�OF�THE�THREADS��PROCESSES�THAT�MAKE�UP�THE�4SERVERENCOUNTERED�A�BAD�$RIVER�)DENTIFICATION�NUMBER�DURINGPROCESSING�


43%26%2?$%!$?$2)6%2!�$RIVER�HAS�NOT�SENT�A��HEART�BEAT�MESSAGES�TO�THE�4SERVERFORM�THE�LAST�THREE�MINUTES��4HE�$RIVER�MAY�BE�IN�ANINOPERABLE�STATE�

43%26%2?-%33!'%?()'(?7!4%2?-!2+4HE�MESSAGE�RATE�BETWEEN�A�CLIENT�AND�THE�4SERVER�OR�THE4SERVER�AND�A�$RIVER�HAS�EXCEEDED�THE�HIGH�WATER�MARK�RATE�

43%26%2?&2%%?"5&&%2?&!),%$4HE�4SERVER�WAS�UNABLE�TO�FREE�4SERVER�$RIVER�)NTERFACE�4$)�MEMORY�

43%26%2?3%.$?4/?$2)6%24HE�4SERVER�WAS�UNABLE�TO�SEND�A�MESSAGE�TO�A�$RIVER�

43%26%2?2%#%)6%?&2/-?$2)6%24HE�4SERVER�WAS�UNABLE�TO�RECEIVE�A�MESSAGE�FROM�A�$RIVER�

43%26%2?2%')342!4)/.?&!),%$!�$RIVER�S�ATTEMPT�TO�REGISTER�WITH�THE�4SERVER�FAILED�

43%26%2?308?&!),%$!�.ET7ARE�308�CALL�FAILED�IN�THE�4SERVER�

43%26%2?42!#%5SED�BY�THE�4SERVER�FOR�DEBUGGING�PURPOSES�ONLY�

43%26%2?./?-%-/294HE�4SERVER�WAS�UNABLE�TO�ALLOCATE�A�PIECE�OF�MEMORY�

43%26%2?%.#/$%?&!),%$4HE�4SERVER�WAS�UNABLE�TO�ENCODE�A�MESSAGE�FOR�SHIPMENTTO�A�CLIENT�WORKSTATION�

43%26%2?$%#/$%?&!),%$4HE�4SERVER�WAS�UNABLE�TO�DECODE�A�MESSAGE�FROM

A�CLIENT�WORKSTATION�

43%26%2?"!$?#/..%#4)/.4HE�4SERVER�TRIED�TO�PROCESS�A�REQUEST�WITH�A�BAD�CLIENTCONNECTION�)$�NUMBER�


43%26%2?"!$?0$54HE�4SERVER S�INTERNAL�TABLE�OF�0ROTOCOL�$ESCRIPTOR�5NITS�ISCORRUPTED�

43%26%2?./?6%23)/.4HE�4SERVER�PROCESSED�A�!#3/PEN3TREAM#ONF%VENT�FROM�A$RIVER�IN�WHICH�ONE�OR�MORE�THE�VERSION�FIELDS�WAS�NOT�SET�

43%26%2?%#"?-!8?%8#%%$%$4HE�4SERVER�CAN�NOT�PROCESS�A�MESSAGE�FROM�THE�DRIVERBECAUSE�THE�MESSAGE�IS�LARGER�THAN�THE�SUM�OF�THE�%#"SALLOCATED�FOR�THIS�DRIVER�

43%26%2?./?%#"34HE�4SERVER�HAS�NO�AVAILABLE�%#"S�TO�SEND�EVENTS�TO�THECLIENT�

43%26%2?./?2%3/52#%?4!'4HE�4SERVER�WAS�UNABLE�TO�GET�A�RESOURCE�TAG�FOR�THE�PURPOSEOF�ALLOCATING�MEMORY�

43%26%2?).6!,)$?-%33!'%4HE�4SERVER�RECEIVED�AN�INVALID�4SERVER�/!-�MESSAGE�

43%26%2?%#"?/6%2$5%4HE�4ELEPHONY�3ERVER�USES�THIS�ERROR�CODE�IN�THE�LOG�FILE�!N�APPLICATION�WILL�NOT�RECEIVE�IT�

43%26%2?"!$?07?%.#2904)/.4HE�4ELEPHONY�3ERVER�USES�THIS�ERROR�CODE�IN�THE�LOG�FILE�!N�APPLICATION�WILL�NOT�RECEIVE�IT�

43%26%2?"!$?42!.30/24?490%4HE�4ELEPHONY�3ERVER�USES�THIS�ERROR�CODE�IN�THE�LOG�FILE�!N�APPLICATION�WILL�NOT�RECEIVE�IT�

43%26%2?"!$?43%26?02/4/#/,4HE�APPLICATION�HAS�REQUESTED�A�43!0)�PROTOCOL�VERSION�THATTHE�4ELEPHONY�3ERVER�DOES�NOT�PROVIDE�


43%26%2?"!$?$2)6%2�02/4/#/,4HE�APPLICATION�HAS�REQUESTED�A�43!0)�PROTOCOL�VERSION�THATTHE�4ELEPHONY�3ERVER�PROVIDES�BUT�THE�0"8�$RIVER�DOES�NOTPROVIDE�

43%26%2?0$5?6%23)/.?-)3-!4#(4HE�APPLICATION�HAS�INVOKED�A�SERVICE�THAT�THE�STREAMVERSION�DOES�NOT�SUPPORT��4HIS�RESULTED�IN�THE�CLIENT�LIBRARYSENDING�THE�4ELEPHONY�3ERVER�A�0ROTOCOL�$ATA�5NIT��0$5THAT�IS�NOT�SUPPORTED�IN�THE�43!0)�VERSION�ON�THAT�STREAM�

43%26%2?"!$?02/4/#/,?&/2-!44HE�API6ER�PARAMETER�VALUE�IS�NOT�IN�THE�PROPER�SYNTAX�

43%26%2?/,$?43,)"4HE�APPLICATION�IS�USING�A�43,)"�LIBRARY�OF�AN�EARLIERVINTAGE�THAN�THE�VERSION�IT�IS�REQUESTING�IN�AN�OPEN�STREAMCALL�

43%26%2?2%15)2%$?-/$5,%3?./4?,/!$%$

43%26%2?42!.30/24?).?53%?"9?/!-

43%26%2?./?.$3?/!-?0%2-)33)/.

43%26%2?/0%.?3$"?,/'?&!),%$

43%26%2?).6!,)$?,/'?3):%�

43%26%2?72)4%?3$"?,/'?&!),%$

43%26%2?.4?&!),52%�

43%26%2?,/!$?,)"?&!),%$

43%26%2?).6!,)$?$2)6%2

43%26%2?2%')3429?%22/2

43%26%2?$50,)#!4%?%.429

43%26%2?$2)6%2?,/!$%$

Tserver Security Data Base errors

%RROR�VALUES�IN�THIS�CATEGORY�INDICATE�THAT�THERE�IS�AN�ERROR�IN�THEPROCESS�OF�AN�EVENT�WHICH�REQUIRES�A�CHECK�AGAINST�THE�3ECURITY�$ATA"ASE��4HIS�TYPE�INCLUDES�ONE�OF�THE�FOLLOWING�SPECIFIC�ERROR�VALUES�


43%26%2?./?3$"/NE�OR�MORE�THE�FILES�THAT�MAKEUP�THE�3ECURITY�$ATA�"ASE�ISNOT�PRESENT�ON�THE�SERVER�OR�CAN�NOT�BE�OPENED�

43%26%2?./?3$"?#(%#+?.%%$%$4HE�REQUESTED�SERVICE�EVENT�DOES�NOT�REQUIRE�A�3ECURITY�$ATA"ASE�CHECK�

43%26%2?3$"?#(%#+?.%%$%$4HE�REQUESTED�SERVICE�EVENT�DOES�REQUIRE�A�3ECURITY�$ATA"ASE�CHECK�

43%26%2?"!$?3$"?,%6%,4HE�4SERVER S�INTERNAL�TABLE�OF�!0)�CALLS�INDICATING�WHICHLEVEL�OF�SECURITY�TO�PERFORM�ON�THE�REQUEST�IS�CORRUPTED�

43%26%2?"!$?3%26%2)$4HE�4SERVER�REJECTED�AN�!#3/PEN3TREAM�REQUEST�BECAUSETHE�3ERVER�)$�IN�THE�MESSAGE�DID�NOT�MATCH�A�$RIVERSUPPORTED�BY�THIS�4SERVER�

43%26%2?"!$?342%!-?490%4HE�STREAM�TYPE�AN�!#3/PEN3TREAM�REQUEST�WAS�INVALID�

43%26%2?"!$?0!337/2$?/2?,/').4HE�0ASSWORD�OR�,OGIN�OR�BOTH�FROM�AN�!#3/PEN3TREAMREQUEST�DID�NOT�MATCH�AN�ENTRY�IN�THE�"INDERY�ON�THE�SERVERTHE�4SERVER�IS�RUNNING�ON�

43%26%2?./?53%2?2%#/2$.O�USER�RECORD�WAS�FOUND�IN�THE�3ECURITY�$ATA�"ASE�FOR�THELOGIN�SPECIFIED�IN�THE�!#3/PEN3TREAM�REQUEST�

43%26%2?./?$%6)#%?2%#/2$.O�DEVICE�RECORD�WAS�FOUND�IN�THE�3ECURITY�$ATA�"ASE�FORTHE�DEVICE�SPECIFIED�IN�THE�!0)�CALL�

43%26%2?$%6)#%?./4?/.?,)344HE�SPECIFIED�DEVICE�IN�AN�!0)�CALL�WAS�NOT�FOUND�ON�ANYDEVICE�LIST�ADMINISTERED�FOR�THIS�USER�


43%26%2?53%23?2%342)#4%$?(/-%4HE�4SERVER�IS�ADMINISTERED�TO�RESTRICT�USERS�TO�HOMEWORKTOPS�SO�NO�CHECKING�IS�DONE�AGAINST�AWAY�WORKTOPDEVICES�

43%26%2?./?!7!90%2-)33)/.4HE�4SERVER�REJECTED�A�SERVICE�REQUEST�BECAUSE�THE�DEVICEDID�NOT�MATCH�A�DEVICE�ASSOCIATED�WITH�AN�AWAY�WORKTOP�

43%26%2?./?(/-%0%2-)33)/.4HE�4SERVER�REJECTED�A�SERVICE�REQUEST�BECAUSE�THE�DEVICEDID�NOT�MATCH�A�DEVICE�ASSOCIATED�WITH�A�HOME�WORKTOP�

43%26%2?./?!7!9?7/2+4/04HE�AWAY�WORKTOP�THE�USER�IS�WORKING�FROM�IS�NOTADMINISTERED�IN�THE�3ECURITY�$ATA�"ASE�

43%26%2?"!$?$%6)#%?2%#/2$4HE�4SERVER�READ�A�DEVICE�RECORD�FROM�THE�3ECURITY�$ATA"ASE�THAT�CONTAINED�CORRUPTED�INFORMATION�

43%26%2?$%6)#%?./4?3500/24%$4HE�DEVICE�IN�THE�!0)�CALL�IS�ADMINISTERED�TO�BE�SUPPORTEDBY�A�DIFFERENT�4SERVER�

43%26%2?).35&&)#)%.4?0%2-)33)/.4HE�DEVICE�IN�THE�!0)�CALL�IS�AT�THE�USERS�AWAY�WORKTOP�ANDTHE�DEVICE�HAS�A�HIGHER�PERMISSION�LEVEL�THAN�THE�USER�PREVENTING�THE�USER�FROM�CONTROLLING�THE�DEVICE�

43%26%2?%8#%04)/.?,)344HE�DEVICE�IN�THE�!0)�CALL�IS�ON�AN�EXCEPTION�LIST�WHICH�ISADMINISTERED�AS�PART�OF�THE�INFORMATION�FOR�THIS�USER�

Driver Errors

%RROR�VALUES�IN�THIS�CATEGORY�INDICATE�THAT�THE�DRIVER�DETECTED�AN�ERROR�4HIS�TYPE�INCLUDES�ONE�OF�THE�FOLLOWING�SPECIFIC�ERROR�VALUES�

$2)6%2?$50,)#!4%?!#3(!.$,%4HE�ACS(ANDLE�GIVEN�FOR�AN�!#3/PEN3TREAM�REQUEST�ISALREADY�IN�USE�FOR�A�SESSION��4HE�ALREADY�OPEN�SESSION�WITHTHE�ACS(ANDLE�IS�REMAINS�OPEN�


$2)6%2?).6!,)$?!#3?2%15%344HE�!#3�MESSAGE�CONTAINS�AN�INVALID�OR�UNKNOWN�REQUEST�4HE�REQUEST�IS�REJECTED�

$2)6%2?!#3?(!.$,%?2%*%#4)/.!�#34!�REQUEST�WAS�ISSUED�WITH�NO�PRIOR�!#3/PEN3TREAMREQUEST��4HE�REQUEST�IS�REJECTED�

$2)6%2?).6!,)$?#,!33?2%*%#4)/.4HE�DRIVER�RECEIVED�A�MESSAGE�CONTAINING�AN�INVALID�ORUNKNOWN�MESSAGE�CLASS��4HE�REQUEST�IS�REJECTED�

$2)6%2?'%.%2)#?2%*%#4)/.4HE�DRIVER�DETECTED�AN�INVALID�MESSAGE�FOR�SOMETHING�OTHERTHAN�MESSAGE�TYPE�OR�MESSAGE�CLASS��4HIS�IS�AN�INTERNALERROR�AND�SHOULD�BE�REPORTED�

$2)6%2?2%3/52#%?,)-)4!4)/.4HE�DRIVER�DID�NOT�HAVE�ADEQUATE�RESOURCES��I�E��MEMORY�ETC��TO�COMPLETE�THE�REQUESTED�OPERATION��4HIS�IS�AN�INTERNALERROR�AND�SHOULD�BE�REPORTED�

$2)6%2?!#3(!.$,%?4%2-).!4)/.$UE�TO�PROBLEMS�WITH�THE�LINK�TO�THE�SWITCH�THE�DRIVER�HASFOUND�IT�NECESSARY�TO�TERMINATE�THE�SESSION�WITH�THE�GIVENACS(ANDLE��4HE�SESSION�WILL�BE�CLOSED��AND�ALL�OUTSTANDINGREQUESTS�WILL�TERMINATE�

$2)6%2?,).+?5.!6!),!",%4HE�DRIVER�WAS�UNABLE�TO�OPEN�THE�NEW�SESSION�BECAUSE�NOLINK�WAS�AVAILABLE�TO�THE�0"8��4HE�LINK�MAY�HAVE�BEENPLACED�IN�THE�",/#+%$�STATE��OR�IT�MAY�HAVE�BEEN�TAKENOFF LINE�

$2)6%2?/!-?).?53%4HERE�IS�ALREADY�AN�OPEN�/!- TYPE�STREAM�TO�THE�0"8DRIVER��!�DRIVER�CAN�ONLY�HAVE�A�SINGLE�/!-�STREAM�OPEN�ATANY�TIME�


!#3�$ATA�4YPES

This section defines all the data types which are used with the ACS functionsand messages and may repeat data types already shown in the ACS ControlFunctions. Refer to the specific commands for any operational differences inthese data types. The ACS data types are type defined in the acs.h header file.

The definition for ACSHandle_t is client platform specific.

!#3�#OMMON�$ATA�4YPES

This section specifies the common ACS data types.

TYPEDEF�INT�2ET#ODE?T�

�DEFINE�!#30/3)4)6%?!#+��3UCCESSFUL�FUNCTION�RETURN��

��%RROR�#ODES��

�DEFINE�!#3%22?!0)6%2$%.)%$ � ��4HE�!0)�6ERSION��REQUESTED�IS�INVALID��AND�NOT�SUPPORTED�BY�THE�!0)�#LIENT�,IBRARY��

�DEFINE�!#3%22?"!$0!2!-%4%2 � ��/NE�OR�MORE�OF�THE��PARAMETERS�IS�INVALID��

�DEFINE�!#3%22?$50342%!- � ��4HIS�RETURN�INDICATES��THAT�AN�!#3�3TREAM�IS��ALREADY�ESTABLISHED��WITH�THE�REQUESTED��3ERVER��

�DEFINE�!#3%22?./$2)6%2 � ��4HIS�ERROR�RETURN��VALUE�INDICATES�THAT��NO�!0)�#LIENT�,IBRARY��$RIVER�WAS�FOUND�OR�INSTALLED�ON�THE�SYSTEM��

�DEFINE�!#3%22?./3%26%2 � ��THE�REQUESTED�3ERVER

.OTE


��IS�NOT�PRESENT�IN�THE��NETWORK��

�DEFINE�!#3%22?./2%3/52#% � ��THERE�ARE�INSUFFICIENT��RESOURCESTO�OPEN�A��!#3�3TREAM��

�DEFINE�!#3%22?5"5&3-!,, � ��4HE�USER�BUFFER�SIZE��WAS�SMALLER�THAN�THE��SIZE�OF��THE�NEXT��AVAILABLE�EVENT��

�DEFINE�!#3%22?./-%33!'% � ��4HERE�WERE�NO�MESSAGES�AVAILABLE�TO�RETURN�TO��THE�APPLICATION��

�DEFINE�!#3%22?5.+./7. � ��4HE�!#3�3TREAM�HAS��ENCOUNTEREDAN��UNSPECIFIED�ERROR��

�DEFINE�!#3%22?"!$($, �� 4HE�!#3�(ANDLE�IS��INVALID��

�DEFINE�!#3%22?342%!-?&!),%$ �� 4HE�!#3�3TREAM�HAS��FAILED�DUE�TO��NETWORK�PROBLEMS��.O�FURTHER��OPERATIONS�ARE��POSSIBLE�ON�THIS�

��STREAM��

�DEFINE�!#3%22?./"5&&%23 �� 4HERE�WERE�NOT��ENOUGH�BUFFERS��AVAILABLE�TO�PLACE��AN�OUTGOING�MESSAGE��ON�THE�SEND�QUEUE��.O�MESSAGE�HAS�BEEN��SENT��

�DEFINE�!#3%22?15%5%?&5,, �� 4HE�SEND�QUEUE�IS��FULL��.O�MESSAGE�HAS�BEEN�SENT��

TYPEDEF�UNSIGNED�LONG )NVOKE)$?T�

TYPEDEF�ENUM�[!00?'%.?)$� ��APPLICATION�WILL�PROVIDE�INVOKE)$S�

��ANY�� BYTE�VALUE�IS�LEGAL,)"?'%.?)$ ��LIBRARY�WILL�GENERATE�INVOKE)$S�IN


��THE�RANGE�� ]�)NVOKE)$4YPE?T�

TYPEDEF�UNSIGNED�SHORT� %VENT#LASS?T�

��DEFINES�FOR�!#3�EVENT�CLASSES

�DEFINE !#32%15%34 ��DEFINE !#35.3/,)#)4%$ ��DEFINE !#3#/.&)2-!4)/. �

TYPEDEF�UNSIGNED�SHORT�%VENT4YPE?T� ��EVENT�TYPES�ARE��DEFINED�IN�ACS�H��AND�CSTA�H

TYPEDEF�CHAR�"OOLEAN�TYPEDEF�CHAR�.ULLTYPE�

�DEFINE��!#3?/0%.?342%!- ��DEFINE��!#3?/0%.?342%!-?#/.& ��DEFINE��!#3?#,/3%?342%!- ��DEFINE��!#3?#,/3%?342%!-?#/.& ��DEFINE��!#3?!"/24?342%!- ��DEFINE��!#3?5.)6%23!,?&!),52%?#/.& ��DEFINE��!#3?5.)6%23!,?&!),52% �

TYPEDEF�ENUM�3TREAM4YPE?T�[34?#34!��34?/!-��

]�3TREAM4YPE?T�

TYPEDEF�CHAR�3ERVER)$?T;��=�

TYPEDEF�CHAR�,OGIN)$?T;��=�

TYPEDEF�CHAR�0ASSWD?T;��=�

TYPEDEF�CHAR�!PP.AME?T;��=�

TYPEDEF�ENUM�,EVEL?T�[!#3?,%6%,��!#3?,%6%,��!#3?,%6%,��!#3?,%6%,��

]�,EVEL?T�

TYPEDEF�CHAR�6ERSION?T;��=�

!#3�%VENT�$ATA�4YPES

This section specifies the ACS data types used in the construction of genericACSEvent_t structures (see section 4.6).


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[

UNION[!#35NIVERSAL&AILURE%VENT?T�FAILURE%VENT�]�U�

]�!#35NSOLICITED%VENT�

TYPEDEF�STRUCT[

)NVOKE)$?T INVOKE)$�UNION[!#3/PEN3TREAM#ONF%VENT?T ACSOPEN�!#3#LOSE3TREAM#ONF%VENT?T ACSCLOSE�!#35NIVERSAL&AILURE#ONF%VENT?T FAILURE%VENT�]�U�

]�!#3#ONFIRMATION%VENT�


#34!�#ONTROL�3ERVICES�AND�#ONFIRMATION�%VENTS

This section defines the CSTA functions associated with the TelephonyServer’s Services. These functions are used to determine types and capabilitiesof Telephony Servers and Drivers connected to Telephony Servers and todetermine the set of devices an application can control, monitor and query.


CSTA'ET!0)#APS��

cstaGetAPICaps( ) obtains the CSTA API function and event capabilitieswhich are supported on an open CSTA stream. The stream could be a localPBX driver or a remote PBX Driver on a network. If a stream provides aCSTA service then it also provides the corresponding CSTA confirmationevent.

Syntax


2ET#ODE?T CSTA'ET!0)#APS�!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�

Parameters

acsHandle4HIS�IS�THE�HANDLE�TO�AN�ACTIVE�!#3�3TREAM��4HIS�SERVICE�WILL�RETURNIN�ITS�CONFIRMATION�INFORMATION�ABOUT�THE�#34!�SERVICES�AVAILABLE�ONTHIS�STREAM�


Return Values


,IBRARY GENERATED�)DENTIFIERS� �IF�THE�FUNCTION�CALL�COMPLETESSUCCESSFULLY�IT�WILL�RETURN�A�POSITIVE�VALUE��I�E��THE�INVOKEIDENTIFIER��)F�THE�CALL�FAILS�A�NEGATIVE�ERROR��CONDITION�WILLBE�RETURNED��&OR�LIBRARY GENERATED�IDENTIFIERS�THE�RETURN�WILLNEVER�BE�ZERO��


!PPLICATION GENERATED�)DENTIFIERS� �IF�THE�FUNCTION�CALLCOMPLETES�SUCCESSFULLY�IT�WILL�RETURN�A�ZERO��VALUE��)F�THECALL�FAILS�A�NEGATIVE�ERROR��CONDITION�WILL�BE�RETURNED�&OR�APPLICATION GENERATED�IDENTIFIERS�THE�RETURN�WILL�NEVER�BEPOSITIVE��

4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!'ET!0)#APS#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�



Comments

)F�THIS�FUNCTION�RETURNS�WITH�A�0/3)4)6%?!#+��THE��REQUEST�HAS�BEENFORWARDED�TO�THE�4ELEPHONY�3ERVER��AND�THE�APPLICATION�WILL�RECEIVEAN�INDICATION�OF�THE�EXTENT�OF�#34!�SERVICE�SUPPORT�IN�THE#34!'ET!0)#APS#ONF%VENT ��!N�ACTIVE�!#3�3TREAM�IS�REQUIREDTO�THE�SERVER�BEFORE�THIS�FUNCTION�IS�CALLED�

4HE�APPLICATION�MAY�USE�THIS�COMMAND�TO�DETERMINE�WHICH�FUNCTIONSAND�EVENTS�ARE�SUPPORTED�ON�AN�OPEN�#34!�STREAM��4HIS�WILL�AVOIDUNNECESSARY�NEGATIVE�ACKNOWLEDGMENTS�FROM�THE�4ELEPHONY�3ERVERWHEN�A�SPECIFIC�!0)�FUNCTION�OR�EVENT�IS�NOT�SUPPORTED�


#34!'ET!0)#APS#ONF%VENT

This event is in response to the cstaGetAPICaps( ) function and it indicateswhich CSTA services are available on the CSTA stream.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�#34!�$ATA�4YPES�FOR�A�COMPLETEDESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[ !#3(ANDLE?T ACS(ANDLE�

%VENT#LASS?T EVENT#LASS�%VENT4YPE?T EVENT4YPE�


TYPEDEF�STRUCT[

!#3%VENT(EADER?T EVENT(EADER�UNION

[STRUCT[


� #34!'ET!0)#APS#ONF%VENT?T�GET!0)CAPS�]�U�

]�CSTA#ONFIRMATION�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!'ET!0)#APS#ONF%VENT?T�[��SHORT��ALTERNATE#ALL��SHORT��ANSWER#ALL��SHORT��CALL#OMPLETION��SHORT��CLEAR#ALL��SHORT��CLEAR#ONNECTION��SHORT��CONFERENCE#ALL��SHORT��CONSULTATION#ALL��SHORT��DEFLECT#ALL��SHORT��PICKUP#ALL��SHORT��GROUP0ICKUP#ALL��SHORT��HOLD#ALL��SHORT��MAKE#ALL��SHORT��MAKE0REDICTIVE#ALL��SHORT��QUERY-WI��SHORT��QUERY$ND��SHORT��QUERY&WD��SHORT��QUERY!GENT3TATE�


��SHORT��QUERY,AST.UMBER��SHORT��QUERY$EVICE)NFO��SHORT��RECONNECT#ALL��SHORT��RETRIEVE#ALL��SHORT��SET-WI��SHORT��SET$ND��SHORT��SET&WD��SHORT��SET!GENT3TATE��SHORT��TRANSFER#ALL��SHORT��EVENT2EPORT��SHORT��CALL#LEARED%VENT��SHORT��CONFERENCED%VENT��SHORT��CONNECTION#LEARED%VENT��SHORT��DELIVERED%VENT��SHORT��DIVERTED%VENT��SHORT��ESTABLISHED%VENT��SHORT��FAILED%VENT��SHORT��HELD%VENT��SHORT��NETWORK2EACHED%VENT��SHORT��ORIGINATED%VENT��SHORT��QUEUED%VENT��SHORT��RETRIEVED%VENT��SHORT��SERVICE)NITIATED%VENT��SHORT��TRANSFERRED%VENT��SHORT��CALL)NFORMATION%VENT��SHORT��DO.OT$ISTURB%VENT��SHORT��FORWARDING%VENT��SHORT��MESSAGE7AITING%VENT��SHORT��LOGGED/N%VENT��SHORT��LOGGED/FF%VENT��SHORT��NOT2EADY%VENT��SHORT��READY%VENT��SHORT��WORK.OT2EADY%VENT��SHORT��WORK2EADY%VENT��SHORT��BACK)N3ERVICE%VENT��SHORT��OUT/F3ERVICE%VENT��SHORT��PRIVATE%VENT��SHORT��ROUTE2EQUEST%VENT��SHORT��RE2OUTE��SHORT��ROUTE3ELECT��SHORT��ROUTE5SED%VENT��SHORT��ROUTE%ND%VENT��SHORT��MONITOR$EVICE��SHORT��MONITOR#ALL��SHORT��MONITOR#ALLS6IA$EVICE��SHORT��CHANGE-ONITOR&ILTER��SHORT��MONITOR3TOP��SHORT��MONITOR%NDED��SHORT��SNAPSHOT$EVICE2EQ��SHORT��SNAPSHOT#ALL2EQ��SHORT��ESCAPE3ERVICE��SHORT��PRIVATE3TATUS%VENT��SHORT��ESCAPE3ERVICE%VENT��SHORT��ESCAPE3ERVICE#ONF��SHORT��SEND0RIVATE%VENT�


��SHORT��SYS3TAT2EQ��SHORT��SYS3TAT3TART��SHORT��SYS3TAT3TOP��SHORT��CHANGE3YS3TAT&ILTER��SHORT��SYS3TAT2EQ%VENT��SHORT��SYS3TAT2EQ#ONF��SHORT��SYS3TAT%VENT�]�#34!'ET!0)#APS#ONF%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICHIDENTIFIES�THIS�MESSAGE�AS�A�#34!�CONFIRMATION�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?'%4!0)?#!03?#/.&��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�#34!'ET!0)#APS#ONF%VENT�

getAPIcaps4HIS�STRUCTURE�CONTAINS�AN�INTEGER�FOR�EACH�POSSIBLE�#34!�CAPABILITYWHICH�INDICATES�WHETHER�THE�CAPABILITY�IS�SUPPORTED��!�VALUE�OF��INDICATES�THE�CAPABILITY�IS�NOT�SUPPORTED��A�POSITIVE�VALUE�INDICATESTHAT�IT�IS�SUPPORTED��.OTE�THAT�DIFFERENT�CAPABILITIES�ARE�SUPPORTED�ONDIFFERENT�STREAM�VERSIONS��4HIS�PARAMETER�SHOWS�WHAT�CAPABILITIES�ARESUPPORTED�ON�THE�STREAM�WHERE�THE�CONFIRMATION�HAS�BEEN�RECEIVED�3TREAMS�USING�OTHER�VERSIONS�MAY�SUPPORT�A�DIFFERENT�CAPABILITY�SET�

Comments

4HIS�EVENT�WILL�PROVIDE�THE�APPLICATION�WITH�COMPATIBILITYINFORMATION�FOR�A�SPECIFIC�4ELEPHONY�3ERVER�ON�A�COMMAND�EVENTBASIS��!LL�THE�COMMANDS�AND�EVENTS�SUPPORTED�BY�A�4ELEPHONY�3ERVERMUST�BE�SUPPORTED�AS�DEFINED�IN�THIS�DOCUMENT�


CSTA'ET$EVICE,IST��

This is used to obtain the list of Devices that can be controlled, monitored,queried or routed for the ACS Stream indicated by the acsHandle.

Syntax


2ET#ODE?T CSTA'ET$EVICE,IST�!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�LONG INDEX�#34!,EVEL?TLEVEL

Parameters

acsHandle4HIS�IS�THE�HANDLE�TO�AN�ACTIVE�!#3�3TREAM�


index4HE�SECURITY�DATA�BASE�COULD�CONTAIN�A�LARGE�NUMBER�OF�DEVICES�THAT�AUSER�HAS�PRIVILEGE�OVER��SO�THIS�!0)�CALL�WILL�RETURN�ONLY#34!?-!8?'%4$%6)#%�DEVICES�IN�ANY�ONE#34!'ET$EVICE,IST#ONF%VENT��WHICH�MEANS�SEVERAL�CALLS�TOCSTA'ET$EVICE,IST��MAY�BE�NECESSARY�TO�RETRIEVE�ALL�THE�DEVICES�)NDEX�SHOULD�BE�SET�OF� ��THE�FIRST�TIME�THIS�!0)�IS�CALLED�AND�THEN�SETTO�THE�VALUE�OF�)NDEX�RETURNED�IN�THE�CONFIRMATION�EVENT��)NDEX�WILLBE�SET�BACK�TO� ��IN�THE�#34!'ET$EVICE,IST#ONF%VENT�WHICHCONTAINS�THE�LAST�BATCH�OF�DEVICES�


level4HIS�PARAMETER�SPECIFIES�THE�CLASS�OF�SERVICE�FOR�WHICH�THE�USER�WANTSTO�KNOW�THE�SET�OF�DEVICES�THAT�CAN�BE�CONTROLLED�VIA�THIS�!#3�STREAM�LEVEL�MUST�BE�SET�TO�ONE�OF�THE�FOLLOWING�

TYPEDEF�ENUM�#34!,EVEL?T�[��#34!?(/-%?7/2+?4/0��#34!?!7!9?7/2+?4/0��#34!?$%6)#%?$%6)#%?-/.)4/2��#34!?#!,,?$%6)#%?-/.)4/2��#34!?#!,,?#/.42/,��#34!?2/54).'��#34!?#!,,?#!,,?-/.)4/2��]�#34!,EVEL?T�

The level CSTA_CALL_CALL_MONITOR is not supported by theCSTAGetDeviceList() call. To determine if an ACS stream haspermission to do call/call monitoring, use the API callCSTAQueryCallMonitor( ).

Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!'ET$EVICE,IST#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�


.OTE




#34!'ET$EVICE,IST#ONF%VENT

This event is in response to the cstaGetDeviceList( ) function and it provide alist of the devices which can be controlled for the indicated ACS Level. It isalso possible to receive an ACSUniversalFailureConf event in response to acstaGetDeviceList() call.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND�#34!�$ATA�4YPESFOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[

!#3%VENT(EADER?T EVENT(EADER�UNION[STRUCT

[)NVOKE)$?T INVOKE)$�UNION[��#34!'ET$EVICE,IST#ONF%VENT?T�GET$EVICE,IST�]�U�


]�#34!%VENT?T�

TYPEDEF�ENUM�3$",EVEL?T�[��./?3$"?#(%#+).'�� !#3?/.,9��!#3?!.$?#34!?#(%#+).'��]�3$",EVEL?T�

TYPEDEF�STRUCT�#34!'ET$EVICE,IST?T�[��LONG��INDEX��#34!,EVEL?T��LEVEL�]�#34!'ET$EVICE,IST?T�

TYPEDEF�STRUCT�$EVICE,IST�[


��SHORT��COUNT��$EVICE)$?T��DEVICE;��=�]�$EVICE,IST�

TYPEDEF�STRUCT�#34!'ET$EVICE,IST#ONF%VENT?T�[��3$",EVEL?T��DRIVER3DB,EVEL��#34!,EVEL?T��LEVEL��LONG��INDEX��$EVICE,IST��DEV,IST�]�#34!'ET$EVICE,IST#ONF%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�!#3�CONFIRMATION�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?'%4?$%6)#%?,)34?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN#34!'ET$EVICE,IST#ONF%VENT �

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION��)T�ISUSED�TO�MATCH�A�SPECIFIC�FUNCTION�REQUEST�WITH�ITS�CONFIRMATION�EVENTS�

driverSdbLevel4HIS�PARAMETER�INDICATES�THE�3ECURITY�,EVEL�WITH�WHICH�THE�$RIVERREGISTERED��0OSSIBLE�VALUES�ARE�

./?3$"?#(%#+).' .OT�5SED�

!#3?/.,9 #HECK�!#3/PEN3TREAM�REQUESTS�ONLY

!#3?!.$?#34!?#(%#+).' #HECK�!#3/PEN3TREAM�AND�ALL

APPLICABLE�#34!�MESSAGES

index4HIS�PARAMETER�INDICATES�TO�THE�CLIENT�APPLICATION�THE�CURRENT�INDEXTHE�4SERVER�IS�USING�FOR�RETURNING�THE�LIST�OF�DEVICES��4HE�CLIENTAPPLICATION�SHOULD�RETURN�THIS�VALUE�IN�THE�NEXT�CALL�TO#34!'ET$EVICE,IST�TO�CONTINUE�RECEIVING�DEVICES��!�VALUE�OF�� INDICATES�THERE�ARE�NO�MORE�DEVICES�IN�THE�LIST�


devlist4HIS�PARAMETER�IS�A�STRUCTURE�WHICH�CONTAINS�AN�ARRAY�OF�$EVICE)$?TWHICH�CONTAIN�THE�DEVICES�FOR�THIS�STREAM�


CSTA1UERY#ALL-ONITOR��

This is used to determine the if a given ACS stream has permission to docall/call monitoring in the security database.

Syntax


2ET#ODE?T CSTA1UERY#ALL-ONITOR�!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$

Parameters



Return Values





4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!1UERY#ALL-ONITOR #ONF%VENT�MESSAGE�TO�ENSURE�THAT�THE�SERVICE�REQUEST�HAS�BEEN�AC KNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THE�SWITCH�




#34!1UERY#ALL-ONITOR#ONF%VENT

This event is in response to the cstaQueryCallMonitor( ) function and itprovide a list of the devices which can be controlled for the indicated ACSLevel.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�THE�!#3�$ATA�4YPES�AND�#34!�$ATA4YPES�SECTIONS�FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


��#34!1UERY#ALL-ONITOR#ONF%VENT?T��QUERY#ALL-ONITOR�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!1UERY#ALL-ONITOR#ONF%VENT?T�[��"OOLEAN��CALL-ONITOR�]�#34!1UERY#ALL-ONITOR#ONF%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICH��IDENTI FIES��THIS�MESSAGE�AS�AN�!#3�CONFIRMATION�EVENT�


eventType4HIS�IS�A�TAG�WITH�THE�VALUE��#34!?15%29?#!,,?-/.)4/2? #/.&��WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN�#34!1UERY#ALL-ON ITOR#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION��)T�ISUSED�TO�MATCH�A�SPECIFIC�FUNCTION�REQUEST�WITH�ITS�CONFIRMATION�EVENTS�

callMonitor4HIS�PARAMETER�INDICATES�WHETHER�OR�NOT��425%�OR�&!,3%�THE�!#33TREAM�HAS�CALL�CALL�MONITORING�PRIVILEGE�


#34!�%VENT�$ATA�4YPES

This section defines all the event data types which are used with the CSTAfunctions and messages and may repeat data types already shown in the CSTAControl Functions. Refer to the specific commands for any operationaldifferences in these data types. The complete set of CSTA data types is givenin - CSTA Data Types. The CSTA data types are type defined in theCSTA.H header file.

An application always receives a generic CSTAEvent_t event structure. Thisstructure contains an ACSEventHeader_t structure which contains informationcommon to all events. This common information includes:

♦ ACS(ANDLE��3PECIFIES�THE�!#3�3TREAM�THE�EVENT�ARRIVED�ON�♦ EVENT#LASS��)DENTIFIES�THE�EVENT�AS�AN�!#3�CONFIRMATION��!#3

UNSOLICITED��#34!�CONFIRMATION��OR�#34!�UNSOLICITED�EVENT�♦ EVENT4YPE��)DENTIFIES�THE�SPECIFIC�TYPE�OF�MESSAGE��-AKE#ALL�

CONFIRMATION�EVENT��(OLD#ALL�EVENT��ETC�♦ PRIVATE$ATA��0RIVATE�DATA�DEFINED�BY�THE�SPECIFIED�DRIVER�VENDOR�

The CSTAEvent_t structure then consists of a union of the four possibleeventClass types; ACS confirmation, ACS unsolicited, CSTA confirmation orCSTA unsolicited event. Each eventClass type itself consists of a union of allthe possible eventTypes for that class. Each eventClass may contain commoninformation such as invokeID and monitorCrossRefID.

��#34!�#ONTROL�3ERVICES�(EADER�&ILE��#34!�(��

�INCLUDE��ACS�H��DEFINES�FOR�#34!�EVENT�CLASSES

�DEFINE #34!2%15%34 ��DEFINE #34!5.3/,)#)4%$ ��DEFINE #34!#/.&)2-!4)/. ��DEFINE #34!%6%.42%0/24 �


TYPEDEF�STRUCT�[)NVOKE)$?T INVOKE)$�UNION[

#34!2OUTE2EQUEST%VENT?T ROUTE2EQUEST�#34!2OUTE2EQUEST%XT%VENT?T ROUTE2EQUEST%XT�#34!2E2OUTE2EQUEST?T RE2OUTE2EQUEST�#34!%SCAPE3VC2EQ%VENT?T ESCAPE3VC2EQEUST�#34!3YS3TAT2EQ%VENT?T SYS3TAT2EQUEST�

]�U�]�#34!2EQUEST%VENT�

TYPEDEF�STRUCT�[UNION[

#34!2OUTE2EGISTER!BORT%VENT?T REGISTER!BORT�#34!2OUTE5SED%VENT?T ROUTE5SED�#34!2OUTE5SED%XT%VENT?T ROUTE5SED%XT�#34!2OUTE%ND%VENT?T ROUTE%ND�#34!0RIVATE%VENT?T PRIVATE%VENT�#34!3YS3TAT%VENT?T SYS3TAT�#34!3YS3TAT%NDED%VENT?T SYS3TAT%NDED�]U�

]�#34!%VENT2EPORT�


TYPEDEF�STRUCT�[#34!-ONITOR#ROSS2EF)$?T��MONITOR#ROSS2EF)D�UNION[

#34!#ALL#LEARED%VENT?T CALL#LEARED�#34!#ONFERENCED%VENT?T CONFERENCED�#34!#ONNECTION#LEARED%VENT?T CONNECTION#LEARED�#34!$ELIVERED%VENT?T DELIVERED�#34!$IVERTED%VENT?T DIVERTED�#34!%STABLISHED%VENT?T ESTABLISHED�#34!&AILED%VENT?T FAILED�#34!(ELD%VENT?T HELD�#34!.ETWORK2EACHED%VENT?T NETWORK2EACHED�#34!/RIGINATED%VENT?T ORIGINATED�#34!1UEUED%VENT?T QUEUED�#34!2ETRIEVED%VENT?T RETRIEVED�#34!3ERVICE)NITIATED%VENT?T SERVICE)NITIATED�#34!4RANSFERRED%VENT?T TRANSFERRED�#34!#ALL)NFORMATION%VENT?T CALL)NFORMATION�#34!$O.OT$ISTURB%VENT?T DO.OT$ISTURB�#34!&ORWARDING%VENT?T FORWARDING�#34!-ESSAGE7AITING%VENT?T MESSAGE7AITING�#34!,OGGED/N%VENT?T LOGGED/N�#34!,OGGED/FF%VENT?T LOGGED/FF�#34!.OT2EADY%VENT?T NOT2EADY�#34!2EADY%VENT?T READY�#34!7ORK.OT2EADY%VENT?T WORK.OT2EADY�#34!7ORK2EADY%VENT?T WORK2EADY�#34!"ACK)N3ERVICE%VENT?T BACK)N3ERVICE�#34!/UT/F3ERVICE%VENT?T OUT/F3ERVICE�#34!0RIVATE3TATUS%VENT?T PRIVATE3TATUS�#34!-ONITOR%NDED%VENT?T�� MONITOR%NDED�]�U�

]�#34!5NSOLICITED%VENT�


TYPEDEF�STRUCT[)NVOKE)$?T��INVOKE)$�UNION[

#34!!LTERNATE#ALL#ONF%VENT?T ALTERNATE#ALL�#34!!NSWER#ALL#ONF%VENT?T ANSWER#ALL�#34!#ALL#OMPLETION#ONF%VENT?T CALL#OMPLETION�#34!#LEAR#ALL#ONF%VENT?T CLEAR#ALL�#34!#LEAR#ONNECTION#ONF%VENT?T CLEAR#ONNECTION�#34!#ONFERENCE#ALL#ONF%VENT?T CONFERENCE#ALL�#34!#ONSULTATION#ALL#ONF%VENT?T CONSULTATION#ALL�#34!$EFLECT#ALL#ONF%VENT?T DEFLECT#ALL�#34!0ICKUP#ALL#ONF%VENT?T PICKUP#ALL�#34!'ROUP0ICKUP#ALL#ONF%VENT?T GROUP0ICKUP#ALL�#34!(OLD#ALL#ONF%VENT?T HOLD#ALL�#34!-AKE#ALL#ONF%VENT?T MAKE#ALL�#34!-AKE0REDICTIVE#ALL#ONF%VENT?T MAKE0REDICTIVE#ALL�#34!1UERY-WI#ONF%VENT?T QUERY-WI�#34!1UERY$ND#ONF%VENT?T QUERY$ND�#34!1UERY&WD#ONF%VENT?T QUERY&WD�#34!1UERY!GENT3TATE#ONF%VENT?T QUERY!GENT3TATE�#34!1UERY,AST.UMBER#ONF%VENT?T QUERY,AST.UMBER�#34!1UERY$EVICE)NFO#ONF%VENT?T QUERY$EVICE)NFO�#34!2ECONNECT#ALL#ONF%VENT?T RECONNECT#ALL�#34!2ETRIEVE#ALL#ONF%VENT?T RETRIEVE#ALL�#34!3ET-WI#ONF%VENT?T SET-WI�#34!3ET$ND#ONF%VENT?T SET$ND�#34!3ET&WD#ONF%VENT?T SET&WD�#34!3ET!GENT3TATE#ONF%VENT?T SET!GENT3TATE�#34!4RANSFER#ALL#ONF%VENT?T RANSFER#ALL�#34!5NIVERSAL&AILURE#ONF%VENT?T UNIVERSAL&AILURE�#34!-ONITOR#ONF%VENT?T MONITOR3TART�#34!#HANGE-ONITOR&ILTER#ONF%VENT?T CHANGE-ONITOR&ILTER�#34!-ONITOR3TOP#ONF%VENT?T MONITOR3TOP�#34!3NAPSHOT$EVICE#ONF%VENT?T SNAPSHOT$EVICE�#34!3NAPSHOT#ALL#ONF%VENT?T SNAPSHOT#ALL�#34!2OUTE2EGISTER2EQ#ONF%VENT?T ROUTE2EGISTER�#34!2OUTE2EGISTER#ANCEL#ONF%VENT?T ROUTE#ANCEL�#34!%SCAPE3VC#ONF%VENT?T ESCAPE3ERVICE�#34!3YS3TAT2EQ#ONF%VENT?T SYS3TAT2EQ�#34!3Y33TAT3TART#ONF%VENT?T SYS3TAT3TART�#34!3YS3TAT3TOP#ONF%VENT?T SYS3TAT3TOP�#34!#HANGE3YS3TAT&ILTER#ONF%VENT?T CHANGE3YS3TAT&ILTER�#34!'ET!0)#APS#ONF%VENT?T GET!0)#APS�#34!'ET$EVICE,IST#ONF%VENT?T GET$EVICE,IST�#34!1UERY#ALL-ONITOR#ONF%VENT?T QUERY#ALL-ONITOR�]�U�

]�#34!#ONFIRMATION%VENT�

�DEFINE�#34!?-!8?(%!0��


TYPEDEF�STRUCT[!#3%VENT(EADER?T EVENT(EADER�UNION[

!#35NSOLICITED%VENT ACS5NSOLICITED�!#3#ONFIRMATION%VENT ACS#ONFIRMATION�#34!2EQUEST%VENT CSTA2EQUEST�#34!5NSOLICITED%VENT CSTA5NSOLICITED�#34!#ONFIRMATION%VENT CSTA#ONFIRMATION�]�EVENT�

CHAR��HEAP;#34!?-!8?(%!0=�]�#34!%VENT?T


C h a p t e r 5 Switching Function Services

This section describes Telephony Services. Applications use TelephonyServices to control calls and activate switch features. Switching FunctionsServices are divided into Basic Call Control Services and TelephonySupplementary Services.

"ASIC�#ALL�#ONTROL�3ERVICES

Basic Call Control Services allows applications to:

u establish, control, and "tear-down" calls at a device or within the switch,

u answer incoming calls at a device, and

u activate/de-activate switch features.

Each Basic Call Control Service request has an associated confirmation eventmessage. The confirmation message returns the status and other service-specific information to the application. TSAPI always returns confirmationevent messages for successful function calls. If TSAPI cannot successfullyprocess a function call then

u TSAPI does not send the service request to the PBX Driver

u TSAPI does not generate a confirmation event


As noted in Chapter 4, section Sending CSTA Requests and Responses, theapplication sets the invokeID type (when it opens the stream) to either librarygenerated or application generated. As described in that section, applicationsmay use application generated invokeIDs to index into data structures invarious ways. The application may also use the invokeID to match resultswith specific service requests.

When TSAPI successfully processes an application request, TSAPI sends theapplication a confirmation event. This conformation means that TSAPI hassuccessfully processed the request, not that the PBX driver or PBX hassuccessfully processed the request. For example, TSAPI will send anapplication a CSTAMakeCallConfEvent after TSAPI (not the PBX)successfully processes a cstaMakeCall( ) request. Further information fromthe PBX Driver or PBX will arrive in call events or unsolicited status events.An application interested in the results of a request should check for a functionconfirmation event and any applicable unsolicited status events (see StatusReporting Services).

To receive events, an application must have an active ACS Stream and animplement an event handling mechanism. Further, the reception of unsolicitedevents requires an active monitor. See the Control Services and StatusReporting Services sections for more information on events.

Not every Driver implementation will support all Telephony functions. Theapplication should use the cstaGetAPICaps function to determine whichTelephony Services are supported.

.OTE


#34!5NIVERSAL&AILURE#ONF%VENT

The CSTA universal failure confirmation event provides a generic negativeresponse from the server/switch for a previous requested service. TheCSTAUniversalFailureConfEvent will be sent in place of any confirmationevent described in this section when the requested function fails. Theconfirmation events defined for each Switching Function in this section areonly sent when that function completes successfully.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND�#34!�$ATA�4YPESIN�#HAPTER��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[#34!5NIVERSAL&AILURE#ONF%VENT�UNIVERSAL&AILURE�]�U�

]��CSTA#ONFIRMATION�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT[

5NIVERSAL&AILURE?T ERROR�]�#34!5NIVERSAL&AILURE#ONF%VENT?T�

TYPEDEF�ENUM�#34!5NIVERSAL&AILURE?T�[��'%.%2)#?5.30%#)&)%$��'%.%2)#?/0%2!4)/.��2%15%34?).#/-0!4)",%?7)4(?/"*%#4��6!,5%?/54?/&?2!.'%��/"*%#4?./4?+./7.��).6!,)$?#!,,).'?$%6)#%��


��).6!,)$?#!,,%$?$%6)#%��).6!,)$?&/27!2$).'?$%34).!4)/.��02)6),%'%?6)/,!4)/.?/.?30%#)&)%$?$%6)#%��02)6),%'%?6)/,!4)/.?/.?#!,,%$?$%6)#%��02)6),%'%?6)/,!4)/.?/.?#!,,).'?$%6)#%��).6!,)$?#34!?#!,,?)$%.4)&)%2��).6!,)$?#34!?$%6)#%?)$%.4)&)%2��).6!,)$?#34!?#/..%#4)/.?)$%.4)&)%2��).6!,)$?$%34).!4)/.��).6!,)$?&%!452%��).6!,)$?!,,/#!4)/.?34!4%��).6!,)$?#2/33?2%&?)$��).6!,)$?/"*%#4?490%��3%#52)49?6)/,!4)/.��'%.%2)#?34!4%?).#/-0!4)"),)49��).6!,)$?/"*%#4?34!4%��).6!,)$?#/..%#4)/.?)$?&/2?!#4)6%?#!,,��./?!#4)6%?#!,,��./?(%,$?#!,,��./?#!,,?4/?#,%!2��./?#/..%#4)/.?4/?#,%!2��./?#!,,?4/?!.37%2��./?#!,,?4/?#/-0,%4%��'%.%2)#?3934%-?2%3/52#%?!6!),!"),)49��3%26)#%?"539��2%3/52#%?"539��2%3/52#%?/54?/&?3%26)#%��.%47/2+?"539��.%47/2+?/54?/&?3%26)#%��/6%2!,,?-/.)4/2?,)-)4?%8#%%$%$��#/.&%2%.#%?-%-"%2?,)-)4?%8#%%$%$��'%.%2)#?35"3#2)"%$?2%3/52#%?!6!),!"),)49��/"*%#4?-/.)4/2?,)-)4?%8#%%$%$��%84%2.!,?425.+?,)-)4?%8#%%$%$��/5434!.$).'?2%15%34?,)-)4?%8#%%$%$��'%.%2)#?0%2&/2-!.#%?-!.!'%-%.4��0%2&/2-!.#%?,)-)4?%8#%%$%$��5.30%#)&)%$?3%#52)49?%22/2��3%15%.#%?.5-"%2?6)/,!4%$��4)-%?34!-0?6)/,!4%$��0!#?6)/,!4%$��3%!,?6)/,!4%$��'%.%2)#?5.30%#)&)%$?2%*%#4)/.��'%.%2)#?/0%2!4)/.?2%*%#4)/.��$50,)#!4%?).6/#!4)/.?2%*%#4)/.��5.2%#/'.):%$?/0%2!4)/.?2%*%#4)/.��-)3490%$?!2'5-%.4?2%*%#4)/.��2%3/52#%?,)-)4!4)/.?2%*%#4)/.��!#3?(!.$,%?4%2-).!4)/.?2%*%#4)/.��3%26)#%?4%2-).!4)/.?2%*%#4)/.��2%15%34?4)-%/54?2%*%#4)/.��2%15%343?/.?$%6)#%?%8#%%$%$?2%*%#4)/.��5.2%#/'.):%$?!0$5?2%*%#4)/.��-)3490%$?!0$5?2%*%#4)/.��"!$,9?3425#452%$?!0$5?2%*%#4)/.��


��).)4)!4/2?2%,%!3).'?2%*%#4)/.��5.2%#/'.):%$?,).+%$)$?2%*%#4)/.��,).+%$?2%30/.3%?5.%80%#4%$?2%*%#4)/.��5.%80%#4%$?#(),$?/0%2!4)/.?2%*%#4)/.��-)3490%$?2%35,4?2%*%#4)/.��5.2%#/'.):%$?%22/2?2%*%#4)/.��5.%80%#4%$?%22/2?2%*%#4)/.��-)3490%$?0!2!-%4%2?2%*%#4)/.��./.?34!.$!2$��]�#34!5NIVERSAL&AILURE?T�

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�NEWLY�OPENED�!#3�3TREAM�

eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!�CONFIRMATION�EVENT�

eventType4HIS�TAG�WITH�A�VALUE��#34!?5.)6%23!,?&!),52%?#/.&�IDENTIFIES��THIS�MESSAGE�AS�AN�#34!5NIVERSAL&AILURE#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�FUNCTION�SERVICE�REQUEST�INSTANCE�THAT�HASFAILED�AT�THE�SERVER�OR�AT�THE�SWITCH��4HIS�IDENTIFIER�IS�PROVIDED�TO�THEAPPLICATION�WHEN�A�SERVICE�REQUEST�IS�MADE�

error4HIS�PARAMETER�CONTAINS�AN�ERROR�VALUE�FROM�ONE�OF�THE�FOLLOWINGCLASSES��5NSPECIFIED��/PERATION��3TATE�)NCOMPATIBILITY��3YSTEM2ESOURCE��3UBSCRIBED�2ESOURCE��0ERFORMANCE�-ANAGEMENT��OR3ECURITY��4HE�HEADINGS�THE�FOLLOW�CONTAIN�THE�SPECIFIC�ERRORS�IN�THESECLASSES�

Unspecified Errors

%RROR�VALUES�IN�THIS�CATEGORY�INDICATE�THAT�AN�ERROR�HAS�OCCURRED�THAT�ISNOT�AMONG�THE�OTHER�ERROR�TYPES��4HIS�TYPE�INCLUDES�THE�FOLLOWINGSPECIFIC�ERROR�VALUES�


'%.%2)#?5.30%#)&)%$

'%.%2)#?5.30%#)&)%$?2%*%#4)/.

Operation errors

%RROR�VALUES�IN�THIS�CATEGORY�INDICATE�THAT�THERE�IS�AN�ERROR�IN�THE3ERVICE�2EQUEST��4HIS�TYPE�INCLUDES�ONE�OF�THE�FOLLOWING�SPECIFICERROR�VALUES�

'%.%2)#?/0%2!4)/.

'%.%2)#?/0%2!4)/.?2%*%#4)/.4HIS�ERROR�INDICATE�THAT�THE�SERVER�HAS�DETECTED�AN�ERROR�INTHE�OPERATION�CLASS��BUT�THAT�IT�IS�NOT�ONE�OF�THE�DEFINEDERRORS��OR�THE�SERVER�CANNOT�BE�ANY�MORE�SPECIFIC�

2%15%34?).#/-0!4)",%?7)4(?/"*%#44HE�REQUEST�IS�NOT�COMPATIBLE�WITH�THE�OBJECT�

$50,)#!4%?).6/#!4)/.4HE�INVOKE)$�VIOLATES�8��OR�8��ASSIGNMENT�RULES�

5.2%#/'.):%$?/0%2!4)/.?2%*%#4)/.4HE�OPERATION�IS�NOT�DEFINED�IN�43!0)�

6!,5%?/54?/&?2!.'%4HE�PARAMETER�HAS�A�VALUE�THAT�IS�NOT�IN�THE�RANGE�DEFINED�FORTHE�SERVER�

/"*%#4?./4?+./7.4HE�PARAMETER�HAS�A�VALUE�THAT�IS�NOT�KNOWN�TO�THE�SERVER�

).6!,)$?#!,,).'?$%6)#%4HE�CALLING�DEVICE�IS�NOT�VALID�

).6!,)$?#!,,%$?$%6)#%4HE�CALLED�DEVICE�IS�NOT�VALID�

02)6),%'%?6)/,!4)/.?/.?30%#)&)%$?$%6)#%4HE�REQUEST�CANNOT�BE�PROVIDED�BECAUSE�THE�SPECIFIED�DEVICEIS�NOT�AUTHORIZED�FOR�THE�3ERVICE�


).6!,)$?&/27!2$).'?$%34).!4)/.4HE�REQUEST�CANNOT�BE�PROVIDED�BECAUSE�THE�FORWARDINGDESTINATION�DEVICE�IS�NOT�VALID�

02)6),%'%?6)/,!4)/.?/.?#!,,%$?$%6)#%4HE�REQUEST�CANNOT�BE�PROVIDED�BECAUSE�THE�CALLED�DEVICE�ISNOT�AUTHORIZED�FOR�THE�3ERVICE�

02)6),%'%?6)/,!4)/.?/.?#!,,).'?$%6)#%4HE�REQUEST�CANNOT�BE�PROVIDED�BECAUSE�THE�CALLING�DEVICE�ISNOT�AUTHORIZED�FOR�THE�3ERVICE�

).6!,)$?#34!?#!,,?)$%.4)&)%24HE�CALL�IDENTIFIER�IS�NOT�VALID�

).6!,)$?#34!?$%6)#%?)$%.4)&)%24HE�$EVICE�)DENTIFIER�IS�NOT�VALID�

).6!,)$?#34!?#/..%#4)/.?)$%.4)&)%24HE�#ONNECTION�IDENTIFIER�IS�NOT�VALID�

).6!,)$?$%34).!4)/.4HE�3ERVICE�2EQUEST�SPECIFIED�A�DESTINATION�THAT�IS�NOT�VALID�

).6!,)$?&%!452%4HE�3ERVICE�2EQUEST�SPECIFIED�A�FEATURE�THAT�IS�NOT�VALID�

).6!,)$?!,,/#!4)/.?34!4%4HE�3ERVICE�2EQUEST�INDICATED�AN�ALLOCATION�CONDITION�THAT�ISNOT�VALID�

).6!,)$?#2/33?2%&?)$4HE�3ERVICE�2EQUEST�SPECIFIED�A�#ROSS 2EFERENCE�)D�THAT�ISNOT�IN�USE�AT�THIS�TIME�

).6!,)$?/"*%#4?490%4HE�3ERVICE�2EQUEST�SPECIFIED�AN�OBJECT�TYPE�THAT�IS�OUTSIDETHE�RANGE�OF�VALID�OBJECT�TYPES�FOR�THE�3ERVICE�

3%#52)49?6)/,!4)/.4HE�REQUEST�VIOLATES�A�SECURITY�REQUIREMENT�


State incompatibility errors

%RROR�VALUES�IN�THIS�CATEGORY�INDICATE�THAT�THE�3ERVICE�2EQUEST�WASNOT�COMPATIBLE�WITH�THE�CONDITION�OF�A�RELATED�#34!�OBJECT��4HISTYPE�INCLUDES�THE�FOLLOWING�SPECIFIC�ERROR�VALUES�

'%.%2)#?34!4%?).#/-0!4)"),)494HE�SERVER�IS�UNABLE�TO�BE�ANY�MORE�SPECIFIC�

).6!,)$?/"*%#4?34!4%4HE�OBJECT�IS�IN�THE�INCORRECT�STATE�FOR�THE�3ERVICE��4HISGENERAL�ERROR�VALUE�MAY�BE�USED�WHEN�THE�SERVER�ISN�T�ABLE�TOBE�ANY�MORE�SPECIFIC�

).6!,)$?#/..%#4)/.?)$?&/2?!#4)6%?#!,,4HE�#ONNECTION�IDENTIFIER�SPECIFIED�IN�THE�!CTIVE�#ALLPARAMETER�OF�THE�REQUEST�IS�NOT�IN�THE�CORRECT�STATE�

./?!#4)6%?#!,,4HE�REQUESTED�3ERVICE�OPERATES�ON�AN�ACTIVE�CALL��BUT�THERE�ISNO�ACTIVE�CALL�

./?(%,$?#!,,4HE�REQUESTED�3ERVICE�OPERATES�ON�A�HELD�CALL��BUT�THESPECIFIED�CALL�IS�NOT�IN�THE�(ELD�STATE�

./?#!,,?4/?#,%!24HERE�IS�NO�CALL�ASSOCIATED�WITH�THE�#34!�#ONNECTIONIDENTIFIER�OF�THE�#LEAR�#ALL�REQUEST�

./?#/..%#4)/.?4/?#,%!24HERE�IS�NO�#ONNECTION�FOR�THE�#34!�#ONNECTION�IDENTIFIERSPECIFIED�AS�#ONNECTION�4O�"E�#LEARED�

./?#!,,?4/?!.37%24HERE�IS�NO�CALL�ACTIVE�FOR�THE�#34!�#ONNECTION�IDENTIFIERSPECIFIED�AS�#ALL�4O�"E�!NSWERED�

./?#!,,?4/?#/-0,%4%4HERE�IS�NO�CALL�ACTIVE�FOR�THE�#34!�#ONNECTION�IDENTIFIERSPECIFIED�AS�#ALL�4O�"E�#OMPLETED�


System resource availability errors

%RROR�VALUES�IN�THIS�CATEGORY�INDICATE�THAT�THE�3ERVICE�2EQUEST�CANNOTBE�COMPLETED�BECAUSE�OF�A�LACK�OF�SYSTEM�RESOURCES�WITHIN�THESERVING�SUB DOMAIN��4HIS�TYPE�INCLUDES�ONE�OF�THE�FOLLOWING�SPECIFICERROR�VALUES�

'%.%2)#?3934%-?2%3/52#%?!6!),!"),)494HE�SERVER�IS�UNABLE�TO�BE�ANY�MORE�SPECIFIC�

3%26)#%?"5394HE�3ERVICE�IS�SUPPORTED�BY�THE�SERVER��BUT�IS�TEMPORARILYUNAVAILABLE�

2%3/52#%?"539!N�INTERNAL�RESOURCE�IS�BUSY��4HERE�IS�HIGH�PROBABILITY�THATTHE�3ERVICE�WILL�SUCCEED�IF�RETRIED�

2%3/52#%?/54?/&?3%26)#%4HE�3ERVICE�REQUIRES�A�RESOURCE�THAT�IS�/UT�/F�3ERVICE��!3ERVICE�2EQUEST�THAT�ENCOUNTERS�THIS�CONDITION�COULD�INITIATESYSTEM�PROBLEM�DETERMINATION�ACTIONS��E�G��NOTIFICATION�OFTHE�NETWORK�ADMINISTRATOR�

.%47/2+?"5394HE�SERVER�SUB DOMAIN�IS�BUSY�

.%47/2+?/54?/&?3%26)#%4HE�SERVER�SUB DOMAIN�IS�/UT�/F�3ERVICE�

/6%2!,,?-/.)4/2?,)-)4?%8#%%$%$4HIS�REQUEST�WOULD�EXCEED�THE�SERVER�S�OVERALL�LIMIT�OFMONITORS�

#/.&%2%.#%?-%-"%2?,)-)4?%8#%%$%$�4HIS�REQUEST�WOULD�EXCEED�THE�SERVER�S�LIMIT�ON�THE�NUMBEROF�MEMBERS�OF�A�CONFERENCE�

Subscribed resource availability errors

%RROR�VALUES�IN�THIS�CATEGORY�INDICATE�THAT�THE�3ERVICE�2EQUEST�CANNOTBE�COMPLETED�BECAUSE�A�REQUIRED�RESOURCE�MUST�BE�PURCHASED�ORCONTRACTED�BY�THE�CLIENT�SYSTEM��4HIS�TYPE�INCLUDES�THE�FOLLOWINGSPECIFIC�ERROR�VALUES�


'%.%2)#?35"3#2)"%$?2%3/52#%?!6!),!"),)494HE�SERVER�IS�UNABLE�TO�BE�ANY�MORE�SPECIFIC�

/"*%#4?-/.)4/2?,)-)4?%8#%%$%$4HIS�REQUEST�WOULD�EXCEED�THE�SERVER�S�LIMIT�OF�MONITORS�FORTHE�SPECIFIED�OBJECT�

%84%2.!,?425.+?,)-)4?%8#%%$%$4HE�LIMIT�OF�EXTERNAL�TRUNKS�WOULD�BE�EXCEEDED�BY�THISREQUEST�

/5434!.$).'?2%15%34?,)-)4?%8#%%$%$4HE�LIMIT�OF�OUTSTANDING�REQUESTS�WOULD�BE�EXCEEDED�BY�THISREQUEST�

Performance management errors

%RROR�VALUES�IN�THIS�CATEGORY�INDICATE�THAT�AN�ERROR�HAS�BEEN�RETURNEDAS�A�PERFORMANCE�MANAGEMENT�MECHANISM��4HIS�TYPE�INCLUDES�THEFOLLOWING�SPECIFIC�ERROR�VALUES�

'%.%2)#?0%2&/2-!.#%?-!.!'%-%.44HE�SERVER�IS�UNABLE�TO�BE�ANY�MORE�SPECIFIC�

0%2&/2-!.#%?,)-)4?%8#%%$%$!�PERFORMANCE�LIMIT�IS�EXCEEDED�

Security errors

%RROR�VALUES�IN�THIS�CATEGORY�INDICATE�THAT�THERE�IS�A�SECURITY�ERROR�4HIS�TYPE�INCLUDES�THE�FOLLOWING�SPECIFIC�ERROR�VALUES�

5.30%#)&)%$?3%#52)49?%22/24HE�SERVER�IS�UNABLE�TO�BE�ANY�MORE�SPECIFIC�

3%15%.#%?.5-"%2?6)/,!4%$4HIS�ERROR�INDICATES�THAT�THE�SERVER�HAS�DETECTED�AN�ERROR�INTHE�3EQUENCE�.UMBER�OF�THE�OPERATION�

4)-%?34!-0?6)/,!4%$4HIS�ERROR�INDICATES�THAT�THE�SERVER�HAS�DETECTED�AN�ERROR�INTHE�4IME�3TAMP�OF�THE�OPERATION�


0!#?6)/,!4%$4HIS�ERROR�INDICATES�THAT�THE�SERVER�HAS�DETECTED�AN�ERROR�INTHE�0!#�OF�THE�OPERATION�

3%!,?6)/,!4%$4HIS�ERROR�INDICATES�THAT�THE�SERVER�HAS�DETECTED�AN�ERROR�INTHE�3EAL�OF�THE�OPERATION�

CSTA Driver Interface Errors

4HESE�ERRORS�DERIVE�FROM�THE�2EMOTE�/PERATIONS�##)443PECIFICATION�8��AND�MAY�OCCUR�WHEN�A�0"8�$RIVER�USES�THE#34!�INTERFACE�TO�THE�4ELEPHONY�3ERVICES�

5.2%#/'.):%$?!0$5?2%*%#4)/.4HE�GIVEN�TYPE�OF�THE�!0$5�IS�NOT�DEFINED�IN�THE�PROTOCOL�

-)3490%$?!0$5?2%*%#4)/.4HE�STRUCTURE�OF�THE�!0$5�DOES�NOT�CONFORM�TO�THEPROTOCOL�

"!$,9�3425#452%$?!0$5?2%*%#4)/.!0$5�DOES�NOT�CONFORM�TO�8��OR�8��STANDARDENCODING�

).)4)!4/2�2%,%!3).'?2%*%#4)/.4HE�REQUESTER�IS�NOT�WILLING�TO�DO�THE�INVOKED�OPERATIONBECAUSE�IT�IS�ABOUT�TO�RELEASE�THE�STREAM�

5.2%#/'.):%$?,).+%$)$?2%*%#4)/.4HERE�IS�NO�OPERATION�IN�PROGRESS�WITH�AN�INVOKE�)$�EQUAL�TOTHE�SPECIFIED�LINK�)$�

,).+%$?2%30/.3%?5.%80%#4%$?2%*%#4)/.4HE�INVOKED�OPERATION�THAT�THE�LINKED�)$�REFERS�TO�IS�NOT�APARENT�OPERATION�

5.%80%#4%$?#(),$?/0%2!4)/.?2%*%#4)/.4HE�LINKED�)$�REFERS�TO�A�PARENT�OPERATION�THAT�DOES�NOTALLOW�THE�INVOKED�OPERATION�


-)3490%$?2%35,4?2%*%#4)/.4HE�TYPE�OF�THE�2ESULT�PARAMETER�DOES�NOT�CONFORM�TO�THEPROTOCOL�

5.2%#/'.):%$?%22/2?2%*%#4)/.4HE�REPORTED�ERROR�IS�NOT�IN�THE�PROTOCOL�DEFINITION�

5.%80%#4%$?%22/2?2%*%#4)/.4HE�REPORTED�ERROR�IS�NOT�ONE�THAT�THE�OPERATION�MAY�REPORT�

-)3490%$?!2'5-%.4?2%*%#4)/.

-)3490%$?0!2!-%4%2?2%*%#4)/.4HE�TYPE�OF�A�SUPPLIED�ERROR�PARAMETER�IS�NOT�CONSISTENT�WITHTHE�PROTOCOL�SPECIFICATION

TSAPI

4HE�ERROR�CODES�BELOW�CAN�OCCUR�WITHIN�THE�43!0)�IMPLEMENTATIONOF�THE�%#-!�#34!�STANDARDS��4HE�%#-!�STANDARDS�DO�NOT�DEFINETHESE�ERRORS�

2%3/52#%?,)-)4!4)/.?2%*%#4)/.!�4ELEPHONY�3ERVER�OR�0"8�$RIVER�RESOURCE�LIMITATIONPREVENTS�THE�SYSTEM�FROM�PROCESSING�THE�APPLICATION�REQUEST

!#3?(!.$,%?4%2-).!4)/.?2%*%#4)/.

3%26)#%?4%2-).!4)/.?2%*%#4)/.

2%15%34?4)-%/54?2%*%#4)/.

2%15%343?/.?$%6)#%?%8#%%$%$?2%*%#4)/.

Private Data

)F�PRIVATE�DATA�ACCOMPANIED�THIS�EVENT��THEN�THE�PRIVATE�DATA�WOULD�BECOPIED�TO�THE�LOCATION�POINTED�TO�BY�THE�PRIVATE$ATA�POINTER�IN�THEACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��FUNCTION��)F�THEPRIVATE$ATA�POINTER�IS�SET�TO�.5,,�IN�THESE�FUNCTIONS��THEN�NO�PRIVATEDATA�WILL�BE�DELIVERED�TO�THE�APPLICATION�


CSTA!LTERNATE#ALL��

4HE�!LTERNATE�#ALL�3ERVICE�PROVIDES�A�HIGHER LEVEL��COMPOUND�ACTIONOF�THE�(OLD�#ALL�3ERVICE�FOLLOWED�BY�2ETRIEVE�#ALL�3ERVICE��4HISFUNCTION�WILL�PLACE�AN�EXISTING�ACTIVE�CALL�ON�HOLD�AND�THEN�EITHERRETRIEVES�A�PREVIOUSLY�HELD�CALL�OR�CONNECTS�AN�ALERTING�CALL�AT�THESAME�DEVICE�

Syntax


2ET#ODE?T��CSTA!LTERNATE#ALL�!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T ACTIVE#ALL�#ONNECTION)$?T OTHER#ALL�0RIVATE$ATA?T PRIVATE$ATA�

Parameters

acsHandle4HIS�IS�THE�VALUE�OF�THE�UNIQUE�HANDLE�TO�THE�OPENED�!#3�3TREAM�


activeCall4HIS�PARAMETER�POINTS�TO�THE�CONNECTION�IDENTIFIER�FOR�THE�#ONNECTED��OR�ACTIVE�CALL�WHICH�IS�TO�BE�ALTERNATED�

otherCall4HIS�PARAMETER�POINTS�TO�THE�CONNECTION�IDENTIFIER�FOR�THE��!LERTING�OR��(ELD��CALL�WHICH�IS�TO�BE�ALTERNATED�


privateData4HIS�IS�A�POINTER�TO�THE�PRIVATE�DATA�EXTENSION�MECHANISM��3ETTINGTHIS�PARAMETER�IS�OPTIONAL��)F�THE�PARAMETER�IS�NOT�USED��THE�POINTERSHOULD�BE�SET�TO�.5,,�

Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!!LTERNATE#ALL#ONF%VENT � MESSAGE�TO�ENSURE�THAT�THESERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGED�AND� PROCESSED�BY�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�


!#3%22?"!$($,4HIS�RETURN�VALUE�INDICATES�THAT�A�BAD�OR�UNKNOWNACS(ANDLE�WAS�PROVIDED�BY�THE�APPLICATION�

!#3%22?342%!-?&!),%$4HIS�RETURN�VALUE�INDICATES�THAT�A�PREVIOUSLY�ACTIVE�!#33TREAM�HAS�BEEN�ABNORMALLY�ABORTED�

Comments

!�SUCCESSFUL�CALL�TO�THIS�FUNCTION�WILL�CAUSES�THE�HELD OR DELIVEREDCALL�TO�BE�SWAPPED�WITH�THE�ACTIVE�CALL


!S�SHOWN�IN�THE�FIGURE�BELOW��THE�!LTERNATE�#ALL�3ERVICE�PLACES�THEUSER�S�ACTIVE�CALL�TO�DEVICE�$��ON�HOLD�AND��IN�A�COMBINED�ACTION�ESTABLISHES�OR�RETRIEVES�THE�CALL�BETWEEN�DEVICE�$��AND�DEVICE�$��ASTHE�ACTIVE�CALL��$EVICE�$��CAN�BE�CONSIDERED�AS�BEING�AUTOMATICALLYPLACED�ON�HOLD�IMMEDIATELY�PRIOR�TO�THE�RETRIEVAL�ESTABLISHMENT�OF�THEHELD�ACTIVE�CALL�TO�DEVICE�$��

&IGURE�� SHOWS�THE�OPERATION�OF�THE�!LTERNATE�#ALL�3ERVICE�

Figure 5-1Alternate Call Service

D1 C1 D2

D3C2

D1 C1 D2

D3C2

c

c

h

h/a

*

* *

*

Before After


#34!!LTERNATE#ALL#ONF%VENT

The Alternate Call confirmation event provides the positive response from theserver for a previous alternate call request.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��!#3�$ATA�4YPES�AND�#34!�$ATA4YPES�IN�SECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!!LTERNATE#ALL#ONF%VENT?T ��ALTERNATE#ALL�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!!LTERNATE#ALL#ONF%VENT?T�[� .ULLTYPE��NULL�]�#34!!LTERNATE#ALL#ONF%VENT?T�

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�NEWLY�OPENED�!#3

3TREAM�



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?!,4%2.!4%?#!,,?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN#34!!LTERNATE#ALL#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�FUNCTION�SERVICE�REQUEST�INSTANCE�FOR�THESERVICE�WHICH�WAS�PROCESSED�AT�THE�4ELEPHONY�3ERVER�OR�AT�THESWITCH��4HIS�IDENTIFIER�IS�PROVIDED�TO�THE�APPLICATION�WHEN�A�SERVICEREQUEST�IS�MADE�

privateData)F�PRIVATE�DATA�ACCOMPANIED�THIS�EVENT��THEN�THE�PRIVATE�DATA�WOULD�BECOPIED�TO�THE�LOCATION�POINTED�TO�BY�THE�PRIVATE$ATA�POINTER�IN�THEACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��FUNCTION��)F�THEPRIVATE$ATA�POINTER�IS�SET�TO�.5,,�IN�THESE�FUNCTIONS��THEN�NO�PRIVATEDATA�WILL�BE�DELIVERED�TO�THE�APPLICATION�


CSTA!NSWER#ALL��

The Answer Call function will connect an alerting call at the device which isalerting. The call must be associated with a device that can answer a callwithout requiring physical user manipulation.

Syntax


2ET#ODE?T��CSTA!NSWER#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T ALERTING#ALL�0RIVATE$ATA?T PRIVATE$ATA�

Parameters

acsHandle4HIS�IS�THE�VALUE�OF�THE�UNIQUE�HANDLE�TO�THE�OPENED�!#3

3TREAM�


alertingCall4HIS�PARAMETER�POINTS�TO�THE�CONNECTION�IDENTIFIER�OF�THE�CALL�TO�BEANSWERED�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!!NSWER#ALL#ONF%VENT�MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�




Comments

4HE�!NSWER�#ALL�3ERVICE�WORKS�FOR�AN�INCOMING�CALL�THAT�IS�ALERTING�ADEVICE��)N�THE�FOLLOWING�FIGURE�THE�CALL�#��IS�DELIVERED�TO�DEVICE�$��4HE�CSTA!NSWER#ALL��IS�TYPICALLY�USED�WITH�TELEPHONES�THAT�HAVEATTACHED�SPEAKERPHONE�UNITS�TO�ESTABLISH�THE�CALL�IN�A�HANDS FREEOPERATION�


Figure 5-2Answer Call Service

D1 C1 D1 C1 D2D2 ca * *

Before After


#34!!NSWER#ALL#ONF%VENT

The Answer Call confirmation event provides the positive response from theserver for a previous answer call request.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND�#34!�$ATA�4YPESIN�SECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!!NSWER#ALL#ONF%VENT?T ANSWER#ALL�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!!NSWER#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!!NSWER#ALL#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?!.37%2?#!,,?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN�#34!!NSWER#ALL#ONF%VENT�




CSTA#ALL#OMPLETION��

The Call Completion Service invokes specific switch features that maycomplete a call that would otherwise fail. The feature to be activated is passedas a parameter to the function.

Syntax


2ET#ODE?T��CSTA#ALL#OMPLETION��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�&EATURE?T FEATURE�#ONNECTION)$?T CALL�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



feature3PECIFIES�THE�CALL�COMPLETION�FEATURE�THAT�IS�DESIRED��4HESE�INCLUDE�

#!-0?/.� �QUEUES�THE�CALL�UNTIL�THE�DEVICE�IS�AVAILABLE�

#!,,?"!#+� �REQUESTS�THE�CALLED�DEVICE�TO�RETURN�THE�CALL�WHEN�IT�RETURNSTO�IDLE�

).425$%� �ADDS�THE�CALLER�TO�AN�EXISTING�ACTIVE�CALL�AT�THE�CALLED� DEVICE�

4HIS�FEATURE�REQUIRES�THE�APPROPRIATE�USER�SECURITY�LEVEL�AT�THE�SERVER�

TYPEDEF�ENUM�&EATURE?T�[��&4?#!-0?/.��&4?#!,,?"!#+��&4?).425$%��]�&EATURE?T�


call4HIS�IS�A�POINTER�TO�A�CONNECTION�IDENTIFIER�FOR�THE�CALL�TO�BECOMPLETED�


Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!#ALL#OMPLETION#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THESERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGED�AND� PROCESSED�BY�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�





Comments

'ENERALLY�THIS�3ERVICE�IS�INVOKED�WHEN�A�CALL�IS�ESTABLISHED�AND�ITENCOUNTERS�A�BUSY�OR�NO�ANSWER�AT�THE�FAR�DEVICE�

4HE�#AMP�/N�FEATURE�ALLOWS�QUEUING�FOR�AVAILABILITY�OF�THE�FAR�ENDDEVICE��'ENERALLY��#AMP�/N�MAKES�THE�CALLER�WAIT�UNTIL�THE�CALLEDPARTY�FINISHES�THE�CURRENT�CALL�AND�ANY�PREVIOUSLY�CAMPED�ON�CALLS�#ALL�"ACK�ALLOWS�REQUESTING�THE�CALLED�DEVICE�TO�RETURN�THE�CALL�WHENIT�RETURNS�TO�IDLE��#ALL�"ACK�WORKS�MUCH�LIKE�#AMP�/N��BUT�THE�CALLERIS�ALLOWED�TO�HANG�UP�AFTER�INVOKING�THE�SERVICE��AND�THE�#34!3WITCHING�&UNCTION�CALLS�BOTH�PARTIES�WHEN�THE�CALLED�PARTY�BECOMESFREE��)NTRUDE�ALLOWS�THE�CALLER�TO�BE�ADDED�INTO�AN�EXISTING�CALL�AT�THECALLED�DEVICE�


#34!#ALL#OMPLETION#ONF%VENT

The Call Completion confirmation event provides the positive response fromthe server for a previous call completion request.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!#ALL#OMPLETION#ONF%VENT?T ��CALL#OMPLETION�]U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!#ALL#OMPLETION#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!#ALL#OMPLETION#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE#34!?#!,,?#/-0,%4)/.?#/.&��WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!#ALL#OMPLETION#ONF%VENT�




CSTA#LEAR#ALL��

The Clear Call Service releases all of the devices from the specified call, andeliminates the call itself. The call ceases to exist and the connectionidentifiers used for observation and manipulation are released.

Syntax


2ET#ODE?T��CSTA#LEAR#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T CALL�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



call4HIS�IS�A�POINTER�TO�THE�CONNECTION�IDENTIFIER�FOR�THE�CALL�TO�BE�CLEARED�


Return Values





4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!#LEAR#ALL#ONF%VENTMESSAGE�TO�ENSURE�THAT�THE�SERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGEDAND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THE�SWITCH�




Comments

4HIS�FUNCTION�WILL�CAUSE�EACH�DEVICE�ASSOCIATED�WITH�A�CALL�TO�BERELEASED�AND�THE�#34!�#ONNECTION�)DENTIFIERS��AND�THEIRCOMPONENTS�ARE�FREED�

&IGURE�� ILLUSTRATES�THE�RESULTS�OF�A�#LEAR�#ALL��#34!�#ONNECTION)$��#��$��WHERE�CALL�#��CONNECTS�DEVICES�$��$��AND�$��


Figure 5-3Clear Call Service

D2

D3

D1D2

D3

D1 C1* *

*

Before After


#34!#LEAR#ALL#ONF%VENT

The Clear Call confirmation event provides the positive response from theserver for a previous clear call request.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��!#3�$ATA�4YPES�AND�#34!�$ATA4YPES��IN�SECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!#LEAR#ALL#ONF%VENT?TCLEAR#ALL�

]U�]�CSTA#ONFIRMATION�

]�EVENT�]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!#LEAR#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!#LEAR#ALL#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?#,%!2?#!,,?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!#LEAR#ALL#ONF%VENT�



Comments

4HIS�CONFIRMATION�INDICATES�THAT�ALL�INSTANCES�OF�THE�!#3��#ONNECTION)DENTIFIERS�FOR�ALL�THE�ENDPOINTS�IN�THE�CALL�AND�IN�THE�CURRENTASSOCIATION�HAVE�BECOME�INVALID��4HE�INSTANCES�OF�IDENTIFIERS�SHOULDNOT�BE�USED�TO�REQUEST�ADDITIONAL�SERVICES�OF�THE�4ELEPHONY�3ERVER�


CSTA#LEAR#ONNECTION��

The Clear Connection Service releases the specified device from thedesignated call. The Connection is left in the Null state. Additionally, theCSTA Connection Identifier provided in the Service Request is released.

Syntax


2ET#ODE?T��CSTA#LEAR#ONNECTION��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T CALL�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



call4HIS�IS�A�POINTER�TO�THE�CONNECTION�IDENTIFIER�FOR�THE�CONNECTION�TO�BECLEARED�




Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!#LEAR#ONNECTION#ONF%VENT�MESSAGE�TO�ENSURE�THAT�THESERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGED�AND��PROCESSED�BY�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�




Comments

4HIS�3ERVICE�RELEASES�THE�SPECIFIED�#ONNECTION�AND�#34!#ONNECTION�)DENTIFIER�INSTANCE�FROM�THE�DESIGNATED�CALL��4HE�RESULT�ISAS�IF�THE�DEVICE�HAD�HUNG�UP�ON�THE�CALL��)T�IS�INTERESTING�TO�NOTE�THATTHE�PHONE�MAY�NOT�BE�PHYSICALLY�RETURNED�TO�THE�SWITCH�HOOK��WHICHMAY�RESULT�IN�SILENCE��DIAL�TONE��OR�SOME�OTHER�CONDITION��'ENERALLY��IFONLY�TWO�#ONNECTIONS�ARE�IN�THE�CALL��THE�EFFECT�OFCSTA#LEAR#ONNECTION ��FUNCTION�IS�THE�SAME�AS�CSTA#LEAR#ALL��


&IGURE�� IS�AN�EXAMPLE�OF�THE�RESULTS�OF�A�#LEAR�#ONNECTION��#34!#ONNECTION�)D��#��$��WHERE�CALL�#��CONNECTS�DEVICES�$��$��AND$��.OTE�THAT�IT�IS�LIKELY�THAT�THE�CALL�IS�NOT�CLEARED�BY�THIS�3ERVICE�IFIT�IS�SOME�TYPE�OF�CONFERENCE�

Figure 5-4Clear Connection Service

D2

D3

D1D2

D3

D1 C1 C1* *

*

* *

Before After


#34!#LEAR#ONNECTION#ONF%VENT

The Clear Connection confirmation event provides the positive response fromthe server for a previous clear connection request.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


��#34!#LEAR#ONNECTION#ONF%VENT?T��CLEAR#ONNECTION�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!#LEAR#ONNECTION#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!#LEAR#ONNECTION#ONF%VENT?T�

Parameters




eventType4HIS�TAG�WITH�THE�VALUE�#34!?#,%!2?#/..%#4)/.?#/.&IDENTIFIES�THIS�MESSAGE�AS�AN�#34!#LEAR#ONNECTION#ONF%VENT�



Comments

4HIS�CONFIRMATION�EVENT�INDICATES�THAT�THE�INSTANCE�OF�THE�!#3#ONNECTION�)DENTIFIER�FOR�THE�CLEARED�#ONNECTION�IS�RELEASED��4HEIDENTIFIER�SHOULD�NOT�BE�USED�TO�REQUEST�ADDITIONAL�SERVICES�OF�THE4ELEPHONY�3ERVER�


CSTA#ONFERENCE#ALL��

This function provides the conference of an existing held call and anotheractive call at a device. The two calls are merged into a single call and the twoConnections at the conferencing device resolve into a single Connection in theConnected state. The pre-existing CSTA Connection Identifiers associatedwith the device creating the conference are released, and a new CSTAConnection Identifier for the resulting conferenced Connection is provided.

Syntax


2ET#ODE?T��CSTA#ONFERENCE#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T HELD#ALL�#ONNECTION)$?T ACTIVE#ALL�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



heldCall4HIS�IS�A�POINTER�TO�THE�CONNECTION�IDENTIFIER�FOR�THE�CALL�WHICH�IS�ONHOLD�AND�IS�TO�BE�CONFERENCED�WITH�AN�ACTIVE�CALL�

activeCall4HIS�IS�A�POINTER�TO�THE�CONNECTION�IDENTIFIER�FOR�THE�CALL�WHICH�ISACTIVE�OR�PROCEEDING�AND�IS�TO�BE�CONFERENCED�WITH�THE�HELD�CALL�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!#ONFERENCE#ALL#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH� 4HE�FOLLOWING�ARE�POSSIBLE�NEGATIVE�ERRORCONDITIONS�FOR�THIS�FUNCTION�



Comments

&IGURE�� IS�AN�EXAMPLE�OF�THE�STARTING�CONDITIONS�FOR�THECSTA#ONFERENCE#ALL��FUNCTION��WHICH�ARE��THE�CALL�#��FROM�$�TO�$��IS�IN�THE�HELD�STATE��!�CALL�#��FROM�$��TO�$��IS�IN�PROGRESS�ORACTIVE�


Figure 5-5Conference Call Service

D1 C1 D2

D3C2

D1 D2

D3c c

h

C3

* *

**

Before After

$��$��AND�$��ARE�CONFERENCED�OR�JOINED�TOGETHER�INTO�A�SINGLE�CALL�#��4HE�VALUE�OF�THE�#ONNECTION��IDENTIFIER��$��#��MAY�BE�THAT�OFONE�OF�THE�#34!�#ONNECTION�)DENTIFIERS�PROVIDED�IN�THE�REQUEST�$��#��OR�$��#��


#34!#ONFERENCE#ALL#ONF%VENT

The Conference Call confirmation event provides the positive response fromthe server for a previous conference call request.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND��#34!�$ATA4YPES�IN�SECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!#ONFERENCE#ALL#ONF%VENT?T��CONFERENCE#ALL�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#ONNECTION?T�[��#ONNECTION)$?T��PARTY��3UBJECT$EVICE)$?T��STATIC$EVICE�]�#ONNECTION?T�

TYPEDEF�STRUCT�#ONNECTION,IST�[��INT��COUNT��#ONNECTION?T��CONNECTION�]�#ONNECTION,IST?T�

TYPEDEF�STRUCT�#34!#ONFERENCE#ALL#ONF%VENT?T�[��#ONNECTION)$?T��NEW#ALL��#ONNECTION,IST?T��CONN,IST�]�#34!#ONFERENCE#ALL#ONF%VENT?T�


Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�#34!�CONFIRMATION�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE#34!?#/.&%2%.#%?#!,,?#/.&��WHICH�IDENTIFIES�THISMESSAGE�AS�AN�#34!#ONFERENCE#ALL#ONF%VENT�


newCall4HIS�PARAMETER�SPECIFIES�THE�RESULTING�CONNECTION�IDENTIFIER�FOR�THECALLS�WHICH�WERE�CONFERENCED�AT�THE�#ONFERENCING�DEVICE��4HISCONNECTION�IDENTIFIER�REPLACES�THE�TWO�PREVIOUS�CONNECTION�IDENTIFIERAT�THAT�DEVICE�

connList3PECIFIES�THE�RESULTING�NUMBER�OF�KNOWN�DEVICES�IN�THE�CONFERENCE�4HIS�FIELD�CONTAINS�A�COUNT��COUNT�OF�THE�NUMBER�OF�DEVICES�IN�THECONFERENCE�AND�A�POINTER��CONNECTION�TO�AN�ARRAY�OF�#ONNECTION?TSTRUCTURES�WHICH�DEFINE�EACH�CONNECTION�IN�THE�CALL�

%ACH�#ONNECTION?T�RECORD�CONTAINS�THE�FOLLOWING�

0ARTY� �INDICATES�THE�#ONNECTION�)$�OF�THE�PARTY�IN�THECONFERENCE�

$EVICE� �PROVIDES�THE�STATIC�REFERENCE�FOR�THE�PARTY�IN�THECONFERENCE��4HIS�PARAMETER�MAY�HAVE�A�VALUE�THAT�INDICATESTHE�STATIC�IDENTIFIER�IS�NOT�KNOWN�




CSTA#ONSULTATION#ALL��

The cstaConsultationCall( ) function will provide the compound or combinedaction of the Hold Call service followed by Make Call service. This serviceplaces an existing active call at a device on hold and initiates a new call fromthe same device using a single function call.

Syntax


2ET#ODE?T��CSTA#ONSULTATION#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T ACTIVE#ALL�$EVICE)$?T CALLED$EVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



activeCall4HIS�IS�A�POINTER�TO�THE�CONNECTION�IDENTIFIER�FOR�THE�ACTIVE�CALL�WHICHIS�TO�BE�PLACED�ON�HOLD�BEFORE�THE�NEW�CALL�IS�ESTABLISHED�

calledDevice4HIS�IS�A�POINTER�TO�THE�DESTINATION�DEVICE�ADDRESS�FOR�THE�NEW�CALL�TOBE�ESTABLISHED�



Return Values


,IBRARY GENERATED�)DENTIFIERS� �IF�THE�FUNCTION�CALL�COMPLETESSUCCESSFULLY�IT�WILL�RETURN�A�POSITIVE�VALUE��I�E��THE�INVOKEIDENTIFIER��)F�THE�CALL�FAILS�A�NEGATIVE�ERROR��CONDITIONWILL�BE�RETURNED��&OR�LIBRARY GENERATED�IDENTIFIERS�THE�RETURNWILL�NEVER�BE�ZERO��


4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!#ONSULTATION#ALL#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THESERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�




#OMMENTS4HIS�COMPOUND�SERVICE�ALLOWS�THE�APPLICATION�TO�PLACE�AN�EXISTINGCALL�ON�HOLD�AND�AT�THE�SAME�TIME�ESTABLISH�A�NEW�CALL�TO�ANOTHERDEVICE��)N�THIS�CASE�AN�ACTIVE�CALL�#��EXISTS�AT�$��SEE�&IGURE��AND�A�CONSULTATIVE�CALL�IS�DESIRED�TO�$��!FTER�THIS�FUNCTION�IS�CALLED�THE�ORIGINAL�ACTIVE�CALL��#��IS�PLACED�ON�HOLD�AND�A�NEW�CALL��#��ISPLACED�TO�DEVICE�$��


Figure 5-6Consultation Call Service

D1 C1 D1 C1D2 D2

D3C2

c h

c

* *

Before After


#34!#ONSULTATION#ALL#ONF%VENT

The Consultation Call confirmation event provides the positive response fromthe server for a previous consultation call request.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!#ONSULTATION#ALL#ONF%VENT?T�CONSULTATION#ALL�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!#ONSULTATION#ALL#ONF%VENT?T�[�� #ONNECTION)$?T��NEW#ALL�

]�#34!#ONSULTATION#ALL#ONF%VENT?T�

Parameters




eventType4HIS�TAG�WITH�THE�VALUE�#34!?#/.35,4!4)/.?#!,,?#/.&�IDENTIFIES�THIS�MESSAGE�AS�AN�#34!#ONSULTATION#ALL#ONF%VENT�


newCall3PECIFIES�THE�#ONNECTION�)$�FOR�THE�ORIGINATING�CONNECTION�OF�THE�NEWCALL�ORIGINATED�BY�THE�#ONSULTATION�#ALL�REQUEST�



CSTA$EFLECT#ALL��

The cstaDeflectCall( ) service takes an alerting call at a device and redirectsthe call to a given number.

Syntax


2ET#ODE?T��CSTA$EFLECT#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T DEFLECT#ALL�$EVICE)$?T CALLED$EVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



deflectCall4HIS�IS�A�POINTER�TO�THE�CONNECTION�IDENTIFIER�OF�THE�CALL�WHICH�IS�TO�BEDEFLECTED�TO�ANOTHER�DEVICE�WITHIN�THE�SWITCH�

calledDevice!�POINTER�TO�THE�DEVICE�IDENTIFIER�WHERE�THE�ORIGINAL�CALL�IS�TO�BEDEFLECTED�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!$EFLECT#ALL#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�




Comments

4HE�$EFLECT�#ALL�3ERVICE�TAKES�A�RINGING��ALERTING�CALL�AT�ADEVICE��$��AND�SENDS�IT�TO�A�NEW�DESTINATION��$��4HIS�FUNCTIONREPLACES�THE�ORIGINAL�CALLED�DEVICE��AS�SPECIFIED�IN�THE�DEFLECT#ALLPARAMETER��WITH�A�DIFFERENT�DEVICE�WITHIN�THE�SWITCH��AS�SPECIFIED�INTHE�CALLED$EVICE�PARAMETER�


Figure 5-7Deflect Call Service

D1 C1 D2 D1 C1 D2

D3 D3

* *

*

?

Before After


#34!$EFLECT#ALL#ONF%VENT

The Deflect Call confirmation event provides the positive response from theserver for a previous deflect call request.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!$EFLECT#ALL#ONF%VENT?T��DEFLECT#ALL�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!$EFLECT#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!$EFLECT#ALL#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?$%&,%#4?#!,,?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN�#34!$EFLECT#ALL#ONF%VENT�




CSTA'ROUP0ICKUP#ALL��

The cstaGroupPickupCall( ) service moves an alerting call (at one or moredevices in a device pickup group) to a specified device.

'ROUP�0ICKUP�IS�A�0"8�FEATURE�WHERE�A� 0ICKUP�'ROUP �IS�DEFINED�ON�THE0"8��INDEPENDENT�OF�4ELEPHONY�3ERVICE�$EVICE�'ROUPS��7HEN�A�CALL�RINGSAT�A�STATION�IN�THE�PICKUP�GROUP��A�PICKUP�GROUP�MEMBER�MAY�INVOKE�THE0"8 S� 'ROUP�0ICKUP �FEATURE�AND�THEREBY�REDIRECT�THE�RINGING�CALL�TO�THEIRPHONE��4HE�APPLICATION�DOES�NOT�SPECIFY�THE�CALL�THAT�IS�TO�BE�REDIRECTED�

Syntax


2ET#ODE?T��CSTA'ROUP0ICKUP#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T DEFLECT#ALL� ��6ERSION��3TREAM�/NLY�$EVICE)$?T PICKUP$EVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



deflectCall43!0)�6ERSION��3TREAM��0OINTER�TO�THE�CALL��BEING�PICKED�UP�

43!0)�6ERSION��3TREAM��4HIS�PARAMETER�IS�IGNORED�

pickupDevice4HIS�IS�A�POINTER�TO�THE�DEVICE�WHICH�IS�PICKING�UP�CALLS�FROM�THEGROUP�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!'ROUP0ICKUP#ONF%VENT�MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH��4HE�FOLLOWING�ARE�POSSIBLE�NEGATIVE�ERRORCONDITIONS�FOR�THIS�FUNCTION�



Comments

4HE�CSTA'ROUP0ICKUP#ALL��SERVICE�REDIRECTS�AN�ALERTING�CALL��AT�ONEOF�MORE�DEVICES�IN�A�DEVICE�PICKUP�TO�A�SPECIFIED�DEVICE��THEPICKUP$EVICE�


Figure 5-8Group Pickup Call Service

D1 C1 D2 D1 C1 D2

D3 D3

* *

*

?

Before After


#34!'ROUP0ICKUP#ALL#ONF%VENT

The Group Pickup Call confirmation event provides the positive responsefrom the server for a previous Group Pickup call request.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!'ROUP0ICKUP#ALL#ONF%VENT?T��GROUP0ICKUP#ALL�]U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!'ROUP0ICKUP#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!'ROUP0ICKUP#ALL#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?'2/50?0)#+50?#!,,? #/.&��WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN�#34!'ROUP0ICKUP #ALL#ONF%VENT�




CSTA(OLD#ALL��

The cstaHoldCall( ) service places an existing Connection in the held state.

Syntax


2ET#ODE?T CSTA(OLD#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T ACTIVE#ALL�"OOLEAN RESERVATION�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



activeCall!�POINTER�TO�THE�CONNECTION�IDENTIFIER�FOR�THE�ACTIVE�CALL�TO�BE�PLACEDON�HOLD�

reservation2ESERVES�THE�FACILITY�FOR�REUSE�BY�THE�HELD�CALL��4HIS�OPTION�IS�NOTAPPROPRIATE�FOR�MOST�NON )3$.�TELEPHONES��4HE�DEFAULT�IS�NOCONNECTION�RESERVATION�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!(OLD#ALL#ONF%VENTMESSAGE�TO�ENSURE�THAT�THE�SERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGEDAND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THE�SWITCH�




Comments

!�CALL�TO�THIS�FUNCTION�WILL�INTERRUPT�COMMUNICATIONS�FOR�AN�EXISTINGCALL�AT�A�DEVICE��4HE�CALL�IS�USUALLY��BUT�NOT�ALWAYS��IN�THE�ACTIVESTATE��!�CALL�MAY�BE�PLACED�ON�HOLD�BY�THE�USER�SOME�TIME�AFTERCOMPLETION�OF�DIALING��4HE�ASSOCIATED�CONNECTION�FOR�THE�HELD�CALL�ISMADE�AVAILABLE�FOR�OTHER�USES��DEPENDING�ON�THE�RESERVATION�OPTION�)3$. CASE��!S�SHOWN�IN�&IGURE�� IF�THE�(OLD�#ALL�SERVICE�ISINVOKED�FOR�DEVICE�$��ON�CALL�#��THEN�CALL�#��IS�PLACED�ON�HOLD�ATDEVICE�$��4HE�HOLD�RELATIONSHIP�IS�AFFECTED�AT�THE�HOLDING�DEVICE�


Figure 5-9Hold Call Service

D1 C1 D1 C1 D2D2 hc * *

Before After

4HE�CSTA(OLD#ALL��SERVICE�MAINTAINS�A�RELATIONSHIP�BETWEEN�THEHOLDING�DEVICE�AND�THE�HELD�CALL�THAT�LASTS�UNTIL�THE�CALL�IS�RETRIEVEDFROM�THE�HOLD�STATUS��OR�UNTIL�THE�CALL�IS�CLEARED�


#34!(OLD#ALL#ONF%VENT

The Hold Call confirmation event provides the positive response from theserver for a previous Hold call request

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND�#34!�$ATA4YPES�IN�3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!(OLD#ALL#ONF%VENT?T��HOLD#ALL�]U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!(OLD#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!(OLD#ALL#ONF%VENT?T�

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�!#3�3TREAM



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?(/,$?#!,,?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!(OLD#ALL#ONF%VENT�




CSTA-AKE#ALL��

The cstaMakeCall( ) service originates a call between two devices. Theoriginator must be on the switch. The service attempts to create a new call andestablish a connection between the calling device (originator) and the calleddevice (destination). The Make Call service also provides a CSTA ConnectionIdentifier that indicates the Connection of the originating device.

Syntax


2ET#ODE?T��CSTA-AKE#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T CALLING$EVICE�$EVICE)$?T CALLED$EVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



callingDevice!�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�WHICH�IS�TO�ORIGINATETHE�NEW�CALL�

calledDevice!�POINTER�TO�THE�DEVICE�IDENTIFIER�FOR�THE�DESTINATION�DEVICE�FOR�THENEW�CALL�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!-AKE#ALL#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�





Comments

4HE�CSTA-AKE#ALL��SERVICE�ORIGINATES�A�CALL�BETWEEN�TWOAPPLICATION�DESIGNATED�DEVICES��7HEN�THE�SERVICE�IS�INITIATED��THECALLING�DEVICE�IS�PROMPTED��IF�NECESSARY��AND��WHEN�THAT�DEVICEACKNOWLEDGES��A�CALL�TO�THE�CALLED�DEVICE�IS�ORIGINATED��&IGURE�� ILLUSTRATES�THE�RESULTS�OF�A�-AKE�#ALL�SERVICE�REQUEST��#ALLING�DEVICE��$��#ALLED�DEVICE��$��!�CALL�IS�ESTABLISHED�AS�IF�$��HAD�CALLED�$��AND�THE�CLIENT�IS�RETURNED�THE�#ONNECTION�ID��#��$��

Figure 5-11Make Call Service

D1 D2C1D1 D2 c

Before After

4HE�ESTABLISHMENT�OF�A�COMPLETE�CALL�CONNECTION�CAN�BE�A�MULTI STEPPED�PROCESS�DEPENDING�ON�THE�DESTINATION�OF�THE�CALL��#ALL�STATUSEVENT�REPORTS��SEE�3TATUS�2EPORTING�3ERVICE�MAY�BE�SENT�BY�THE4ELEPHONY�3ERVER�TO�THE�SERVICE�REQUESTING�CLIENT�APPLICATION�AS�THECONNECTION�ESTABLISHMENT�PROGRESSES��4HESE�EVENTS�ARE�IN�ADDITION�TOTHE�STANDARD�CONFIRMATION�EVENTS��E�G��#34!-AKE#ALL#ONF%VENTWHICH�ONLY�INDICATES�THAT�THE�SWITCH�IS�ATTEMPTING�TO�ESTABLISH�ACONNECTION�BETWEEN�THE�TWO�DEVICES��4HE�APPLICATION�SHOULD�BE�AWARETHAT�THE�REQUESTED�CALL�IS�NOT�GUARANTEED�TO�SUCCEED�EVEN�AFTER�ASUCCESSFUL�-AKE�#ALL�SERVICE�CONFIRMATION�EVENT�HAS�BEEN�RECEIVED�4HE�APPLICATION�MUST�MONITOR�STATUS�EVENTS�TO�BE�INFORMED�OF�THE�CALLSTATUS�AS�IT�PROGRESSES��3TATUS�EVENT�REPORTS�CAN�BE�ESTABLISHED�BYUSING�THE�CSTA-ONITOR3TART ��SERVICE��SEE�3TATUS�2EPORTING3ERVICES�


#34!-AKE#ALL#ONF%VENT

The Make Call confirmation event provides the positive response from theserver for a previous Make Call service request.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��!#3�$ATA�4YPES�AND��#34!�$ATA4YPES�IN�3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!-AKE#ALL#ONF%VENT?T MAKE#ALL�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T NEW#ALL�]�#34!-AKE#ALL#ONF%VENT?T�

Parameters


eventClass4HIS� IS� A� TAG� WITH� THE� VALUE� #34!#/.&)2-!4)/.�� WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!�CONFIRMATION�EVENT�


eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?-!+%?#!,,?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!-AKE#ALL#ONF%VENT�


newCall3PECIFIES�THE�#ONNECTION�)$�FOR�THE�ORIGINATING�CONNECTION�OF�THE�NEWCALL�ORIGINATED�BY�THE�-AKE�#ALL�REQUEST�



CSTA-AKE0REDICTIVE#ALL��

The cstaMakePredictiveCall( ) service originates a call between a group ofdevices or a logical device on behalf of an originating (calling) device. Theservice creates a new call and establishes a Connection with the terminating(called) device. The Make Predictive Call service also provides a CSTAConnection Identifier that indicates the Connection of the terminating (called)device.

Syntax


2ET#ODE?T��CSTA-AKE0REDICTIVE#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T CALLING$EVICE�$EVICE)$?T CALLED$EVICE�!LLOCATION3TATE?T ALLOCATION3TATE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



callingDevice!�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�WHICH�IS�TO�ORIGINATETHE�NEW�CALL�

calledDevice!�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�BEING�CALL��I�E��THEDESTINATION�DEVICE�


allocationState4HIS�PARAMETER�SPECIFIES�UNDER�WHICH�CONDITION�THE�CONNECTION�WITHTHE�DESTINATION�IS�TO�BE�CONNECTED�TO�THE�CALLING�OR�ORIGINATING�DEVICE�)F�THIS�PARAMETER�IS�NOT�SPECIFIED�BY�THE�APPLICATION��THE�#ALL$ELIVERED�STATE�WILL�BE�THE�DEFAULT��4HIS�PARAMETER�MAY�BE�ONE�OF�THEFOLLOWING�VALUES�

#ALL�$ELIVERED��THIS�VALUE�SPECIFIES�THAT�THE�SWITCH�SHOULDATTEMPT�TO�CONNECT�THE�CALL�TO�THE�CALLER��ORIGINATING�DEVICE�IF�THE�!LERTING�OR�#ONNECTED�STATE�IS�DETERMINED�AT�THE�CALLEDPARTY��DESTINATION�DEVICE�

#ALL�%STABLISHED��THIS�VALUE�SPECIFIES�THAT�THE�SWITCH�SHOULDATTEMPT�TO�CONNECT�THE�CALL�TO�THE�CALLER��ORIGINATING�DEVICE�IF�THE�#ONNECTED�STATE�IS�DETERMINED�AT�THE�CALLED�PARTY�DESTINATION�DEVICE�


Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!-AKE0REDICTIVE#ALL#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THESERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�





Comments

4HIS�SERVICE�IS�OFTEN�USED�TO�INITIATE�A�CALL�TO�A�CALLED�DEVICE�DESTINATION�FROM�A�GROUP�OF�DEVICES�OR�A�LOGICAL�DEVICE�WITHOUT�FIRSTESTABLISHING�A�CONNECTION�WITH�A�CALLING�DEVICE��ORIGINATOR��4HISSERVICE�ALLOCATES�THE�CALL�TO�A�PARTICULAR�DEVICE�WITHIN�THAT�GROUP�ATSOME�TIME�DURING�THE�PROGRESS�OF�THE�CALL�

4HE�CSTA-AKE0REDICTIVE#ALL��SERVICE�FIRST�INITIATES�A�CALL�TO�THECALLED�DEVICE��DESTINATION��$EPENDING�ON�THE�CALL�S�PROGRESS��THE�CALLMAY�BE�CONNECTED�WITH�THE�CALLING�DEVICE��ORIGINATOR�DURING�THEPROGRESS�OF�THE�CALL��4HE�POINT�AT�WHICH�THE�SWITCH�WILL�ATTEMPT�TOCONNECT�THE�CALL�TO�THE�ORIGINATING�DEVICE�IS�DETERMINED�BY�THEALLOCATION�3TATE�PARAMETER��)F�THE�ALLOCATION�PARAMETER�IS�SET�TO�#ALL$ELIVERED��THEN�THE�CALL�IS�ALLOCATED�UPON�DETECTION�OF�AN�!LERTING��OR#ONNECTED�#ONNECTION�STATE�AT�THE�DESTINATION��)F�THE�ALLOCATIONPARAMETER�IS�SET�TO�#ALL�%STABLISHED��THEN�THE�CALL�IS�ALLOCATED�UPONDETECTION�OF�A�#ONNECTED�#ONNECTION�STATE�AT�THE�RECIPIENT��)N�OTHERWORDS��THE�CALL�IS�CONNECTED�TO�THE�ORIGINATING�DEVICE�IF�THE�CALL�STATEIS�EITHER�ALERTING�OR�CONNECTED�AT�THE�FAR�END�OR�CONNECTED�RESPECTIVELY�

&IGURE�� ILLUSTRATES�THE�RESULTS�OF�A�-AKE�0REDICTIVE�#ALL��#ALLINGDEVICE��GROUP�DEVICE�$��#ALLED�DEVICE��$��

Figure 5-12Make Predictive Call Service

D1 D2C1D1 D2 a/c

Before After


#34!-AKE0REDICTIVE#ALL#ONF%VENT

The Make Predictive Call confirmation event provides the positive responsefrom the server for a previous cstaMakePredictiveCall( ) request.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��!#3�$ATA�4YPES�AND�#34!�$ATA4YPES�IN�3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!-AKE0REDICTIVE#ONF%VENT?TMAKE0REDICTIVE#ALL�

]�U�]�CSTA#ONFIRMATION�


TYPEDEF�STRUCT[

#ONNECTION)$?T NEW#ALL�]�#34!-AKE0REDICTIVE#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�-!+%?02%$)#4)6%?#!,,?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN#34!-AKE0REDICTIVE#ONF%VENT�


newCall3PECIFIES�THE�#ONNECTION�)$�FOR�THE�FAR END�CONNECTION�OF

THE�NEW�CALL�ORIGINATED�BY�THE�-AKE�0REDICTIVE�#ALL�REQUEST�



CSTA0ICKUP#ALL��

The cstaPickupCall( ) service takes a ringing (alerting) call at a device andredirects the call to a specified device.

Syntax


2ET#ODE?T��CSTA0ICKUP#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T DEFLECT#ALL�$EVICE)$?T CALLED$EVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



deflectCall4HIS�IS�A�POINTER�TO�THE�CONNECTION�IDENTIFIER�OF�THE�CALL�WHICH�IS�TO�BEPICKED�UP�FROM�ANOTHER�DEVICE�WITHIN�THE�SWITCH�

calledDevice!�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�WHICH�IS�PICKING�UPTHE�ORIGINAL�CALL�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!0ICKUP#ALL#ONF%VENT�MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�




Comments

4HE�CSTA0ICKUP#ALL��SERVICE�TAKES�AN�ALERTING�CALL�AT�A�DEVICEWITHIN�THE�SWITCH�AND�BRINGS�IT�TO�A�LOCAL�DEVICE�DESTINATION��4HISFUNCTION�PICKS�UP�A�CALL��DEFLECT#ALL��AT�THE�DEVICE�SPECIFIED�IN�THECALLED$EVICE�PARAMETER�


Figure 5-13Pickup Call Service

D1 C1 D2 D1 C1 D2

D3 D3

* *

*

?

Before After


#34!0ICKUP#ALL#ONF%VENT

The Pickup Call confirmation event provides the positive response from theserver for a previous pickup call request.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!0ICKUP#ALL#ONF%VENT?T��PICKUP#ALL�]U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!0ICKUP#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!0ICKUP#ALL#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?0)#+50?#!,,?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!0ICKUP#ALL#ONF%VENT�




CSTA2ECONNECT#ALL��

The cstaReconnectCall( ) service provides the compound action(combination) of the cstaClearConnection( ) service followed by thecstaRetrieveCall( ) service. The service clears an existing Connection andthen retrieves a previously Held Connection at the same device.

Syntax


2ET#ODE?T��CSTA2ECONNECT#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T ACTIVE#ALL�#ONNECTION)$?T HELD#ALL�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



activeCall!�POINTER�TO�THE�CONNECTION�IDENTIFIER�OF�THE�ACTIVE�CALL�WHICH�IS�TO�BECLEARED�

heldCall!�POINTER�TO�THE�CONNECTION�IDENTIFIER�OF�THE�HELD�CALL�WHICH�IS�TO�BERETRIEVED�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!2ECONNECT#ALL#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�




Comments

!�SUCCESSFUL�REQUEST�OF�THIS�SERVICE�WILL�CAUSE�AN�EXISTING�ACTIVE�CALLTO�BE�DROPPED��/NCE�THE�ACTIVE�CALL�HAS�BEEN�DROPPED��THE�SPECIFIEDHELD�CALL�AT�THE�DEVICE�IS�RETRIEVED�AND�BECOMES�ACTIVE��4HIS�SERVICE�ISTYPICALLY�USED�TO�DROP�AN�ACTIVE�CALL�AND�RETURN�TO�A�HELD�CALL�HOWEVER��IT�CAN�ALSO�BE�USED�TO�CANCEL�OF�A�CONSULTATION�CALL��BECAUSEOF�NO�ANSWER��CALLED�DEVICE�BUSY��ETC��FOLLOWED�BY�RETURNING�TO�A�HELDCALL�


Figure 5-14Reconnect Call Service

D1 C1D1 C1 D2D2

D3C2

ch

c D3C2

*

*

*

*

Before After


#34!2ECONNECT#ALL#ONF%VENT

The Reconnect Call confirmation event provides the positive response fromthe server for a previous Reconnect call request.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!2ECONNECT#ALL#ONF%VENT?TRECONNECT#ALL�

]U�]�CSTA#ONFIRMATION�


TYPEDEF�STRUCT�#34!2ECONNECT#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!2ECONNECT#ALL#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?2%#/..%#4?#!,,?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN#34!2ECONNECT#ALL#ONF%VENT�




CSTA2ETRIEVE#ALL��

The cstaRetrieveCall( ) service connects an existing Held Connection. Thestate of the specified call changes from held to active.

Syntax


2ET#ODE?T��CSTA2ETRIEVE#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T HELD#ALL�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



heldCall!�POINTER�TO�THE�CONNECTION�IDENTIFIER�OF�THE�HELD�CALL�WHICH�IS�TO�BERETRIEVED�


Return Values





4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!2ETRIEVE#ALL#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�





Comments

4HE�INDICATED�HELD�#ONNECTION�IS�RESTORED�TO�THE�#ONNECTED�STATE�ACTIVE��4HE�CALL�STATE�CAN�CHANGE�DEPENDING�ON�THE�ACTIONS�OF�FAREND�ENDPOINTS��)F�THE�CSTA(OLD#ALL��SERVICE�RESERVED�THE�(ELD#ONNECTION�AND�THE�CSTA2ETRIEVE#ALL��SERVICE�IS�REQUESTED�FOR�THESAME�CALL��THEN�THE�2ETRIEVE�#ALL�SERVICE�USES�THE�RESERVED#ONNECTION�

Figure 5-15Retrieve Call Service

D1 C1 D1 C1 D2D2 ch * *

Before After


#34!2ETRIEVE#ALL#ONF%VENT

The Retrieve Call confirmation event provides the positive response from theserver for a previous Retrieve call request.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND�#34!�$ATA�4YPESIN�3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!2ETRIEVE#ALL#ONF%VENT?T��RETRIEVE#ALL�]U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!2ETRIEVE#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!2ETRIEVE#ALL#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?2%42)%6%?#!,,?#/.&�WHICH�IDENTIFIES�THIS�MESSAGE�AS�AN�#34!2ETRIEVE#ALL#ONF%VENT�




CSTA4RANSFER#ALL��

The cstaTransferCall( ) service provides the transfer of a held call with anactive call at the same device. The transfer service merges two calls withConnections to a single common device. Also, both of the Connections to thecommon device become Null and their Connections Identifiers are released.

Syntax


2ET#ODE?T��CSTA4RANSFER#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T HELD#ALL�#ONNECTION)$?T ACTIVE#ALL�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



heldCall!�POINTER�TO�THE�CONNECTION�IDENTIFIER�OF�THE�HELD�CALL�WHICH�IS�TO�BETRANSFERRED�

activeCall!�POINTER�TO�THE�CONNECTION�IDENTIFIER�OF�THE�ACTIVE�CALL�TO�WHICH�THEHELD�CALL�IS�TO�BE�TRANSFERRED�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!4RANSFER#ALL#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�




Comments

2EFERRING�TO�&IGURE�� THE�STARTING�CONDITIONS�FOR�THECSTA4RANSFER#ALL��SERVICE�ARE��THE�CALL�#��FROM�$��TO�$��IS�IN�HELDSTATE��HELD#ALL��!�CALL�#��FROM�$��TO�$��IS�IN�PROGRESS�OR�ACTIVE�ACTIVE#ALL��4HIS�SERVICE�TRANSFERS�THE�EXISTING��HELD�CALL�BETWEENDEVICES�$��AND�$��INTO�A�NEW�CALL�WITH�A�NEW�CALL�IDENTIFIER�FROMDEVICE�$��TO�A�DEVICE�$��


Figure 5-16Transfer Call Service

D1 C1 D2

D3C2

D1 D2

D3c

h

C3

*

**

*

Before After

4HE�REQUEST�IS�USED�IN�THE�SITUATION�WHERE�THE�CALL�FROM�$��TO�$��ISESTABLISHED��ACTIVE�OR�IF�THE�CALL�IS�IN�ANY�STATE�OTHER�THAN�&AILED�OR.ULL�STATE��4HE�4RANSFER�#ALL�SERVICE�SUCCESSFULLY�COMPLETES��AND�$�IS�RELEASED�FROM�THE�CALL�


#34!4RANSFER#ALL#ONF%VENT

The Transfer Call confirmation event provides the positive response from theserver for a previous transfer call request.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND�#34!�$ATA4YPES�IN�3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!4RANSFER#ALL#ONF%VENT?T��TRANSFER#ALL�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#ONNECTION?T�[��#ONNECTION)$?T��PARTY��3UBJECT$EVICE)$?T��STATIC$EVICE��.5,,�FOR�NOT�PRESENT

�]�#ONNECTION?T�

TYPEDEF�STRUCT�#ONNECTION,IST�[��INT��COUNT��#ONNECTION?T��CONNECTION�]�#ONNECTION,IST?T�

TYPEDEF�STRUCT�[��#ONNECTION)$?T��NEW#ALL��#ONNECTION,IST?T��CONN,IST�]�#34!4RANSFER#ALL#ONF%VENT?T�


Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?42!.3&%2?#!,,?#/.&�WHICH�IDENTIFIES�THIS�MESSAGE�AS�AN�#34!4RANSFER#ALL#ONF%VENT�


newCall3PECIFIES�THE�RESULTING�#ONNECTION�)DENTIFIER�FOR�THE�TRANSFERRED�CALL�

connList3PECIFIES�THE�RESULTING�NUMBER�OF�KNOWN�DEVICES�IN�THE�TRANSFERREDCALL��4HIS�FIELD�CONTAINS�A�COUNT��COUNT�OF�THE�NUMBER�OF�DEVICES�INTHE�TRANSFERRED�CALL�AND�A�POINTER��CONNECTION�TO�AN�ARRAY�OFPOINTERS�THAT�POINT�TO�#ONNECTION)$?T�STRUCTURES�WHICH�DEFINE�EACHCONNECTION�IN�THE�CALL�

%ACH�#ONNECTION)$?T��RECORD�CONTAINS�THE�FOLLOWING�

0ARTY� �INDICATES�THE�#ONNECTION�)$�OF�THE�PARTY�IN�THETRANSFERRED�CALL�

$EVICE� �PROVIDES�THE�STATIC�REFERENCE�FOR�THE�PARTY�IN�THETRANSFERRED�CALL��4HIS�PARAMETER�MAY�HAVE�A�VALUE�THATINDICATES�THE�STATIC�IDENTIFIER�IS�NOT�KNOWN�



4ELEPHONY�3UPPLEMENTARY�3ERVICES

This section describes those CSTA telephony services that switches typicallyprovide as "features".

Not all switches support all these functions and events.

Applications can use the Telephony Supplementary Services (defined in thissection) to manipulate telephony objects.. As with other TSAPI servicesalready described, these function will generate associated confirmation eventsfrom the Telephony Server. Similarly (as described in Chapter 4, SendingCSTA Requests and Responses) applications can use the invokeID to match aspecific confirmation event with the specific function call, or they may useapplication-generated invokeIDs to index into a data structure.


.OTE


CSTA3ET-SG7AITING)ND��

The cstaSetMsgWaitingInd( ) service provides the application with theability to turns on and off a message waiting indicator on a telephony device.

Syntax


2ET#ODE?T��CSTA3ET-SG7AITING)ND��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�"OOLEAN MESSAGES�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



device4HIS�PARAMETER�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�ONWHICH�TO�SET�THE�MESSAGE�WAITING�INDICATOR��

messages4HIS�PARAMETER�IDENTIFIES�WHETHER�TO�TURN�ON�OR�OFF�THE�MESSAGEWAITING�INDICATOR�AT�THE�DEVICE�SPECIFIED�BY�DEVICE�PARAMETER��!�VALUEOF�425%�INDICATES�THAT�THE�MESSAGE�WAITING�INDICATOR�SHOULD�BETUNED�ON��&!,3%�INDICATES�THAT�THE�INDICATOR�SHOULD�BE�TURN�OFF�



2ETURN�6ALUES




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!3ET-WI#ONF%VENTMESSAGE�TO�ENSURE�THAT�THE�SERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGEDAND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THE�SWITCH�





#34!3ET-WI#ONF%VENT

The Set Message Waiting Indicator confirmation event provides the positiveresponse from the Telephony Server for a previous Set Message WaitingIndicator service request. When the application receives this event themessage waiting indicator has been set as requested by the application.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND��#34!�$ATA4YPES�IN�3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!3ET-WI#ONF%VENT?T��SET-WI�]U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!3ET-WI#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!3ET-WI#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?3%4?-7)?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN#34!3ET-ESSAGE7AITING)ND#ONF%VENT�




CSTA3ET$O.OT$ISTURB��

The cstaSetDoNotDisturb( ) service activates the switch feature that preventscalls from alerting at a specified device by deflecting the calls from theoriginal destination to other devices.

Syntax


2ET#ODE?T��CSTA3ET$O.OT$ISTURB��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�"OOLEAN DO.OT$ISTURB�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



device4HIS�PARAMETER�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�ONWHICH�THE�$O�.OT�$ISTURB�FEATURE�IS�TO�BE�ACTIVATED��4HIS�PARAMETERMAY�BE�DIFFERENT�THAN�THE�ORIGINATING�DEVICE�DEPENDING�ON�THESECURITY�LEVEL�DEFINED�FOR�THE�ORIGINATING�DEVICE�IN�THE�4ELEPHONY3ERVER�

doNotDisturb4HIS�PARAMETER�IDENTIFIES�WHETHER�TO�TURN�ON�OR�OFF�THE�$O�.OT$ISTURB�FEATURE�AT�THE�DEVICE�SPECIFIED�BY�DEVICE�PARAMETER��!�VALUEOF�425%�INDICATES�THAT�THE�$O�.OT�$ISTURB�FEATURE�SHOULD�BE�TUNEDON��&!,3%�INDICATES�THAT�THE�FEATURE�SHOULD�BE�TURN�OFF�



Return Values

4HIS� FUNCTION� RETURNS� THE� FOLLOWING� VALUES� DEPENDING� ON� WHETHER� THEAPPLICATION� IS� USING� LIBRARY� OR� APPLICATION GENERATED� INVOKEIDENTIFIERS�



4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!3ET$ND#ONF%VENTMESSAGE�TO�ENSURE�THAT�THE�SERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGEDAND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THE�SWITCH�





#34!3ET$ND#ONF%VENT

The Set Do Not Disturb confirmation event provides the positive responsefrom the Telephony Server for a previous Set Do Not Disturb request. Whenthe application receives this event the Do Not Disturb feature has been set asrequested by the application.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND��#34!�$ATA4YPES��IN�3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!3ET$ND#ONF%VENT?T��SET$ND�]U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!3ET$ND#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!3ET$ND#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?3%4?$.$?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!3ET$ND#ONF%VENT�




CSTA3ET&ORWARDING��

The cstaSetForwarding( ) service activates and deactivates several types offorwarding features on a specified device.

Syntax


2ET#ODE?T��CSTA3ET&ORWARDING��

!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�&ORWARDING4YPE?T FORWARDING4YPE�"OOLEAN FORWARDING/N�$EVICE)$?T FORWARDING$ESTINATION�0RIVATE$ATA?T PRIVATE$ATA�

TYPEDEF�ENUM�&ORWARDING4YPE?T�[��&7$?)--%$)!4%��&7$?"539��&7$?./?!.3��&7$?"539?).4��&7$?"539?%84��&7$?./?!.3?).4��&7$?./?!.3?%84��]�&ORWARDING4YPE?T�

Parameters




device4HIS�PARAMETER�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�ONWHICH�FORWARDING�IS�TO�BE�SET��4HIS�PARAMETER�MAY�BE�DIFFERENT�THANTHE�ORIGINATING�DEVICE�DEPENDING�ON�THE�SECURITY�LEVEL�DEFINED�FOR�THEORIGINATING�DEVICE�IN�THE�4ELEPHONY�3ERVER�

forwardingType4HIS�PARAMETER�SPECIFIES�THE�TYPE�OF�FORWARDING�TO�SET�OR�CLEAR�AT�THEREQUESTED�DEVICE��4HE�POSSIBLE�TYPES�INCLUDE�

)MMEDIATE &ORWARDING�ALL�CALLS

"USY &ORWARDING�WHEN�BUSY

.O�!NSWER &ORWARDING�AFTER�NO�ANSWER

"USY�)NTERNAL &ORWARDING�WHEN�BUSY�FOR�ANINTERNAL�CALL

"USY�%XTERNAL &ORWARDING�WHEN�BUSY�FOR�ANEXTERNAL�CALL

.O�!NSWER�)NTERNAL &ORWARDING�AFTER�NO�ANSWERFOR�AN�INTERNAL�CALL

.O�!NSWER�%XTERNAL &ORWARDING�AFTER�NO�ANSWERFOR�AN�EXTERNAL�CALL�

forwardingOn4HIS�PARAMETER�IDENTIFIES�WHETHER�TO�TURN�ON�OR�OFF�THE�FORWARDINGFEATURE�AT�THE�DEVICE�SPECIFIED�BY�DEVICE�PARAMETER��!�VALUE�OF�425%INDICATES�THAT�THE�FORWARDING�FEATURE�SHOULD�BE�TUNED�ON��&!,3%INDICATES�THAT�THE�FEATURE�SHOULD�BE�TURN�OFF�

forwardingDestination4HIS�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�FOR�THE�DEVICE�TO�WHICH�THECALLS�ARE�TO�BE�FORWARDED�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!3ET&WD#ONF%VENTMESSAGE�TO�ENSURE�THAT�THE�SERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGEDAND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THE�SWITCH�





#34!3ET&WD#ONF%VENT

The Set Forwarding confirmation event provides the positive response fromthe server for a previous Set Forwarding service request. When this event isreceived by the application the forwarding feature has been set as requested.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!3ET&WD#ONF%VENT?T��SET&WD�]U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!3ET&WD#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!3ET&WD#ONF%VENT?T�

Parameters




eventType4HIS� IS� A� TAG� WITH� THE� VALUE� #34!?3%4?&7$?#/.&�� WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!3ET&WD#ONF%VENT�




CSTA3ET!GENT3TATE��

The cstaSetAgentState( ) service changes an ACD agents work mode to onespecified by this service.

Syntax


2ET#ODE?T��CSTA3ET!GENT3TATE��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�!GENT-ODE?T AGENT-ODE�!GENT)$?T AGENT)$�!GENT'ROUP?T AGENT'ROUP�!GENT0ASSWORD?T AGENT0ASSWORD�0RIVATE$ATA?T PRIVATE$ATA�

TYPEDEF�ENUM�!GENT-ODE?T�[��!-?,/'?).��!-?,/'?/54��!-?./4?2%!$9��!-?2%!$9��!-?7/2+?./4?2%!$9��!-?7/2+?2%!$9��]�!GENT-ODE?T�

TYPEDEF�CHAR��!GENT)$?T;��=�TYPEDEF�$EVICE)$?T��!GENT'ROUP?T�TYPEDEF�CHAR��!GENT0ASSWORD?T;��=�

Parameters




device4HIS�PARAMETER�POINTS�TO��THE�DEVICE�IDENTIFIER�FOR�THE�!#$�AGENT�FORWHICH�THE�WORK�MODE�IS�TO�BE�CHANGED��4HIS�PARAMETER�MAY�BEDIFFERENT�THAN�THE�ORIGINATING�DEVICE�DEPENDING�ON�THE�SECURITY�LEVELDEFINED�FOR�THE�ORIGINATING�DEVICE�IN�THE�4ELEPHONY�3ERVER�

agentMode4HIS�PARAMETER�SPECIFIES�THE�WORK�MODE�STATE�WHICH�THE�AGENT�WILL�BEMOVED�TO��4HIS�COULD�BE�ONE�OF�THE�FOLLOWING�

,/'?).,/'?/54./4?2%!$92%!$97/2+?./4?2%!$97/2+?2%!$9

agentID!�POINTER�TO�THE�AGENT�IDENTIFIER�OF�THE�!#$�!GENT�WHOSE�WORK�MODEIS�TO�BE�CHANGED�

agentGroup!�POINTER�TO�THE�AGENT�GROUP�IDENTIFIER�FOR�THE�!#$�GROUP�OR�SPLIT�INWHICH�THE�AGENT�WILL�BE�LOGGED�INTO�OR�OUT�OF��4HIS�PARAMETER�IS�ONLYREQUIRED�WHEN�THE�AGENT-ODE�PARAMETER�IS�SET�FOR�THE�,/'?).�AND,/'?/54�WORK�MODES�

agentPassword!�POINTER�TO�A�PASSWORD�THAT�ALLOWS�THE�AGENT�TO�LOG�INTO�AN�!#$�SPLITOR�GROUP��4HIS�PARAMETER�IS�ONLY�REQUIRED�WHEN�THE�AGENT-ODEPARAMETER�IS�SET�FOR�THE�,/'?).�AND�,/'?/54�WORK�MODES�


Return Values





4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!3ET!GENT3TATE#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�





#34!3ET!GENT3TATE#ONF%VENT

The Set Agent State confirmation event provides the positive response fromthe server for a previous Set Agent State service request. When this event isreceived by the application the agent state has been set as requested.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!3ET!GENT3TATE#ONF%VENT?TSET!GENT3TATE�

]U�]�CSTA#ONFIRMATION�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!3ET!GENT3TATE#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!3ET!GENT3TATE#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?3%4?!'%.4?34!4%?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN#34!3ET!GENT3TATE#ONF%VENT�




CSTA1UERY-SG7AITING)ND��

The cstaQueryMessageWaitingInd( ) service provides the current state ofthe message waiting indicator of a specified device.

Syntax


2ET#ODE?T��CSTA1UERY-SG7AITING)ND��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



device4HIS�PARAMETER�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�ONWHICH�THE�MESSAGE�WAITING�INDICATOR�IS�BEING�QUERIED��4HIS�PARAMETERMAY�BE�DIFFERENT�THAN�THE�ORIGINATING�DEVICE�DEPENDING�ON�THESECURITY�LEVEL�DEFINED�FOR�THE�ORIGINATING�DEVICE�IN�THE�4ELEPHONY3ERVER�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!1UERY-WI#ONF%VENT�MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�





#34!1UERY-WI#ONF%VENT

The Query Message Waiting Indicator confirmation event provides thepositive response from the server for a previous Query Message WaitingIndicator service request. This event informs the application whether there areany messages waiting, i.e. whether the message waiting indicator is turned onor off.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!1UERY-WI#ONF%VENT?T��QUERY-WI�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!1UERY-WI#ONF%VENT?T�["OOLEAN��MESSAGES�

]�#34!1UERY-WI#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?15%29?-7)?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!1UERY-WI#ONF%VENT�


messages4HIS�PARAMETER�SPECIFIES�WHETHER�THERE�ARE�ANY�MESSAGES�WAITING�ATTHE�REQUESTED�DEVICE��425%�INDICATES�THAT�THERE�ARE�MESSAGESWAITING��&!,3%�INDICATES�THAT�THERE�ARE�NONE�



CSTA1UERY$O.OT$ISTURB��

The cstaQueryDoNotDisturb( ) service provides the current state of the donot disturb feature on a specific device.

Syntax


2ET#ODE?T��CSTA1UERY$O.OT$ISTURB��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



device4HIS�PARAMETER�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�ONWHICH�THE�$O�.OT�$ISTURB�FEATURE�IS�BEING�QUERIED��4HIS�PARAMETERMAY�BE�DIFFERENT�THAN�THE�ORIGINATING�DEVICE�DEPENDING�ON�THESECURITY�LEVEL�DEFINED�FOR�THE�ORIGINATING�DEVICE�IN�THE�4ELEPHONY3ERVER�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!1UERY$ND#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�





#34!1UERY$ND#ONF%VENT

The Query Do Not Disturb confirmation event provides the positive responsefrom the server for a previous Query Do Not Disturb service request. Thisevent informs the application whether the feature is turned on or off.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!1UERY$ND#ONF%VENT?T��QUERY$ND�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

"OOLEAN?T DO.OT$ISTURB�]�#34!1UERY$ND#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?15%29?$.$?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!1UERY$ND#ONF%VENT�


doNotDisturb4HIS�PARAMETER�SPECIFIES�WHETHER�THE�$O�.OT�$ISTURB�FEATURE�IS�ACTIVEAT�THE�REQUESTED�DEVICE��425%�INDICATES�THAT�THE�FEATURE�IS�TURNED�ON�&!,3%�INDICATES�THAT�THE�FEATURE�IS�TURNED�OFF�



CSTA1UERY&WD��

The cstaQueryFwd( ) service provides the current state of the forwardingfeature(s) on a specific device.

Syntax


2ET#ODE?T��CSTA1UERY&WD��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



device4HIS�PARAMETER�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�ONWHICH�THE�FORWARDING�FEATURE�IS�BEING�QUERIED��4HIS�PARAMETER�MAY�BEDIFFERENT�THAN�THE�ORIGINATING�DEVICE�DEPENDING�ON�THE�SECURITY�LEVELDEFINED�FOR�THE�ORIGINATING�DEVICE�IN�THE�4ELEPHONY�3ERVER�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!1UERY&WD#ONF%VENT�MESSAGE�TO�ENSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�





#34!1UERY&WD#ONF%VENT

The Query Forwarding confirmation event provides the positive response fromthe server for a previous Query Forwarding service request. The event alsoinforms the application of the forwarding type, whether forwarding is on oroff, and the forwarding destination for each device requested.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!1UERY&WD#ONF%VENT?TQUERY&WD�



TYPEDEF�ENUM�&ORWARDING4YPE?T�[&7$?)--%$)!4%��&7$?"539��&7$?./?!.3��&7$?"539?).4��&7$?"539?%84��&7$?./?!.3?).4��&7$?./?!.3?%84��

]�&ORWARDING4YPE?T�

TYPEDEF�STRUCT�&ORWARDING)NFO?T�[&ORWARDING4YPE?T FORWARDING4YPE�"OOLEAN FORWARDING/N�


$EVICE)$?T FORWARD$.�]�&ORWARDING)NFO?T�

TYPEDEF�STRUCT�,IST&ORWARD0ARAMETERS?T�[SHORT COUNT�&ORWARDING)NFO?T PARAM;�=�

]�,IST&ORWARD0ARAMETERS?T�

TYPEDEF�STRUCT�#34!1UERY&WD#ONF%VENT?T�[,IST&ORWARD0ARAMETERS?T FORWARD�

]�#34!1UERY&WD#ONF%VENT?T�

Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?15%29?&7$?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!1UERY&WD#ONF%VENT�


queryFwd4HIS�PARAMETER��IS�A�,IST&ORWARD0ARAMETERS?T�STRUCTURE�WHICHCONTAINS�THE�FOLLOWING�

count4HIS�PARAMETER�INDICATES�HOW�MANY�FORWARDING�LIST�ENTRIES�AREPROVIDED��%ACH�ENTRY�CORRESPONDS�TO�A�DIFFERENT�DEVICE�

param!N�ARRAY�OF��&ORWARDING)NFO?T�STRUCTURES��EACH�OF�WHICH�IS�COMPOSEDOF��THE�FOLLOWING�ELEMENTS�


forwardingType3PECIFIES�THE�TYPE�OF�FORWARDING�SET��4HE�TYPES�INCLUDE�



.O�!NSWER &ORWARDING�AFTER�NOANSWER

"USY�)NTERNAL &ORWARDING�WHEN�BUSYFOR�AN�INTERNAL�CALL

"USY�%XTERNAL &ORWARDING�WHEN�BUSYFOR�AN�EXTERNAL�CALL

.O�!NSWER�)NTERNAL &ORWARDING�AFTER�NOANSWER�FOR�AN�INTERNAL�CALL

.O�!NSWER�%XTERNAL &ORWARDING�AFTER�NOANSWER�FOR�AN�EXTERNALCALL�

forwardingOn)NDICATES�WHETHER�FORWARDING�IS�ACTIVE�OR�INACTIVE��425%�INDICATESFORWARDING�IS�ACTIVE��&!,3%�INDICATES�FORWARDING�IS�INACTIVE�

forwardingDN3PECIFIES�THE�FORWARD TO�DESTINATION�DEVICE�FOR�THE�TYPE�OF�FORWARDINGLISTED�



CSTA1UERY!GENT3TATE��

The cstaQueryAgentState( ) service will provide the application with thecurrent agent state at a device.

Syntax


2ET#ODE?T��CSTA1UERY!GENT3TATE��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



device4HIS�PARAMETER�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�ONWHICH�THE�AGENT�STATE�IS�BEING�QUERIED��4HIS�PARAMETER�MAY�BEDIFFERENT�THAN�THE�ORIGINATING�DEVICE�DEPENDING�ON�THE�SECURITY�LEVELDEFINED�FOR�THE�ORIGINATING�DEVICE�IN�THE�4ELEPHONY�3ERVER�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!1UERY!GENT3TATE#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THESERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�





#34!1UERY!GENT3TATE#ONF%VENT

The Query Agent State confirmation event provides the positive response fromthe server for a previous Query Agent State service request. This event willprovide the application with the current agent state.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!1UERY!GENT3TATE#ONF%VENT?T�QUERY!GENT3TATE�]�U�


]�#34!%VENT?T�

TYPEDEF�ENUM�!GENT3TATE?T�[��!'?./4?2%!$9��!'?.5,,��!'?2%!$9��!'?7/2+?./4?2%!$9��!'?7/2+?2%!$9��]�!GENT3TATE?T�

TYPEDEF�STRUCT�#34!1UERY!GENT3TATE#ONF%VENT?T�[��!GENT3TATE?T��AGENT3TATE�]�#34!1UERY!GENT3TATE#ONF%VENT?T�


Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE#34!?15%29?!'%.4?34!4%?#/.&��WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!1UERY!GENT3TATE#ONF%VENT�


agentState4HIS�PARAMETER�SPECIFIES�THE�CURRENT�WORK�MODE�STATE�OF�THE�AGENT�4HE�POSSIBLE�AGENT�STATES�ARE�

.ULL� ��4HIS�INDICATES�THAT�AN�AGENT�IS�LOGGED�OUT�OF�THEGROUP�OR�DEVICE�THAT�THEY�SERVE�

.OT�2EADY� �4HIS�STATE�INDICATES�THAT�AN�AGENT�IS�OCCUPIEDWITH�SOME�TASK�OTHER�THAN�THAT�OF�SERVING�A�CALL�

2EADY� �4HIS�STATE�INDICATES�THAT�AN�AGENT�IS�READY�TO�ACCEPTCALLS�

7ORK�.OT�2EADY� �4HIS�STATE�INDICATES�THAT�AN�AGENT�ISOCCUPIED�WITH�AFTER�CALL�WORK��)T�ALSO�IMPLIES�THAT�THE�AGENTSHOULD�NOT�RECEIVE�ADDITIONAL�!#$�CALLS�

7ORK�2EADY� �4HIS�STATE�INDICATES�THAT�AN�AGENT�IS�OCCUPIEDWITH�AFTER�CALL�WORK��)T�ALSO�IMPLIES�THAT�THE�AGENT�MAYRECEIVE�ADDITIONAL�!#$�CALLS�




CSTA1UERY,AST.UMBER��

The cstaQueryLastNumber( ) service provides the last number dialed by aspecified device.

Syntax


2ET#ODE?T��CSTA1UERY,AST.UMBER��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



device4HIS�PARAMETER�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�ONWHICH�THE�LAST�NUMBER�IS�BEING�QUERIED��4HIS�PARAMETER�MAY�BEDIFFERENT�THAN�THE�ORIGINATING�DEVICE�DEPENDING�ON�THE�SECURITY�LEVELDEFINED�FOR�THE�ORIGINATING�DEVICE�IN�THE�4ELEPHONY�3ERVER�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!1UERY,AST.UMBER#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THESERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�





#34!1UERY,AST.UMBER#ONF%VENT

The Query Last Number confirmation event provides the positive responsefrom the server for a previous Query Last Number request. This eventprovides the last number that was dialed from the requested device.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!1UERY,AST.UMBER#ONF%VENT?T��QUERY,AST.UMBER�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

$EVICE)$?T LAST.UMBER�]�#34!1UERY,AST.UMBER#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE#34!?15%29?,!34?.5-"%2?#/.&��WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!1UERY,AST.UMBER#ONF%VENT�


lastNumber4HIS�PARAMETER�INDICATES�THE�LAST�NUMBER�DIALED�AT�THE�REQUESTEDDEVICE�



CSTA1UERY$EVICE)NFO��

The cstaQueryDeviceInfo( ) service provides general information about adevice. The confirmation event for this service will include information on theclass and type of device being queried.

Syntax


2ET#ODE?T��CSTA1UERY$EVICE)NFO��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



device4HIS�PARAMETER�IS�A�POINTER�TO�THE�DEVICE�IDENTIFIER�OF�THE�DEVICE�FORWHICH�INFORMATION�IS�BEING�REQUESTED��4HIS�PARAMETER�MAY�BEDIFFERENT�THAN�THE�ORIGINATING�DEVICE�DEPENDING�ON�THE�SECURITY�LEVELDEFINED�FOR�THE�ORIGINATING�DEVICE�IN�THE�4ELEPHONY�3ERVER�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!1UERY$EVICE)NFO#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THESERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�





#34!1UERY$EVICE)NFO#ONF%VENT

The Query Device Info confirmation event provides the positive responsefrom the server for a previous Query Device Info request. This event providesthe application with type and class of the requested device.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!1UERY$EVICE)NFO#ONF%VENT?T�QUERY$EVICE)NFO�]�U�

]�CSTA#ONFIRMATION�


TYPEDEF�ENUM�$EVICE4YPE?T�[��$4?34!4)/.��$4?,).%��$4?"544/.��$4?!#$��$4?425.+��$4?/0%2!4/2��$4?34!4)/.?'2/50��$4?,).%?'2/50��$4?"544/.?'2/50��$4?!#$?'2/50��$4?425.+?'2/50��$4?/0%2!4/2?'2/50��$4?/4(%2��]�$EVICE4YPE?T�


TYPEDEF�UNSIGNED�CHAR��$EVICE#LASS?T��DEFINE��$#?6/)#%��X��DEFINE��$#?$!4!��X��DEFINE��$#?)-!'%��X��DEFINE��$#?/4(%2��X��

TYPEDEF�STRUCT�#34!1UERY$EVICE)NFO#ONF%VENT?T�[��$EVICE)$?T��DEVICE��$EVICE4YPE?T��DEVICE4YPE��$EVICE#LASS?T��DEVICE#LASS�]�#34!1UERY$EVICE)NFO#ONF%VENT?T�

Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE#34!?15%29?$%6)#%?).&/?#/.&��WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!1UERY$EVICE)NFO#ONF%VENT�


deviceIdentifier-AY�PROVIDE�AN�ALTERNATE�SHORT FORM�STATIC�DEVICE�IDENTIFIER�FOR�THEDEVICE�REQUESTED�

deviceType4HIS�PARAMETER�INDICATES�THE�TYPE�OF�DEVICE�BEING�QUERIED��4HEPOSSIBLE�DEVICE�TYPES�ARE�

!#$� �!UTOMATIC�#ALL�$ISTRIBUTOR��!#$

!#$�GROUP� �!UTOMATIC�#ALL�$ISTRIBUTOR��!#$�GROUP

"UTTON� �IS�ONE�INSTANCE�OF�A�CALL�MANIPULATION�POINT�AT�ANINDIVIDUAL�STATION�


"UTTON�GROUP� �IS�TWO�OR�MORE�INSTANCES�OF�A�CALLMANIPULATION�POINT�AT�AN�INDIVIDUAL�STATION�

,INE� �IS�A�COMMUNICATIONS�INTERFACE�TO�ONE�OR�MORE�STATIONS�

,INE�GROUP� �IS�A�SET�OF�COMMUNICATIONS�INTERFACES�TO�ONE�ORMORE�STATIONS�

/PERATOR� �ALSO�KNOWN�AS�!TTENDANT

/PERATOR�GROUP� �TWO�OR�MORE�OPERATOR�DEVICES�USEDINTERCHANGEABLY�OR�ADDRESSED�IDENTICALLY�

/THER� �IS�ANY�OTHER�TYPE�FOR�WHICH�THERE�IS�NO�ENUMERATIONDEFINED�

3TATION� �IS�THE�TRADITIONAL�TELEPHONE�DEVICE��EITHER�SIMPLE�ORFEATURED�

3TATION�GROUP� �IS�TWO�OR�MORE�STATIONS�USED�INTERCHANGEABLYOR�ADDRESSED�IDENTICALLY�

4RUNK� �A�DEVICE�USED�TO�ACCESS�OTHER�SWITCHING�SUB DOMAINS�

4RUNK�GROUP� �TYPICALLY��TWO�OR�MORE�TRUNKS�PROVIDINGCONNECTIONS�TO�THE�SAME�PLACE�

3EE�THE�&UNCTIONAL�#ALL�-ODEL�SECTION�OF�THIS�DOCUMENT�FOR�MOREINFORMATION�ON�DEVICE�TYPES��.OT�ALL�SWITCH�IMPLEMENTATIONS�WILLSUPPORT�ALL�THE�DEVICE�TYPES�LISTED�

deviceClass4HIS�PARAMETER�INDICATES�THE�CLASS�OF�DEVICE�BEING�QUERIED��4HEPOSSIBLE�DEVICE�CLASSES�ARE�

6OICE� �A�DEVICE�THAT�IS�USED�TO�MAKE�AUDIO�CALLS��4HIS�CLASSINCLUDES�ALL�NORMAL�TELEPHONES��AS�WELL�AS�COMPUTER�MODEMSAND�'��FACSIMILE�MACHINES�

$ATA� �A�DEVICE�THAT�IS�USED�TO�MAKE�DIGITAL�DATA�CALLS��EITHERCIRCUIT�SWITCHED�OR�PACKET�SWITCHED��4HIS�CLASS�INCLUDESCOMPUTER�INTERFACES�AND�'��FACSIMILE�MACHINES�

)MAGE� �A�DEVICE�THAT�IS�USED�TO�MAKE�DIGITAL�DATA�CALLSINVOLVING�IMAGING��OR�HIGH�SPEED�CIRCUIT�SWITCHED�DATA�INGENERAL��4HIS�CLASS�INCLUDES�VIDEO�TELEPHONES�AND�#/$%#S�

/THER� �A�TYPE�OF�DEVICE�NOT�COVERED�BY�DATA��IMAGE��ORVOICE�


3EE�THE�&UNCTIONAL�#ALL�-ODEL�SECTION�OF�THIS�DOCUMENT�FOR�MOREINFORMATION�ON�DEVICE�CLASSES��.OT�ALL�SWITCH�IMPLEMENTATIONS�WILLSUPPORT�ALL�THE�DEVICE�CLASSES�LISTED�



C h a p t e r 6 Status Reporting Services

TSAPI Status Services are those function calls and events that are related tounsolicited TSAPI event messages. External telephony activity on the switch,External telephony activity at a device, or human user activity can all causeunsolicited TSAPI events. Such events messages are asynchronous in nature.An application typically cannot anticipate their arrival. For example, an eventinforming the application of an incoming call to a device (e.g. a telephonestation) is an unsolicited, asynchronous TSAPI event (since the application didnot initiate the call and such a call can arrive at any time).

Applications use the status reporting request function to turn-on or turn-offstatus event reporting for a CSTA device (e.g. a desktop telephone). Anapplication can use this function to turn-on/turn-off status reporting for anystations on the switch where monitoring is required (assuming proper accesspermissions are administered at the Telephony Server).


3TATUS�2EPORTING�&UNCTIONS�AND�#ONFIRMATION�%VENTS

Applications may use Event reporting to determine the changes in the state ofa call or a connection associated with a device which is of interest to theapplication. This section describes the functions that an application uses torequest unsolicited event reports for a telephony device or for calls. In thecase of calls, the application must first control the calls.

Events provide the application with information about the state of calls orconnection. The application may keep track of device or call states. If theapplication needs to maintain call state information for a specific device orcall within the switch, it must establish a device or call "monitor" to keep trackof the real-time state information for the call or device.

Applications should always be "event driven" and use events received fromthe Telephony Server to react to changes in call or connection state ratherthan using a specific switch implementation’s call state mode. Following thisguideline will simplify the support of applications across various switchimplementations of TSAPI.

An application calls the cstaMonitorDevice( ), cstaMonitorCall( ), orcstaMonitorCallsViaDevice( ) function to initiate event reporting for aspecific device or call. Event reporting can be provided for a device, a call, orfor calls at a monitored device. An application can request two different typesof event monitors using these functions. The monitor types are:

u Call-type monitor - call-type monitors provide monitoring (eventreporting) for unsolicited events about a specific call from "cradle-to-grave". In other words, a call-type monitor provides events for a specificcall regardless of the devices at which the call may appear for theduration of the call.

Using call-type monitoring, an application can determine the currentstate of the call using the TSAPI events. For example, if a call monitorexists for a specific call and that call transfers or forwards to otherdevices, the sending device ceases to participate in the call, but eventreporting continues (telling the application about the new devices


participating in the call). Thus, a call-type monitor will provide call stateinformation as the switch, other applications, and human users interactto route a call.

A switch may assign a new call identifier to a call as it is transferred orconferenced. The new call identifier will be provided in the event reportassociated with the conference or transfer function being requested bythe controller of the call.

u Device-type monitor - device-type monitors provide the applicationwith call or connection state information about calls at a specific device(the monitored device). TSAPI reports any events about the calls at themonitored device on a device-type monitor. If a call is transfers drops,or forwards from the monitored device, TSAPI stops reporting eventsfor that call.

If an application begins monitoring a device when call(s) are already inprogress at the monitored device, TSAPI may not provide events forthose calls (this is switch specific). TSAPI will provide events for callsthat arrive at the device after it sends the confirmation event for thedevice monitor request.

Each monitor must be either a call monitor, a device monitor, or monitor callsvia device. An application may request multiple monitors, with variousmonitors being of various types. An application must setup multiple monitorsif it wants to monitor multiple devices or calls at the same time. The switchmay impose limitations on the maximum number of simultaneous monitorswhich can exist for any given switch, call, or device. TSAPI does not placeany such restrictions on the application.

When an application requests a device or call monitor, it can also specify anevent filter. An event filter causes TSAPI to discard those events which theapplication is not interested in. An application may specify a filter when itestablishes the monitor for a device or call. An application may also use thecstaChangeMonitorFilter( ) to change the filter after the monitor is active.



CSTA-ONITOR$EVICE��

The Monitor Start service is used to initiate unsolicited event reporting for adevice type monitoring on a device object. The unsolicited event reports willbe provided for all endpoints within a CSTA switching sub-domain andoptionally for endpoints outside of the CSTA switching sub-domain(implementation specific) which are involved with a monitored device.

Syntax


2ET#ODE?T CSTA-ONITOR$EVICE��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE)$�#34!-ONITOR&ILTER?T MONITOR&ILTER�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



deviceID$EVICE�)$�OF�THE�DEVICE�TO�BE�MONITORED�

monitorFilter4HIS�PARAMETER�IS�USED�TO�SPECIFY�A�FILTER�TYPE�TO�BE�USED�WITH�THEOBJECT�BEING�MONITORED��3ETTING�A�BIT�TO�TRUE�IN�THE�MONITOR&ILTERSTRUCTURE�CAUSES�THE�SPECIFIC�EVENT�TO�BE�FILTERED�OUT��SO�THEAPPLICATION�WILL�NEVER�SEE�THIS�EVENT��)NITIALIZE�THE�STRUCTURE�TO�ALL��STO�RECEIVE�ALL�TYPES�OF�MONITOR�EVENTS��3EECSTA-ONITOR$EVICE#ONF%VENT�FOR�A�DEFINITION�OF�A�MONITOR&ILTERSTRUCTURE�


privateData0RIVATE�DATA�EXTENSION�MECHANISM��3ETTING�THIS�PARAMETER�IS�OPTIONAL�)F�THE�PARAMETER�IS�NOT�USED��THE�POINTER�SHOULD�BE�SET�TO�.5,,�

Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!-ONITOR#ONF%VENTMESSAGE�TO�INSURE�THAT�THE�SERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGEDAND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THE�SWITCH�





Comments

4HIS�FUNCTION�IS�USED�TO�START�A�DEVICE�MONITOR�ON�A�#34!�DEVICE��4HE�CONFIRMATION�EVENT�FOR�THIS�FUNCTION��I�E�#34!-ONITOR#ONF%VENT �WILL�PROVIDE�THE�APPLICATION�WITH�THE#34!�ASSOCIATION�HANDLE�TO�THE�MONITORED�DEVICE�OR�CALL��I�E��THE-ONITOR�#ROSS 2EFERENCE�)DENTIFIER��MONITOR#ROSS2EF)$�WHICHDEFINES�THE�#34!�ASSOCIATION�ON�WHICH�THE�MONITOR�WILL�EXIST�


CSTA-ONITOR#ALL��

The Monitor Start service is used to initiate unsolicited event reporting for acall type monitoring on a call object. The unsolicited event reports will beprovided for all endpoints within a CSTA switching sub-domain andoptionally for endpoints outside of the CSTA switching sub-domain(implementation specific) which are involved with a monitored device.

Syntax


2ET#ODE?T CSTA-ONITOR#ALL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T CALL�#34!-ONITOR&ILTER?T MONITOR&ILTER�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



call#ONNECTION��)$�OF�THE�CALL�TO�BE��MONITORED�

monitorFilter4HIS�PARAMETER�IS�USED�TO�SPECIFY�A�FILTER�TYPE�TO�BE�USED�WITH�THEOBJECT�BEING�MONITORED��3ETTING�A�BIT�TO�TRUE�IN�THE�MONITOR&ILTERSTRUCTURE�CAUSES�THE�SPECIFIC�EVENT�TO�BE�FILTERED�OUT��SO�THEAPPLICATION�WILL�NEVER�SEE�THIS�EVENT��)NITIALIZE�THE�STRUCTURE�TO�ALL��STO�RECEIVE�ALL�TYPES�OF�MONITOR�EVENTS��3EE�#34!-ONITOR#ONF%VENTFOR�A�DEFINITION�OF�A�MONITOR&ILTER�STRUCTURE�



Return Values








Comments

4HIS�FUNCTION�IS�USED�TO�START�A�CALL�MONITOR�ON�A�#34!�DEVICE��4HECONFIRMATION�EVENT�FOR�THIS�FUNCTION��I�E��#34!-ONITOR#ONF%VENTWILL�PROVIDE�THE�APPLICATION�WITH�THE�#34!�ASSOCIATION�HANDLE�TO�THEMONITORED�DEVICE�OR�CALL��I�E��THE�-ONITOR�#ROSS 2EFERENCE�)DENTIFIER�MONITOR#ROSS2EF)$�WHICH�DEFINES�THE�#34!�ASSOCIATION�ON�WHICHTHE�MONITOR�WILL�EXIST�


CSTA-ONITOR#ALLS6IA$EVICE��

The Monitor Start service is used to initiate unsolicited event reporting for acall type monitoring on a device object. The unsolicited event reports will beprovided for all endpoints within a CSTA switching sub-domain andoptionally for endpoints outside of the CSTA switching sub-domain(implementation specific) which are involved with a monitored device.

Syntax


2ET#ODE?T CSTA-ONITOR#ALLS6IA$EVICE��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T DEVICE)$�#34!-ONITOR&ILTER?T MONITOR&ILTER�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



device4HE�DEVICE)$�OF�THE�DEVICE�FOR�WHICH�CALL�MONITORING�SHOULD�BESTARTED�


monitorFilter4HIS�PARAMETER�IS�USED�TO�SPECIFY�A�FILTER�TYPE�TO�BE�USED�WITH�THEOBJECT�BEING�MONITORED��3ETTING�A�BIT�TO�TRUE�IN�THE�MONITOR&ILTERSTRUCTURE�CAUSES�THE�SPECIFIC�EVENT�TO�BE�FILTERED�OUT��SO�THEAPPLICATION�WILL�NEVER�SEE�THIS�EVENT��)NITIALIZE�THE�STRUCTURE�TO�ALL��STO�RECEIVE�ALL�TYPES�OF�MONITOR�EVENTS��3EECSTA-ONITOR$EVICE#ONF%VENT�FOR�A�DEFINITION�OF�A�MONITOR&ILTERSTRUCTURE�


Return Values









Comments

4HIS�FUNCTION�IS�USED�TO�START�A�MONITOR�ON�A�#34!�OBJECT��A�DEVICE�ORA�CALL��4HE�CONFIRMATION�EVENT�FOR�THIS�FUNCTION��I�E�#34!-ONITOR#ONF%VENT �WILL�PROVIDE�THE�APPLICATION�WITH�THE#34!�ASSOCIATION�HANDLE�TO�THE�MONITORED�DEVICE�OR�CALL��I�E��THE-ONITOR�#ROSS 2EFERENCE�)DENTIFIER��MONITOR#ROSS2EF)$�WHICHDEFINES�THE�#34!�ASSOCIATION�ON�WHICH�THE�MONITOR�WILL�EXIST��4HEREARE�TWO TYPES�OF�-ONITOR�3ERVICE��CALL TYPE�AND�DEVICE TYPE�


#34!-ONITOR#ONF%VENT

This event is in response to the cstaMonitorDevice( ), cstaMonitorCall orcstaMonitorCallsViaDevice function and contains the association handlebeing assigned to the CSTA association being used for status reporting.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!-ONITOR#ONF%VENT?T��MONITOR3TART�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!-ONITOR#ONF%VENT?T�[��#34!-ONITOR#ROSS2EF)$?T MONITOR#ROSS2EF)$��#34!-ONITOR&ILTER?T MONITOR&ILTER�]�#34!-ONITOR#ONF%VENT?T�

TYPEDEF�LONG #34!-ONITOR#ROSS2EF)$?T�

TYPEDEF�UNSIGNED�SHORT��#34!#ALL&ILTER?T��DEFINE��#&?#!,,?#,%!2%$��X��DEFINE��#&?#/.&%2%.#%$��X��DEFINE��#&?#/..%#4)/.?#,%!2%$��X��DEFINE��#&?$%,)6%2%$��X��DEFINE��#&?$)6%24%$��X��DEFINE��#&?%34!",)3(%$��X��DEFINE��#&?&!),%$��X��DEFINE��#&?(%,$��X��


�DEFINE��#&?.%47/2+?2%!#(%$��X��DEFINE��#&?/2)').!4%$��X��DEFINE��#&?15%5%$��X��DEFINE��#&?2%42)%6%$��X��DEFINE��#&?3%26)#%?).)4)!4%$��X��DEFINE��#&?42!.3&%22%$��X��

TYPEDEF�UNSIGNED�CHAR��#34!&EATURE&ILTER?T��DEFINE��&&?#!,,?).&/2-!4)/.��X��DEFINE��&&?$/?./4?$)3452"��X��DEFINE��&&?&/27!2$).'��X��DEFINE��&&?-%33!'%?7!)4).'��X��

TYPEDEF�UNSIGNED�CHAR��#34!!GENT&ILTER?T��DEFINE��!&?,/''%$?/.��X��DEFINE��!&?,/''%$?/&&��X��DEFINE��!&?./4?2%!$9��X��DEFINE��!&?2%!$9��X��DEFINE��!&?7/2+?./4?2%!$9��X��DEFINE��!&?7/2+?2%!$9��X��

TYPEDEF�UNSIGNED�CHAR��#34!-AINTENANCE&ILTER?T��DEFINE��-&?"!#+?).?3%26)#%��X��DEFINE��-&?/54?/&?3%26)#%��X��

TYPEDEF�STRUCT�#34!-ONITOR&ILTER?T�[#34!#ALL&ILTER?T CALL�#34!&EATURE&ILTER?T FEATURE�#34!!GENT&ILTER?T AGENT�#34!-AINTENANCE&ILTER?T MAINTENANCE�LONG PRIVATE&ILTER�

]�#34!-ONITOR&ILTER?T�

Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?-/.)4/2?#/.&��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!-ONITOR#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION�OREVENT��)T�IS�USED�TO�MATCH�A�SPECIFIC�FUNCTIONS�CALL�REQUEST�WITH�ITSCONFIRMATION�EVENTS��5NSOLICITED�EVENTS�WILL�HAVE�THIS�PARAMETER�SETTO�ZERO�


monitorCrossRefID4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�#34!�ASSOCIATION�FORWHICH�THE�REQUESTED�MONITOR�HAS�BEEN�ESTABLISHED��4HIS�HANDLE�ISTYPICALLY�CHOSEN�BY�THE�SWITCH�AND�SHOULD�BE�USED�BY�THE�APPLICATIONAS�A�REFERENCE�TO�A�SPECIFIC�ESTABLISHED�ASSOCIATION�

monitorFilter4HIS�PARAMETER�IS�USED�TO�SPECIFY�THE�FILTER�TYPE�WHICH�IS�ACTIVE�ON�THEOBJECT�BEING�MONITORED�BY�THE�APPLICATION��0OSSIBLE�CLASSES�OF�VALUESARE��#!,,?&),4%2��&%!452%?&),4%2��!'%.4?&),4%2�-!).4%.!.#%?&),4%2��AND�02)6!4%?&),4%2�


Comments

4HE�APPLICATION�SHOULD�CHECK�THIS�CONFIRMATION�EVENT�TO�OBTAIN�THEMONITOR#ROSS2EF)$�BEING�ASSIGNED�BY�THE�SWITCH�AND�TO�ENSURE�THATTHE�EVENT�FILTER�REQUESTED�HAS�BEEN�ACTIVATED��4HE�EVENT�INFORMS�THEAPPLICATION�WHICH�FILTERS�ARE�ACTIVE�ON�THE�GIVEN�#34!�ASSOCIATION�


CSTA-ONITOR3TOP��

The Monitor Stop Service is used to cancel a previously registered MonitorService on an existing CSTA monitor association, i.e. an activemonitorCrossRefID.

Syntax


2ET#ODE?T CSTA-ONITOR3TOP��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#34!-ONITOR#ROSS2EF)$?T MONITOR#ROSS2EF)$�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



monitorCrossRefID4HIS�PARAMETER�IDENTIFIES�THE�ORIGINAL�#34!�MONITOR�ASSOCIATION�FORWHICH�UNSOLICITED�EVENT�MONITORING�IS�TO�BE�CANCELED��4HIS�IDENTIFIERIS�PROVIDED�AS�A�RESULT�OF�A�MONITOR�START�SERVICE�REQUEST�IN�A#34!-ONITOR#ONF%VENT �FOR�A�CALL�OR�DEVICE�MONITOR�WITHIN�THESWITCHING�DOMAIN�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!-ONITOR3TOP#ONF%VENT �MESSAGE�TO�INSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�




Comments

CSTA-ONITOR3TOP ��CANCELS�A�PREVIOUSLY�REGISTERED�MONITORASSOCIATION�ON�A�#34!�OBJECT��A�DEVICE�OR�A�CALL�OBJECT��/NCE�ACONFIRMATION�EVENT�IS�ISSUED�FOR�THIS�FUNCTION��I�E��A#34!-ONITOR3TOP#ONF%VENT� �43!0)�TERMINATES�THE�PREVIOUSLYACTIVE�MONITORING�ASSOCIATION�AND�THUS�END�EVENT�REPORTING�FOR�THEMONITORED�CALL�OR�DEVICE�


#34!-ONITOR3TOP#ONF%VENT

This event is in response to the cstaMonitorStop( ) function and provides theapplication with a confirmation that the monitor association has been canceled.Once this confirmation event is issued all event reporting for the specificmonitoring association will be discontinued.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!-ONITOR3TOP#ONF%VENTMONITOR3TOP�



Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?-/.)4/2?34/0?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN�#34!-ONITOR3TOP#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION�OREVENT��)T�IS�USED�TO�MATCH�A�SPECIFIC�FUNCTIONS�CALL�REQUEST�WITH�ITSCONFIRMATION�EVENTS��5NSOLICITED�EVENTS�WILL�HAVE�THIS�PARAMETER�SETTO�ZERO�


Comments

4HIS�CONFIRMATION�EVENT�INDICATES�A�CANCELLATION�OF�A�#34!MONITORING�ASSOCIATION��!FTER�THIS�EVENT�IS�ISSUED�BY�THE�4ELEPHONY3ERVER��NO�FURTHER�EVENTS�WILL�BE�SENT�TO�THE�APPLICATION�ON�THEMONITORING�ASSOCIATION��MONITOR#ROSS2EF)$�WHICH�WAS�CANCELED�


CSTA#HANGE-ONITOR&ILTER��

This function is used to request a change in the filter options for CSTA eventreporting for a specific CSTA association. It allows the application to specifyfor which event category the application wishes to receive events.

Syntax


2ET#ODE?T CSTA#HANGE-ONITOR&ILTER��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#34!-ONITOR#ROSS2EF)$?T MONITOR#ROSS2EF)$�#34!-ONITOR&ILTER?T FILTERLIST�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



monitorCrossRefID4HIS�PARAMETER�IDENTIFIES�THE�#34!�ASSOCIATION��ASSOCIATION�HANDLEFOR�WHICH�A�CHANGE�IN�EVENT�FILTERING�IS�REQUIRED��4HE�ASSOCIATIONIDENTIFIER�IS�PROVIDED�BY�THE�SERVER�SWITCH�WHEN�THE�ASSOCIATION�ISESTABLISHED�

filterlist4HIS�PARAMETER�IDENTIFIES�THE�FILTER�TYPE�BEING�REQUESTED��0OSSIBLECLASSES�OF�VALUES�ARE�#!,,?&),4%2��&%!452%?&),4%2�!'%.4?&),4%2��-!).4%.!.#%?&),4%2��AND02)6!4%?&),4%2��4HIS�PARAMETER��ALSO�IDENTIFIES�THE�EVENTS�TO�BEFILTERED�



Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!#HANGE-ONITOR&ILTER#ONF%VENT �MESSAGE�TO�INSURE�THAT�THESERVICE�REQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�




Comments

!N�APPLICATION�USES�CSTA#HANGE-ONITOR&ILTER ��TO�INFORM�THE�!0)#LIENT�,IBRARY�AND�THE�SERVER�THAT�APPLICATION�WISHES�TO�RECEIVE�ONLYCERTAIN�EVENTS��4HE�SERVER�FILTERS�OUT�ALL�OTHER�EVENTS�


#34!#HANGE-ONITOR&ILTER#ONF%VENT

This event occurs as a result of the cstaChangeMonitorFilter( ) function andinforms the application which event filter was set by the server.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$?T�UNION[

#34!#HANGE-ONITOR&ILTER#ONF%VENT?TCHANGE-ONITOR&ILTER�



TYPEDEF�STRUCT�#34!#HANGE-ONITOR&ILTER#ONF%VENT?T[

#34!-ONITOR&ILTER?T MONITORFILTER�]��#34!#HANGE-ONITOR&ILTER#ONF%VENT?T

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!#ONFIRMATION�EVENT�


eventType4HIS�IS�A�TAG�WITH�THE�VALUE#34!?#(!.'%?-/.)4/2?&),4%2?#/.&��WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!#HANGE-ONITOR&ILTER#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION�OREVENT��)T�IS�USED�TO�MATCH�A�SPECIFIC�FUNCTION S�CALL�REQUEST�WITH�ITSCONFIRMATION�EVENTS��5NSOLICITED�EVENTS�WILL�HAVE�THIS�PARAMETER�SETTO�ZERO�

monitorFilter4HIS�PARAMETER�IDENTIFIES�THE�FILTER�TYPE�BEING�REQUESTED��0OSSIBLECLASSES�OF�VALUES�ARE�#!,,?&),4%2��&%!452%?&),4%2�!'%.4?&),4%2��-!).4%.!.#%?&),4%2��AND02)6!4%?&),4%2�

4HIS�PARAMETER��ALSO�IDENTIFIES�THE�EVENTS�TO�BE�FILTERED�


Comments

4HIS�CONFIRMATION�EVENT�SHOULD�BE�CHECKED�BY�THE�APPLICATION�TOINSURE�THAT�THE�EVENT�FILTER�REQUESTED�HAS�BEEN�ACTIVATED�AND�WHICHFILTERS�ARE�ALREADY�ACTIVE�ON�THE�GIVEN�#34!�ASSOCIATION�


#34!-ONITOR%NDED%VENT

This unsolicited indication is sent by the driver/switch to indicate to theapplication that the monitor associated with the monitorCrossRefID has beenstopped.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�3ECTIONS�!#3�$ATA�4YPES�AND�#34!$ATA�4YPES�FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

#34!-ONITOR#ROSS2EF)$?T MONITOR#ROSS2EF)$�UNION[

#34!-ONITOR%NDED?T��MONITOR%NDED�]�U�

]�CSTA5NSOLICITED�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!-ONITOR%NDED%VENT?T�[��#34!%VENT#AUSE?T�CAUSE�]�#34!-ONITOR%NDED%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!5.3/,)#)4%$��WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�


eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?-/.)4/2?%.$%$��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!-ONITOR%NDED%VENT�

monitorCrossRefID,4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�#34!�ASSOCIATION�FORWHICH�THIS�EVENT�IS�ASSOCIATED��4HIS�HANDLE�IS�TYPICALLY�CHOSEN�BY�THESWITCH�AND�SHOULD�BE�USED�BY�THE�APPLICATION�AS�A�REFERENCE�TO�ASPECIFIC�ESTABLISHED�ASSOCIATION�

cause4HE�CAUSE�CODE�INDICATING�THE�REASON�THE�MONITOR�WAS�STOPPED�


Comments

4HIS�EVENT�IS��PROVIDED�BY�THE�DRIVER�SWITCH�WHEN�IT�CAN�NO�LONGERPROVIDED�THE�REQUESTED�EVENTS�ASSOCIATED�WITH�THEMONITOR#ROSS2EF)D�


#ALL�%VENT�2EPORTS��5NSOLICITED

This section defines the unsolicited TSAPI Event Reports that result from callactivity at the Device or the switch. These events provide an application withcall status information. Applications, users, and switch administrators mayalso use switch features that interact with monitored devices and calls,resulting in additional call events. One example of such a feature is callcoverage paths.


#34!#ALL#LEARED%VENT

This event report indicates when a call is torn down. This can occur when thelast device has disconnected from the call or when a call is dissolved byanother party to the call - like a conference call being dissolved by theconference controller.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

#34!-ONITOR#ROSS2EF)$?T��MONITOR#ROSS2EF)$�UNION[

#34!#ALL#LEARED%VENT��CALL#LEARED�]�U�


]�#34!%VENT?T�

TYPEDEF�ENUM�,OCAL#ONNECTION3TATE?T�[��#3?.5,,��#3?).)4)!4%��#3?!,%24).'��#3?#/..%#4��#3?(/,$��#3?15%5%$��#3?&!),��]�,OCAL#ONNECTION3TATE?T�

TYPEDEF�ENUM�#34!%VENT#AUSE?T�[��!#4)6%?-/.)4/2��!,4%2.!4%��"539��


��#!,,?"!#+��#!,,?#!.#%,,%$��#!,,?&/27!2$?!,7!93��#!,,?&/27!2$?"539��#!,,?&/27!2$?./?!.37%2��#!,,?&/27!2$��#!,,?./4?!.37%2%$��#!,,?0)#+50��#!-0?/.��$%34?./4?/"4!).!",%��$/?./4?$)3452"��).#/-0!4)",%?$%34).!4)/.��).6!,)$?!##/5.4?#/$%��+%9?#/.&%2%.#%��,/#+/54��-!).4%.!.#%��.%47/2+?#/.'%34)/.��.%47/2+?./4?/"4!).!",%��.%7?#!,,��./?!6!),!",%?!'%.43��/6%22)$%��0!2+��/6%2&,/7��2%#!,,��2%$)2%#4%$��2%/2$%2?4/.%��2%3/52#%3?./4?!6!),!",%��3),%.4?-/.)4/2��42!.3&%2��425.+3?"539��6/)#%?5.)4?).)4)!4/2��]�#34!%VENT#AUSE?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T CLEARED#ALL�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!#ALL#LEARED%VENT?T�

Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?#!,,?#,%!2%$��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!#ALL#LEARED%VENT�


monitorCrossRefID,4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�#34!�ASSOCIATION�FORWHICH�THIS�EVENT�IS�ASSOCIATED��4HIS�HANDLE�IS�TYPICALLY�CHOSEN�BY�THESWITCH�AND�SHOULD�BE�USED�BY�THE�APPLICATION�AS�A�REFERENCE�TO�ASPECIFIC�ESTABLISHED�ASSOCIATION�

clearedCall4HIS�PARAMETER�IDENTIFIES�THE�CALL�WHICH�HAS�BEEN�CLEARED�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�ITHAS�BEEN�CLEARED��4HIS�COULD�BE�NULL��INITIATED��ALERTING��CONNECTED�HELD��QUEUED��OR�FAILED�

cause4HIS�PARAMETER�CONTAINS�THE�CAUSE�VALUE�WHICH�INDICATES�THE�REASON�OREXPLANATION�FOR�THE�OCCURRENCE�OF�THIS�EVENT��4HE�POSSIBLE�EVENTS�AREDEFINED�BY�#34!%VENT#AUSE?T�



Comments

4HIS�EVENT�IS�USUALLY�PROVIDED�AFTER�THE�CSTA#LEAR#ALL��FUNCTION�HASBEEN�CALLED�BY�THE�APPLICATION��)T�CAN�ALSO�OCCUR��UNSOLICITED��WHENANOTHER�ENDPOINT��DEVICE�CLEARS�A�CALL�AND�THE�DEVICE�BEINGMONITORED�BY�THE�!0)�IS�PART�OF�THE�CALL�CLEARED�BY�THE�ANOTHERENDPOINT��4HE�EVENT�IS�ALSO�GENERATED�WHEN�THE�LAST�REMAINING�DEVICEHAS�DISCONNECTED�FROM�THE�CALL�

Figure 6-17Call Cleared Event Report

D2

D3

D1D2

D3

D1 C1* *

*Before After


#34!#ONFERENCED%VENT

This event report provides indication that two separate calls have beenconferenced (merged) into a single call. This occurs without either party beingremoved from the resulting call.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��$ATA�4YPES�AND��#34!�$ATA�4YPES�IN3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

#34!-ONITOR#ROSS2EF)$?T��MONITOR#ROSS2EF)$�UNION[

#34!#ONFERENCED%VENT?T��CONFERENCED�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T PRIMARY/LD#ALL�#ONNECTION)$?T SECONDARY/LD#ALL�3UBJECT$EVICE)$?T CONF#ONTROLLER�3UBJECT$EVICE)$?T ADDED0ARTY�#ONNECTION,IST?T CONFERENCE#ONNECTIONS�,OCAL#ONNECTION3TATE?T� LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!#ONFERENCED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?#/.&%2%.#%$��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!#ONFERENCED%VENT�

monitorCrossRefID4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�#34!�ASSOCIATION�FORWHICH�THIS�EVENT�IS�ASSOCIATED��4HIS�HANDLE�IS�TYPICALLY�CHOSEN�BY�THESWITCH�AND�SHOULD�BE�USED�BY�THE�APPLICATION�AS�A�REFERENCE�TO�ASPECIFIC�ESTABLISHED�ASSOCIATION�

primaryOldCall4HIS�PARAMETER�IDENTIFIES�THE�PRIMARY�KNOWN�CALL�TO�BE�CONFERENCED�4HIS�IS�USUALLY�THE�HELD�CALL�PENDING�THE�CONFERENCE�

secondaryOldCall4HIS�PARAMETER�IDENTIFIES�THE�SECONDARY�CALL��E�G��THE�CONSULTATIVECALL�WHICH�IS�TO�BE�CONFERENCED��4HIS�IS�USUALLY�THE�ACTIVE�CALL�WHICHIS�TO�BE�CONFERENCED�TO�THE�HELD�CALL�PENDING�THE�CONFERENCE�

confController4HIS�STRUCTURE�IDENTIFIES�THE�DEVICE�WHICH�IS�CONTROLLING�THECONFERENCE��4HIS�IS�THE�DEVICE�WHICH�SETUP�THE�CONFERENCE��)F�THEDEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

addedParty4HIS�PARAMETER�IDENTIFIES�THE�DEVICE�WHICH�IS�BEING�ADDED�TO�THECONFERENCE��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILLINDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

conferenceConnections4HIS�IS�A�LIST�OF�CONNECTIONS��PARTIES�ON�THE�CALL�WHICH�RESULTED�FROMTHE�CONFERENCE��4HE�CALL�)$�MAY�BE�DIFFERENT�FROM�EITHER�THE�PRIMARYOR�SECONDARY�OLD�CALL��OR�BOTH�


localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�ITHAS�BEEN�CONFERENCED��4HIS�COULD�BE�NULL��INITIATED��ALERTING�CONNECTED��HELD��QUEUED��OR�FAILED�



Comments

4HIS�EVENT�PROVIDES�INFORMATION�REGARDING�A�CONFERENCE�AFTER�IS�HASBEEN�REQUESTED�BY�THE�APPLICATION�USING�THE�#34!#ONFERENCE#ALL��FUNCTION�OR�OTHER�ENDPOINTS�ON�THE�SWITCH��4HE�CHANGES�IN�THE�CALLSTATES�ARE�AS�FOLLOWS�

Figure 6-18Conferenced Event Report

D1 C1 D2

D3C2

D1 D2

D3c c

h

C3

* *

**Before After


#34!#ONNECTION#LEARED%VENT

This event report indicates that a device associated with a call disconnectsfrom the call or is dropped from the call. The event does not indicate that atransferring device has left a call through the act of transferring that call.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[��#34!-ONITOR#ROSS2EF)$?T MONITOR#ROSS2EF)$��UNION��[��#34!#ONNECTION#LEARED%VENT?T�CONNECTION#LEARED��]�U�]�CSTA5NSOLICITED�


TYPEDEF�STRUCT[

#ONNECTION)$?T DROPPED#ONNECTION�3UBJECT$EVICE)$?T RELEASING$EVICE�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!#ONNECTION#LEARED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?#/..%#4)/.?#,%!2%$�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN#34!#ONNECTION#LEARED%VENT�


droppedConnection4HIS�PARAMETER�IDENTIFIES�THE�#ONNECTION�WHICH�WAS�DROPPED�FROMTHE�CALL�AS�A�RESULT�OF��A�DEVICE�DROPPING�FROM�THE�CALL�

releasingDevice4HIS�PARAMETER�IDENTIFIES�THE�DEVICE�WHICH�DROPPED�THE�CALL�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THECONNECTION�HAS�BEEN�CLEARED��4HIS�COULD�BE�NULL��INITIATED��ALERTING�CONNECTED��HELD��QUEUED��OR�FAILED�




Comments

4HIS�EVENT�IS�USED�TO�DETERMINE�WHICH�DEVICE�DISCONNECTS�FROM�AMULTI PARTY�CALL��4HE�DEVICE)$�IDENTIFIES�THE�DEVICES�WHICHDISCONNECTED�OR�WAS�DISCONNECTED�FROM�THE�CALL��4HE,OCAL#ONNECTION)NFO�DEFINES�THE�STATE�OF�THE�CALL�AT�THE�MONITOREDDEVICE�AFTER�THE�DEVICE�HAS�BEEN�DROPPED�FROM�THE�CALL�

Figure 6-19Connection Cleared Event Report

D2

D3

D1D2

D3

D1 C1 C1* *

*

* *

Before After


#34!$ELIVERED%VENT

This event report indicates that a call is alerting (e.g. ringing) at a specificdevice or that the server has detected that a call is alerting at a specific device.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��#HAPTER��$ATA�4YPES�AND�#34!�$ATA4YPES�FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[��#34!-ONITOR#ROSS2EF)$?T MONITOR#ROSS2EF)$�

UNION[

#34!$ELIVERED%VENT?T��DELIVERED�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T CONNECTION�3UBJECT$EVICE)$?T ALERTING$EVICE�#ALLING$EVICE)$?T CALLING$EVICE�#ALLED$EVICE)$?T CALLED$EVICE�2EDIRECTION$EVICE?T LAST2EDIRECTION$EVICE�,OCAL#ONNECTION3TATE?T� LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!$ELIVERED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?$%,)6%2%$��WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!$ELIVERED%VENT�


connection4HIS�PARAMETER�IDENTIFIES�THE�#ONNECTION�WHICH�IS�ALERTING

alertingDevice4HIS�PARAMETER�INDICATES�WHICH�DEVICE�IS�ALERTING��)F�THE�DEVICE�IS�NOTSPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOTKNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

callingDevice4HIS�PARAMETER�IDENTIFIES�THE�CALLING�DEVICE��)F�THE�DEVICE�IS�NOTSPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOTKNOWN�OR�THAT�IT�WAS�NOT�REQUIRED

calledDevice4HIS�PARAMETER�IDENTIFIES�THE�ORIGINALLY�CALLED�DEVICE��)F�THE�DEVICE�ISNOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOTKNOWN�OR�THAT�IT�WAS�NOT�REQUIRED

lastRedirectionDevice4HIS�PARAMETER�WILL�IDENTIFY�THE�PREVIOUSLY�ALERTED�DEVICE�IN�CASESWHERE�THE�CALL�WAS�REDIRECTED�OR�DIVERTED�TO�THE�ALERTING�DEVICE��)F�THEDEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THE#ONNECTION�HAS�ALERTED��4HIS�COULD�BE�NULL��INITIATED��ALERTING�CONNECTED��HELD��QUEUED��OR�FAILED�




Comments

4HIS�EVENT�PROVIDES�ALL�THE�NECESSARY�INFORMATION�REQUIRED�WHEN�ANEW�CALL�ARRIVES�AT�A�DEVICE��4HIS�WILL�INCLUDE�THE�CALLING�AND�CALLEDNUMBERS�

Figure 6-20Delivered Event Report

D1 C1 D1 C1 D2D2 a **

Before After


#34!$IVERTED%VENT

This event report identifies a call which has been deflected or diverted from amonitored device. The call is no longer present or associated with the device.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�$ATA�4YPES�AND��#34!�$ATA�4YPES�IN3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!$IVERTED%VENT?T��DIVERTED�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T CONNECTION�3UBJECT$EVICE)$?T DIVERTING$EVICE�#ALLED$EVICE)$?T NEW$ESTINATION�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!$IVERTED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?$)6%24%$��WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!$IVERTED%VENT�


connection4HIS�PARAMETER�INDICATES�THE�#ONNECTION�WHICH�WAS�PREVIOUSLYALERTING��4HIS�CAN�BE�THE�INTENDED�#ONNECTION�FOR�THE�CALL�BEFORE�ITWAS�DIVERTED�

divertingDevice4HIS�PARAMETER�INDICATES�THE�DEVICE�FROM�WHICH�THE�CALL�WAS�DIVERTED�)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

newDestination4HIS�PARAMETER�INDICATES�THE�DEVICE�TO�WHICH�THE�CALL�WAS�DIVERTED��)FTHE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�DEVICE�BEINGMONITORED��4HIS�COULD�BE�NULL��INITIATED��ALERTING��CONNECTED��HELD�QUEUED��OR�FAILED�




Comments

4HIS�EVENT�IS�USED�TO�DETERMINE�INFORMATION�ABOUT�A�CALL�WHICH�HASBEEN�DIVERTED�FROM�A�MONITORED�DEVICE��4HIS�INCLUDES�INFORMATION�ONWHICH�DEVICE�THE�CALL�IS�BEING�DIVERTED�

Figure 6-21Diverted Event Report

D1 C1 D2 D1 C1 D2

D3 D3

a * *

*Before After


#34!%STABLISHED%VENT

This event report indicates that a device connects to a call.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��$ATA�4YPES�AND�#34!�$ATA�4YPES�IN3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!%STABLISHED%VENT?T��ESTABLISHED�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?TESTABLISHED#ONNECTION�

3UBJECT$EVICE)$?T ANSWERING$EVICE�#ALLING$EVICE)$?T CALLING$EVICE�#ALLED$EVICE)$?T CALLED$EVICE�2EDIRECTION$EVICE)$?T LAST2EDIRECTION$EVICE�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!%STABLISHED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?%34!",)3(%$��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!%STABLISHED%VENT�


establishedConnection4HIS�PARAMETER�IDENTIFIES�THE�#ONNECTION�WHICH�JOINED�THE�CALL�AS�ARESULT�OF�ANSWERING�THE�CALL�

answeringDevice4HIS�PARAMETER�INDICATES�THE�DEVICE�WHICH�HAS�JOINED�THE�CALL��I�E��THEANSWERING�DEVICE��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETERWILL�INDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOTREQUIRED�

callingDevice4HIS�INDICATES�WHICH�DEVICE�MADE�THE�CALL��I�E��THE�CALLING�DEVICE��)FTHE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

calledDevice4HIS�PARAMETER�INDICATES�THE�ORIGINALLY�CALLED�DEVICE��4HIS�MAY�NOTALWAYS�BE�THE�DEVICE�ANSWERING�A�CALL�AS�IS�THE�CASE�WITH�CALLFORWARDING�OR�COVERAGE��I�E��CALL�REDIRECTION��)F�THE�DEVICE�IS�NOTSPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOTKNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

lastRedirectionDevice4HIS�PARAMETER�INDICATES�THE�PREVIOUSLY�ALERTED�DEVICE�IN�CASES�WHEREA�CALL�IS�REDIRECTED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETERWILL�INDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOTREQUIRED�


localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�DEVICE�FOR�THECALL�WHICH�HAS�BEEN�ESTABLISHED��4HIS�COULD�BE�NULL��INITIATED��ALERTING�CONNECTED��HELD��QUEUED��OR�FAILED�



Comments

4HIS�EVENT�IS�TYPICALLY�USED�TO�DETERMINED�WHEN�A�CALL�IS�ANSWERED�BYAN�ENDPOINT�BEING�CALLED�BY�THE�APPLICATION��4HIS�INCLUDES�THE�CALLINGAND�CALLED�NUMBER�IDENTIFICATION�

Figure 6-22Established Event Report

D1 C1 D1 C1 D2D2 ca * *

Before After


#34!&AILED%VENT

This event report indicates that a call cannot be completed. The event appliesonly to a single Connection.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!&AILED%VENT?T��FAILED�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T FAILED#ONNECTION�3UBJECT$EVICE)$?T FAILING$EVICE�#ALLED$EVICE)$?T CALLED$EVICE�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!&AILED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?&!),%$��WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!&AILED%VENT�


failedConnection4HIS�PARAMETER�INDICATES�WHICH�#ONNECTION�HAS�FAILED�

failingDevice4HIS�PARAMETER�INDICATES�WHICH�DEVICE�HAS�FAILED��)F�THE�DEVICE�IS�NOTSPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOTKNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

calledDevice4HIS�PARAMETER�INDICATES�WHICH�DEVICE�WAS�CALLED�WHEN�THE�CALLFAILED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATETHAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THE#ONNECTION�HAS�FAILED��4HIS�COULD�BE�NULL��INITIATED��ALERTING�CONNECTED��HELD��QUEUED��OR�FAILED�




Comments

4HIS�EVENT�OCCURS�ANYTIME�A�CALL�CANNOT�BE�COMPLETED�FOR�ANY�REASON�E�G��3TATIONS�"USY��2EORDER�4ONE��4RUNKS�"USY��ETC��4HE�CAUSEPARAMETER�CONTAINS�THE�REASON�WHY�THE�CALL�FAILED�

Figure 6-23Failed Event Report

D1 D2C1D1 D2 c fC1c

Before After


#34!(ELD%VENT

This event report indicates that the server has detected that communications ona particular Connection has be interrupted (i.e. put on hold) by one of thedevices on the call. This event is usually associated with a call being placed onhold at a device.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!(ELD%VENT?T��HELD�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T HELD#ONNECTION�3UBJECT$EVICE)$?T HOLDING$EVICE�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!(ELD%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?(%,$��WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!(ELD%VENT�


heldConnection4HIS�PARAMETER�IDENTIFIES�THE�#ONNECTION�WHICH�WAS�PUT�ON�HOLD�BYTHE�DEVICE�

holdingDevice4HIS�PARAMETER�IDENTIFIES�THE�DEVICE�WHICH�PLACED�THE�CONNECTION�ONHOLD��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATETHAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THE#ONNECTION�HAS�BEEN�PUT�ON�HOLD��4HIS�COULD�BE�NULL��INITIATED�ALERTING��CONNECTED��HELD��QUEUED��OR�FAILED�




Comments

4HIS�EVENT�OCCURS�AFTER�A�CALL�HAS�BEEN�PLACED�ON�HOLD�AT�A�SPECIFICDEVICE��4HIS�INFORMS�THE�APPLICATION�WHAT�DEVICE�PLACED�THECONNECTION�ON�HOLD�

Figure 6-24Held Event Report

D1 C1 D1 C1 D2D2 hc * *

Before After


#34!.ETWORK2EACHED%VENT

This event report informs the application that a call has left the switch on anoutbound trunk and is being routed through the telephone network.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�$ATA�4YPES�AND��#34!�$ATA�4YPES�IN3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[��#34!.ETWORK2EACHED%VENT?T��NETWORK2EACHED�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T CONNECTION�3UBJECT$EVICE)$?T TRUNK5SED�#ALLED$EVICE)$?T CALLED$EVICE�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!.ETWORK2EACHED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?.%47/2+?2%!#(%$��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!.ETWORK2EACHED%VENT�


connection4HIS�PARAMETER�SPECIFIES�THE�#ONNECTION�)$�FOR�THE�OUTBOUNDCONNECTION�ASSOCIATED�WITH�THE�TRUNK�AND�ITS�CONNECTION�TO�THENETWORK��SEE�FIGURE�BELOW�

trunkUsed4HIS�PARAMETER�SPECIFIES�THE�TRUNK�THAT�WAS�USED�TO�ESTABLISH�THE#ONNECTION�WITH�THE�TELEPHONE�NETWORK��)F�THE�DEVICE��I�E��THE�TRUNKIS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WASNOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

calledDevice4HIS�PARAMETER�INDICATES�THE�DESTINATION�DEVICE�FOR�THE�CALL��)F�THEDEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THE#ONNECTION�HAS�CUT THROUGH�INTO�THE�TELEPHONE�NETWORK��4HIS�COULDBE�NULL��INITIATED��ALERTING��CONNECTED��HELD��QUEUED��OR�FAILED�




Comments

/NCE�THIS�EVENT�OCCURS�THE�LEVEL�OF�CALL�RELATED�STATUS�INFORMATION�MAYDECREASE�DEPENDING�ON�THE�TYPE�OF�TRUNK�BEING�USED�TO�ROUTE�THE�CALLTO�IT�S�DESTINATION�ACROSS�THE�TELEPHONE�NETWORK��4HE�AMOUNT�OF�CALLRELATED�STATUS�INFORMATION�PROVIDED�BY�THE�NETWORK�WILL�DEPEND�ON�THETYPE�OF�TRUNK�AND�TELEPHONE�NETWORK�BEING�USED�TO�COMPLETE�THE�CALL�#ALL�STATUS�INFORMATION�MAY�BE�LIMITED�TO�THE�DISCONNECT�OR�DROPEVENT��4HIS�ONLY�APPLIES�FOR�CALLS�TO�OTHER�NETWORK�ENDPOINTS�AND�NOTTO�CALLS�WITHIN�THE�SWITCH�BEING�CONTROLLED�BY�THE�SERVER�

Figure 6-25Network Reached Event Report

D1 C1D1 D2 cC1c c D2TrunkTrunk

Switching Sub-Domain Boundary

Before After


#34!/RIGINATED%VENT

This event report informs the application that the switch is attempting toestablish a call as a result of a completed request from the application.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�$ATA�4YPES�AND�#34!�$ATA�4YPES�IN3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!/RIGINATED%VENT?T��ORGINATED�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T ORGINATED#ONNECTION�3UBJECT$EVICE)$?T CALLING$EVICE�#ALLED$EVICE)$?T CALLED$EVICE�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!/RGINATED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?/2').!4%$��WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!/RIGINATED%VENT�


originatedConnection4HIS�PARAMETER�IDENTIFIES�THE�#ONNECTION�WHERE�A�CALL�HAS�BEENORIGINATED�

callingDevice4HIS�PARAMETER�IDENTIFIES�THE�DEVICE�FROM�WHICH�THE�CALL�HAS�BEENORIGINATED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILLINDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

calledDevice4HIS�PARAMETER�IDENTIFIES�THE�DEVICE�FOR�WHICH�THE�ORIGINATED�CALL�ISINTENDED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILLINDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THE#ONNECTION�HAS�BEEN�ORIGINATED��4HIS�COULD�BE�NULL��INITIATED�ALERTING��CONNECTED��HELD��QUEUED��OR�FAILED�




Comments

4HIS�EVENT�INDICATES�THAT�A�CALL�IS�BEING�LAUNCHED�BY�THE�SWITCH�ONBEHALF�OF�THE�REQUEST�FROM�THE�APPLICATION��4HE�EVENT�ONLY�INDICATESTHAT�THE�SWITCH�IS�ATTEMPTING�TO�MAKE�THE�CALL��4HE�APPLICATION�SHOULDCHECK�FOR�ADDITIONAL�EVENTS�TO�DETERMINE�THE�STATUS�OF�THE�CALL�AS�ITPROCEEDS�EITHER�THROUGH�THE�SWITCH�OR�OUT�TO�THE�TELEPHONE�NETWORK�

Figure 6-26Originated Event Report

D1 D2C1D1 D2 c

Before After


#34!1UEUED%VENT

This event report indicates that a call has been queued to an ACD Split, a huntgroup, or others devices which support call queues. Call can also be queuedduring network re-routing without specifying a device.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!1UEUED%VENT?T��QUEUED�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T QUEUED#ONNECTION�3UBJECT$EVICE)$?T QUEUE�3UBJECT$EVICE)$?T CALLING$EVICE�#ALLED$EVICE)$?T CALLED$EVICE�2EDIRECTION$EVICE)$?T LAST2EDIRECTION$EVICE�INT NUMBER1UEUED�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!1UEUED%VENT?T�


Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?15%5%$��WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!1UEUED%VENT�


queuedConnection4HIS�INDICATES�THE�#ONNECTION�WAS�QUEUED�TO�THE�DEVICE�

queue4HIS�PARAMETER�SPECIFIES�THE�DEVICE�TO�WHICH�THE�CALL�HAS�BEENQUEUED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATETHAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

callingDevice4HIS�PARAMETER�INDICATES�THE�DEVICE�WHO�QUEUED�THE�CALL��)F�THE�DEVICEIS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WASNOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

calledDevice4HIS�PARAMETER�INDICATES�THE�DEVICE�WHICH�WAS�CALLED��THE�INTENDEDRECIPIENT�OF�THE�CALL��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETERWILL�INDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOTREQUIRED�


lastRedirectionDevice4HIS�PARAMETER�IDENTIFIES�THE�LAST�DEVICE�WHICH�REDIRECTED�THE�CALL��IFTHE�CALL�HAS�BEEN�REDIRECTED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THEPARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WASNOT�REQUIRED�

numberQueued4HIS�PARAMETER�INDICATES�HOW�MANY�CALLS�ARE�QUEUED�TO�THE�QUEUINGDEVICE�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THECALL�HAS�BEEN�QUEUED��4HIS�COULD�BE�NULL��INITIATED��ALERTING�CONNECTED��HELD��QUEUED��OR�FAILED�



Comments

4HIS�EVENT�USUALLY�OCCURS�WHEN�AN�APPLICATION�IS�MONITORING�A�CALL��A6ECTOR�$IRECTORY�.UMBER��6$.��AN�!#$�3PLIT��OR�A�HUNT�GROUP�4HE�EVENT�ALSO�PROVIDES�INFORMATION�PERTAINING�TO�THE�NUMBER�OF�CALLSTHAT�HAVE�BEEN�QUEUED�TO�A�DEVICE��4HIS�INFORMATION�CAN�BE�USEFUL�TOAPPLICATIONS�MANAGING�THE�QUEUE�AT�THE�DEVICE�


Figure 6-27Queued Event Report

D1 D2C1D1 D2 cC1c q

Before After

#34!2ETRIEVE%VENT

This event report identifies a call which was previously on hold and has beenretrieved at a device. This is equivalent to taking the call off the hold state andinto the active state.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!2ETRIEVED%VENT?T��RETRIEVED�]�U�



]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T RETRIEVED#ONNECTION�3UBJECT$EVICE)$?T RETRIEVING$EVICE�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!2ETRIEVED%VENT?T�

Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?2%42)%6%$��WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!2ETRIEVED%VENT�


retrievedConnection4HIS�PARAMETER�SPECIFIES�THE�#ONNECTION�FOR�WHICH�THE�CALL�HAS�BEENTAKEN�OFF�THE�HOLD�STATE�

retrievingDevice4HIS�SPECIFIES�THE�DEVICE�WHICH�DE ACTIVATED�THE�CALL�FROM�THE�HOLDSTATE�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THECALL�HAS�BEEN�RETRIEVED�FROM�THE�HOLD�STATE��4HIS�COULD�BE�NULL�INITIATED��ALERTING��CONNECTED��HELD��QUEUED��OR�FAILED�





Comments

4HIS�EVENT�INFORMS�THE�APPLICATION�THAT�A�CALL�IS�NO�LONGER�ON�HOLD�4HIS�CAN�OCCUR�IF�THE�END USER�PHYSICALLY�TAKES�THE�CALL�OFF�THE�HOLDSTATE�OR�IN�RESPONSE�TO�THE�CSTA2ETRIEVE#ALL��FUNCTION�REQUEST�

Figure 6-12Retrieved Event Report

D1 C1 D1 C1 D2D2 ch * *

Before After


#34!3ERVICE)NITIATED%VENT

This event report indicates to the application that telephony service wasinitiated at a device. The switch sends this event when it provides “dial tone”.Note that the user may be going off hook to invoke a feature using a featureaccess code, so call setup events do not necessarily follow.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�$ATA�4YPES�AND�#34!�$ATA�4YPES�IN3ECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[

!#3%VENT(EADER?T EVENT(EADER�UNION[��STRUCT��[��#34!-ONITOR#ROSS2EF)$?T MONITOR#ROSS2EF)$�

��UNION��[��#34!3ERVICE)NITIATED%VENT?T��SERVICE)NITIATED��]U��

��]�CSTA5NSOLICITED�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T INITIATED#ONNECTION�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!3ERVICE)NITIATED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?3%26)#%?).)4)!4%$��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!3ERVICE)NITIATED%VENT�


initiatedConnection4HIS�PARAMETER�INDICATES�THE�#ONNECTION�FOR�WHICH�SERVICE��DIAL�TONEHAS�BEEN�ESTABLISHED�OR�A�FEATURE�IS�INVOKED��4HE�SAME�#ONNECTIONIDENTIFIER�WILL�CONTINUE�TO�BE�USED�IF�A�CALL�IS�EVENTUALLY�ESTABLISHED�BYTHE�DEVICE�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THESERVICE�HAS�BEEN�INITIATED��4HIS�COULD�BE�NULL��INITIATED��ALERTING�CONNECTED��HELD��QUEUED��OR�FAILED�




Comments

#34! ��STATES�THAT�SWITCHES�ARE�NOT�REQUIRED�TO�SEND�THE�SERVICEINITIATED�EVENT�FOR�CALLS�THAT�ARE�ORIGINATED�FROM�FUNCTIONAL�TYPEDEVICES��E�G��)3$.�"2)�DEVICES�THAT�DO�EN�BLOC�DIALING�OR�FOR�CALLSTHAT�OTHER�APPLICATIONS�ORIGINATE�USING�CSTA-AKE#ALL��4HUS��SOME0"8�DRIVERS�MAY�NOT�PROVIDE�THIS�EVENT�IN�THESE�CIRCUMSTANCES�

Figure 6-13Service Initiated Event Report

D1 C1D1 i

Before After


#34!4RANSFERRED%VENT

This event report indicates that an existing call was transferred to anotherdevice and that the device which transferred the call is no longer part of thecall, i.e. the transferring device has dropped from the call.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��$ATA�4YPES�AND�#34!�$ATA�4YPES�INSECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!4RANSFER%VENT?T��TRANSFERRED�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T PRIMARY/LD#ALL�#ONNECTION)$?T SECONDARY/LD#ALL�3UBJECT$EVICE)$?T TRANSFERRING$EVICE�3UBJECT$EVICE)$?T TRANSFERRED$EVICE�#ONNECTION,IST?T TRANSFERRED#ONNECTIONS�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION)NFO�#34!%VENT#AUSE?T CAUSE�

]�#34!4RANSFERRED%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?42!.3&%22%$��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!4RANSFERRED%VENT�


primaryOldCall4HIS�PARAMETER�IDENTIFIES�THE�PRIMARY�KNOWN�CALL�THAT�WAS�TRANSFERRED�

secondaryOldCall4HIS�PARAMETER�IDENTIFIES�THE�SECONDARY�CALL�THAT�WAS�TRANSFERRED��4HISWOULD�IDENTIFY�THE�CONSULTATIVE�CALL�USED�TO�MAKE�THE�TRANSFER��AFTERTHE�PRIMARY�CALL�WAS�PLACED�ON�HOLD�

transferringDevice4HIS�INDICATES�WHICH�DEVICE�TRANSFERRED�THE�CALL��)F�THE�DEVICE�IS�NOTSPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOTKNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

transferredDevice4HIS�INDICATES�TO�WHICH�DEVICE�THE�CALL�WAS�TRANSFERRED��)F�THE�DEVICEIS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WASNOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

transferredConnections4HIS�IS�A�LIST�OF�CONNECTIONS��PARTIES�ON�THE�CALL�WHICH�RESULTED�FROMTHE�TRANSFER��4HE�CALL�)$�MAY�BE�DIFFERENT�FROM�EITHER�THE�PRIMARY�ORSECONDARY�OLD�CALL��OR�BOTH�

localConnectionInfo4HIS�PARAMETER�DEFINES�THE�LOCAL�CONNECTION�STATE�OF�THE�CALL�AFTER�THECALLS�HAVE�BEEN�TRANSFERRED�FROM�THE�DEVICE�WHICH�PERFORMED�THETRANSFER��4HIS�COULD�BE�NULL��INITIATED��ALERTING��CONNECTED��HELD�QUEUED��OR�FAILED�




Comments

4HIS�EVENT�PROVIDES�THE�APPLICATION�WITH�ALL�THE�INFORMATION�IT�NEEDSREGARDING�A�CALL�WHICH�WAS�TRANSFERRED�FROM�ONE�DEVICE�TO�ANOTHER�

Figure 6-14Transferred Event Report

D1 C1 D2

D3C2

D1 D2

D3c

h

C3

*

**

*

Before After


&EATURE�%VENT�2EPORTS��5NSOLICITED

TSAPI feature event reports indicate a change in the state of a specific featureoperating on a call or a device on the switch. Each feature event gives thecurrent state of the feature regardless of what the state of the feature wasbefore an application receives a feature event.


#34!#ALL)NFO%VENT

This event report is provided when a user account code feature has collecteddata for a party on the call. The event includes the account code andauthorization information which was collected by the switch feature.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��$ATA�4YPES�AND��#34!�$ATA�4YPES�INSECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!#ALL)NFO%VENT?T��CALL)NFORMATION�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ONNECTION)$?T CONNECTION�3UBJECT$EVICE)$?T DEVICE�!CCOUNT)NFO?T ACCOUNT)NFO�!UTH#ODE?T AUTHORISATION#ODE�

]�#34!#ALL)NFO%VENT?T�

TYPEDEF�CHAR��!CCOUNT)NFO?T;��=�

TYPEDEF�CHAR��!UTH#ODE?T;��=�


Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?#!,,?).&/2-!4)/.��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!#ALL)NFO%VENT�


connection4HIS�PARAMETER�IDENTIFIES�THE�PARTY�THAT�HAS�ENTERED�THE�ACCOUNT�CODE�

device)NDICATES�FROM�WHICH�DEVICE�WAS�THE�ACCOUNT�CODE�INFORMATIONENTERED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATETHAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

accountInfo3PECIFIES�THE�ACCOUNT�CODE�WHICH�WAS�ENTERED�AT�THE�DEVICE�

authorizationCode3PECIFIES�THE�AUTHORIZATION�CODE�WHICH�WAS�ENTERED�AT�THE�DEVICE�



Comments

4HIS�EVENT�INFORMS�THE�APPLICATION�WHEN�AN�ACCOUNT�CODE�FEATURE�HASBEEN�ACTIVATED�AND�WHAT�INFORMATION�WAS�COLLECTED�BY�THE�SWITCH�AS�ARESULT�OF�THE�FEATURE�BEING�ACTIVATED�


#34!$O.OT$ISTURB%VENT

This event report indicates a change in the status of the Do Not Disturb featurefor a specific device. The Do Not Disturb event will result in all calls to adevice to be automatically forwarded to the device coverage path.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[��#34!$O.OT$ISTURB%VENT?T��DO.OT$ISTURB�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

3UBJECT$EVICE)$?T DEVICE�"OOLEAN DO.OT$ISTURB/N�

]�#34!$O.OT$ISTURB%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?$/?./4?$)3452"��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!$O.OT$ISTURB%VENT�


device3PECIFIES�THE�DEVICE�FOR�WHICH�THE�$/�.OT�$ISTURB�FEATURE�HAS�BEENACTIVATED�DEACTIVATED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THEPARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WASNOT�REQUIRED�

doNotDisturbON3PECIFIES�WHETHER�THE�$/�.OT�$ISTURB�FEATURE�IS�ON��OR�OFF��



#34!&ORWARDING%VENT

This event report will indicate a change in the state of the Forwarding featurefor a specific device. The event will also indicate the type of forwarding beinginvoked when the feature is activated.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!&ORWARDING%VENT?T��FORWARDING�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

3UBJECT$EVICE)$?T DEVICE�&ORWARDING)NFO?T FORWARDING)NFORMATION�

]�#34!&ORWARDING%VENT?T�

TYPEDEF�ENUM�&ORWARDING4YPE?T�[&7$?)--%$)!4%��&7$?"539��&7$?./?!.3��&7$?"539?).4��&7$?"539?%84��&7$?./?!.3?).4��&7$?./?!.3?%84��

]�&ORWARDING4YPE?T�


TYPEDEF�STRUCT�&ORWARDING)NFO?T�[&ORWARDING4YPE?T� FORWARDING4YPE�"OOLEAN FORWARDING/N�$EVICE)$?T� � FORWARD$.� ��.5,,�FOR�NOT

PRESENT��]�&ORWARDING)NFO?T�

Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?&/27!2$).'�WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!&ORWARDING%VENT�


device3PECIFIES�THE�DEVICE�FOR�WHICH�THE�&ORWARDING�FEATURE�HAS�BEENACTIVATED�DEACTIVATED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THEPARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WASNOT�REQUIRED�

forwardingType3PECIFIES�THE�TYPE�OF�FORWARDING�BEING�INVOKED�FOR�THE�SPECIFICDEVICE��4HIS�MAY�INCLUDE�ONE�OF�THE�FOLLOWING�



.O�!NSWER &ORWARDING�AFTER�NOANSWER

"USY�)NTERNAL &ORWARDING�WHEN�BUSYFOR�AN�INTERNAL�CALL


"USY�%XTERNAL &ORWARDING�WHEN�BUSYFOR�AN�EXTERNAL�CALL

.O�!NSWER�)NTERNAL &ORWARDING�AFTER�NOANSWER�FOR�AN�INTERNAL�CALL

.O�!NSWER�%XTERNAL &ORWARDING�AFTER�NOANSWER�FOR�AN�EXTERNALCALL�

forwardingON3PECIFIES�WHETHER�THE�&ORWARD�FEATURE�IS�ON��OR�OFF��

forwardDN3PECIFIES�THE�DESTINATION�DEVICE�TO�WHICH�THE�CALLS�ARE�BEINGFORWARDED��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILLINDICATE�THAT�THE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�


Comments

4HE�APPLICATION�SHOULD�BE�AWARE�THAT�THE�FORWARDING)NFO�PARAMETERCAN�INDICATE�ANY�OF�THE�DEFINED�VALUES�DEPENDING�ON�THE�SWITCHIMPLEMENTATION�OF�THE�FORWARDING�FEATURE�


#34!-ESSAGE7AITING%VENT

This event report is used to indicate whether the Message Waiting feature hasbeen activated/deactivated.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[��#34!-ESSAGE7AITING%VENT?T��MESSAGE7AITING�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

#ALLED$EVICE)$?T DEVICE&OR-ESSAGE�3UBJECT$EVICE)$?T INVOKING$EVICE�"OOLEAN MESSAGE7AITING/N�

]�#34!-ESSAGE7AITING%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?-%33!'%?7!)4).'�WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!-ESSAGE7AITING%VENT�


deviceForMessage)NDICATES�THE�DEVICE�WHERE�THE�MESSAGE�IS�WAITING��I�E��ADDRESS�OFDEVICE�WHERE�THE�MESSAGE�WAITING�FEATURE�WAS�ACTIVATED��)F�THEDEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

invokingDevice3PECIFIES�WHICH�DEVICE�INVOKED�THE�MESSAGE�WAITING�FEATURE��I�E�ADDRESS�OF�THE�DEVICE�WHO�ACTIVATED�THE�MESSAGE�WAITING�FEATURE��)FTHE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

messageWaitingOn3PECIFIES�WHETHER�THE�-ESSAGE�7AITING�FEATURE�IS�ON��OR�OFF��


Comments

4HIS�EVENT�CAN�OCCUR�FOR�BOTH�A�DEVICE�OR�A�CALL�ASSOCIATION�


!GENT�3TATUS�%VENT�2EPORTS��5NSOLICITED

This section covers event reports which pertain to the use of ACD agentfeatures. The agent feature event reports indicate a change in the state of aspecific agent. Each event defines the current state of the agent featureregardless of the state of the feature before the event. Typically, applicationsin the call center or message center environment use agent status event reports.


#34!,OGGED/N%VENT

This event report informs the application that an agent has logged into a device(usually an ACD Split).

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!,OGGED/N%VENT?T��LOGGED/N�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

3UBJECT$EVICE)$?T AGENT$EVICE�!GENT)$?T AGENT)$�!GENT'ROUP?T AGENT'ROUP�!GENT0ASSWORD?T PASSWORD�

]�#34!,OGGED/N%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?,/''%$?/.�WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!,OGGED/N%VENT�


agentDevice3PECIFIES�THE�DEVICE�FROM�WHICH�THE�AGENT�IS�LOGGED�ON�TO�THE�SYSTEM�)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

agentID4HIS�PARAMETER�SPECIFIES�THE�AGENT�IDENTIFIER�OF�THE�AGENT�WHO�LOGGED�

INTO�THE�SYSTEM�

agentGroup3PECIFIES�THE�GROUP�OR�!#$�3PLIT�TO�WHICH�THE�AGENT�IS�LOGGING�INTO�

password4HIS�PARAMETER�SPECIFIES�THE�AGENT�S�PASSWORD�USED�TO�LOG�INTO�THESYSTEM�


Comments

)N�MOST�CASES��WHEN�AN�AGENT�LOGS�INTO�A�DEVICE�IT�USUALLY�MEANS�THATTHE�AGENT�IS�READY�TO�START�RECEIVING�CALLS�AT�THE�DEVICE��4HIS�MAY�NOTBE�TRUE�FOR�SOME�IMPLEMENTATIONS�


#34!,OGGED/FF%VENT

This event report indicates that an agent has logged out of the device/ACDSplit for which the agent had previously logged in and was providing service.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!,OGGED/FF%VENT?T��LOGGED/FF�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

3UBJECT$EVICE)$?T AGENT$EVICE�!GENT)$?T AGENT)$�!GENT'ROUP?T AGENT'ROUP�

]�#34!,OGGED/FF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?,/''%$?/&&�WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!,OGGED/FF%VENT�

agentDevice3PECIFIES�THE�DEVICE�FROM�WHICH�THE�AGENT�IS�LOGGED�OFF�THE�SYSTEM��)FTHE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

agentID4HIS�PARAMETER�SPECIFIES�THE�AGENT�IDENTIFIER�OF�THE�AGENT�WHO�LOGGED�

OFF�THE�SYSTEM�

agentGroup3PECIFIES�THE�GROUP�OR�!#$�3PLIT�FROM�WHICH�THE�AGENT�IS�LOGGINGOUT�



#34!.OT2EADY%VENT

This event report indicates that an agent is busy with tasks other than servicingan ACD call at the device. In most cases this will imply that the agent is notready to receive a call or that the agent is taking a break.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!.OT2EADY%VENT?T��NOT2EADY�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

3UBJECT$EVICE)$?T AGENT$EVICE�!GENT)$?T AGENT)$�

]�#34!.OT2EADY%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?./4?2%!$9�WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!.OT2EADY%VENT�

agentDevice3PECIFIES�THE�DEVICE�FROM�WHICH�THE�AGENT�IS�LOGGED�ON�TO�THE�SYSTEM�)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

agentID4HIS�PARAMETER�SPECIFIES�THE�IDENTIFIER�OF�THE�AGENT�WHO�IN�NOT�READYTO� RECEIVE�CALLS�



#34!2EADY%VENT

This event report indicates that an agent is ready to receive calls at the device.This event can occur even if the agent is busy on an active call at the device.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��$ATA�4YPES�AND��#34!�$ATA�4YPES�INSECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!2EADY%VENT?T��READY�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[


]�#34!2EADY%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?2%!$9�WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!2EADY%VENT�

agentDevice3PECIFIES�THE�DEVICE�WHICH�IS�READY�TO�RECEIVE�CALLS�FROM�THE�!#$��)FTHE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

agentID4HIS�PARAMETER�SPECIFIES�THE�IDENTIFIER�OF�THE�AGENT�WHO�IN�READY�TORECEIVE�CALLS�



#34!7ORK.OT2EADY%VENT

This event report indicates that the agent is in after call work mode completingthe tasks involved in servicing a call after the connection has beendisconnected. This will implies that the agents is no longer on the call but iscompleting the servicing of the last call and the agent should not receive anyadditional calls.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[��#34!7ORK.OT2EADY%VENT?T��WORK.OT2EADY�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[


]�#34!7ORK.OT2EADY%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?7/2+?./4?2%!$9�WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!7ORK.OT2EADY%VENT�

agentDevice3PECIFIES�THE�DEVICE�WHICH�HAS�INVOKED�THE�7ORK�.OT�2EADY�MODE��)FTHE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

agentID4HIS�PARAMETER�SPECIFIES�THE�IDENTIFIER�OF�THE�AGENT�WHO�IS�IN�THE7ORK�.OT�2EADY�MODE�


Comments

)N�THE�CASE�OF�THIS�EVENT�THE�AGENT�IS�STILL�WORKING�ON�COMPLETING�THEAFTER�CALL�WORK�FOR�THE�LAST�CALL��4HE�DIFFERENCE�BETWEEN�THIS�EVENT�ANDTHE�#34!7ORK2EADY%VENT�IS�THAT�THE�AGENT�HAS�INDICATED�THATHE�SHE�IS�NOT�READY�TO�RECEIVE�ADDITIONAL�CALLS�


#34!7ORK2EADY%VENT

This event report indicates that the agent is in "after call work mode"completing the tasks involved in servicing a call after the connection has beendisconnected. This implies that the agents is no longer on the call but iscompleting the servicing of the last call and the agent may receive anyadditional calls.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[



UNION[

#34!7ORK2EADY%VENT?T��WORK2EADY�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[


]�#34!7ORK2EADY%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?7/2+?2%!$9�WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!7ORK2EADY%VENT�

agentDevice3PECIFIES�THE�DEVICE�WHICH�HAS�INVOKED�THE�7ORK�2EADY�MODE��)F�THEDEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THEDEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

agentID4HIS�PARAMETER�SPECIFIES�THE�IDENTIFIER�OF�THE�AGENT�WHO�IS�IN�THE7ORK�2EADY�MODE�


Comments

)N�THE�CASE�OF�THIS�EVENT�THE�AGENT�IS�STILL�WORKING�ON�COMPLETING�THEAFTER�CALL�WORK�FOR�THE�LAST�CALL��4HE�DIFFERENCE�BETWEEN�THIS�EVENT�ANDTHE�#34!7ORK.OT2EADY%VENT�IS�THAT�THE�AGENT�HAS�INDICATED�THATHE�SHE�IS�READY�TO�RECEIVE�ADDITIONAL�CALLS�


%VENT�2EPORT�$ATA�4YPES��5NSOLICITED

This section defines the data structures associated with the CSTA EventReports defined in the Status Reporting Services section of this document.


#34!-ONITOR&ILTER?T

This structure is used to identify the event type filters requested or available ona monitored CSTA association.

TYPEDEF�UNSIGNED�SHORT��#34!#ALL&ILTER?T��DEFINE��#&?#!,,?#,%!2%$��X��DEFINE��#&?#/.&%2%.#%$��X��DEFINE��#&?#/..%#4)/.?#,%!2%$��X��DEFINE��#&?$%,)6%2%$��X��DEFINE��#&?$)6%24%$��X��DEFINE��#&?%34!",)3(%$��X��DEFINE��#&?&!),%$��X��DEFINE��#&?(%,$��X��DEFINE��#&?.%47/2+?2%!#(%$��X��DEFINE��#&?/2)').!4%$��X��DEFINE��#&?15%5%$��X��DEFINE��#&?2%42)%6%$��X��DEFINE��#&?3%26)#%?).)4)!4%$��X��DEFINE��#&?42!.3&%22%$��X��

TYPEDEF�UNSIGNED�CHAR��#34!&EATURE&ILTER?T��DEFINE��&&?#!,,?).&/2-!4)/.��X��DEFINE��&&?$/?./4?$)3452"��X��DEFINE��&&?&/27!2$).'��X��DEFINE��&&?-%33!'%?7!)4).'��X��

TYPEDEF�UNSIGNED�CHAR��#34!!GENT&ILTER?T��DEFINE��!&?,/''%$?/.��X��DEFINE��!&?,/''%$?/&&��X��DEFINE��!&?./4?2%!$9��X��DEFINE��!&?2%!$9��X��DEFINE��!&?7/2+?./4?2%!$9��X��DEFINE��!&?7/2+?2%!$9��X��

TYPEDEF�UNSIGNED�CHAR��#34!-AINTENANCE&ILTER?T��DEFINE��-&?"!#+?).?3%26)#%��X��DEFINE��-&?/54?/&?3%26)#%��X��

TYPEDEF�STRUCT�#34!-ONITOR&ILTER?T�[��#34!#ALL&ILTER?T�CALL��#34!&EATURE&ILTER?T�FEATURE��#34!!GENT&ILTER?T�AGENT��#34!-AINTENANCE&ILTER?T�MAINTENANCE��"OOLEAN��PRIVATE�]�#34!-ONITOR&ILTER?T�

CALL_FILTERS4HESE�VALUES�INDICATE�THAT�A�CALL�EVENT�FILTER�SHOULD�BE�USED�FORPROCESSING�EVENTS��4HE�PROVIDED�FILTER�MAY�BE�DIFFERENT�THAN�THE�ONEREQUESTED�


FEATURE_FILTERS4HESE�VALUES�INDICATE�THAT�A�FEATURE�EVENT�FILTER�SHOULD�BE�USED�FORPROCESSING�EVENTS��4HE�PROVIDED�FILTER�MAY�BE�DIFFERENT�THAN�THE�ONEREQUESTED�

AGENT_FILTERS4HESE�VALUES�INDICATE�THAT�A�AGENT�EVENT�FILTER�SHOULD�BE�USED�FORPROCESSING�EVENTS��4HE�PROVIDED�FILTER�MAY�BE�DIFFERENT�THAN�THE�ONEREQUESTED�

MAINTENANCE_FILTERS4HESE�VALUES�INDICATE�THAT�A�MAINTENANCE�EVENT�FILTER�SHOULD�BE�USEDFOR�PROCESSING�EVENTS��4HE�PROVIDED�FILTER�MAY�BE�DIFFERENT�THAN�THEONE�REQUESTED�

PRIVATE_FILTER4HIS�VALUE�INDICATES�THAT�A�PRIVATE�FILTER�SHOULD�BE�USED�FOR�PROCESSINGEVENTS��4HE�PROVIDED�FILTER�MAY�BE�DIFFERENT�THAN�THE�ONE�REQUESTED�


#34!%VENT#AUSE?T

This structure contains an enumerated list of all the possible event causeswhich can occur with different events. The definitions of these event causecodes are also provided.

TYPEDEF�ENUM�#34!%VENT#AUSE?T�[��%#?./.%�� %#?!#4)6%?-/.)4/2��%#?!,4%2.!4%��%#?"539��%#?#!,,?"!#+��%#?#!,,?#!.#%,,%$��%#?#!,,?&/27!2$?!,7!93��%#?#!,,?&/27!2$?"539��%#?#!,,?&/27!2$?./?!.37%2��%#?#!,,?&/27!2$��%#?#!,,?./4?!.37%2%$��%#?#!,,?0)#+50��%#?#!-0?/.��%#?$%34?./4?/"4!).!",%��%#?$/?./4?$)3452"��%#?).#/-0!4)",%?$%34).!4)/.��%#?).6!,)$?!##/5.4?#/$%��%#?+%9?#/.&%2%.#%��%#?,/#+/54��%#?-!).4%.!.#%��%#?.%47/2+?#/.'%34)/.��%#?.%47/2+?./4?/"4!).!",%��%#?.%7?#!,,��%#?./?!6!),!",%?!'%.43��%#?/6%22)$%��%#?0!2+��%#?/6%2&,/7��%#?2%#!,,��%#?2%$)2%#4%$��%#?2%/2$%2?4/.%��%#?2%3/52#%3?./4?!6!),!",%��%#?3),%.4?-/.)4/2��%#?42!.3&%2��%#?425.+3?"539��%#?6/)#%?5.)4?).)4)!4/2��]�#34!%VENT#AUSE?T�

Certain cause codes will appear in events only if they make sense. TheTable 6-1 gives cause code definitions. Table 6-2 illustrates which causecodes are possible for the each of the call events.


Table 6-1Cause Code Definitions

Cause Code Definition

Active Monitor an Active Monitor Feature has occurred. This feature typically allows intrusion bya supervisor into an agent call with the ability to speak and listen. The resultantcall can be considered as a conference so this cause code may be supplied withthe Conferenced Event Report.

Alternate the call is in the process of being exchanged. This feature is typically found onsingle-line telephones, where the human interface puts one call on hold andretrieves a held call or answers a waiting call in an atomic action.

Busy the call encountered a busy tone or device

Call Back Call Back is a feature invoked (by a user or via CSTA) in an attempt to complete acall that has encountered a busy or no answer condition. As a result of invokingthe feature, the failed call is cleared and the call can be considered as queued.The switch may subsequently automatically retry the call (normally when thecalled party next becomes free). Consequently, this cause code may appear inEvent Reports related to the feature invocation (Call Cleared, Connection Clearedand Queued) or related to the subsequent, retried call (Service Initiated,Originated, Delivered, and Established).

Call Canceled the user has terminated a call without going on-hook.

Call Forward the call has been redirected via a Call Forwarding feature set for general,unknown, or multiple conditions.

Call Fd. - Immediate the call has been redirected via a Call Forwarding feature set for all conditions.

Call Fd. - Busy the call has been redirected via a Call Forwarding feature set for a busy endpoint.

Call Fd. - No Answer the call has been redirected via a Call Forwarding feature set for an endpoint thatdoes not answer.

Call Not Answered the call was not answered because a timer has elapsed.

Call Pickup the call has been redirected via a Call Pickup feature.

Camp On a Camp On feature has been invoked or has matured.


Dest. Not Obtainable the call could not obtain the destination.

Do Not Disturb the call encountered a Do Not Disturb condition.


Table 6-1 continuedCause Code Definitions


Incompatible Destination the call encountered an incompatible destination.

Invalid Account Code the call has an invalid account code.

Key Operation1 indicates that the Event Report occurred at a bridged or twin device.

Lockout the call encountered inter-digit time-out while dialing.

Maintenance the call encountered a facility or endpoint in a maintenance condition.

Net Congestion the call encountered a congested network. In some circumstances this causecode indicates that the user is listening to a "No Circuit" Special Information Tone(SIT) from a network that is accompanied by a statement similar to "All circuits arebusy..."

Net Not Obtainable the call could not reach a destination network.

Resources not Available resources were not available

Silent Monitor the event was caused by the invocation of a feature that allows a third party, suchas an ACD agent supervisor, to join the call. The joining party can hear the entireconversation, but cannot be heard by either original party. The feature,sometimes called silent intrusion, may provide a tone to one or both parties toindicate that they are being monitored. This feature is not the same as a CSTAMonitor request. This cause shall not indicate that a CSTA Monitor has beeninitiated.

Transfer a Transfer is in progress or has occurred

Trunks Busy the call encountered Trunks Busy

��4ELEPHONE�NUMBERS�ASSOCIATED�PRIMARILY�WITH�ONE�DEVICE�OFTENAPPEAR�ALSO�ON�A�SECOND�DEVICE��/NE�EXAMPLE�IS�A�SECRETARYWHO�S�PHONE�HAS�MIRRORED�OR�BRIDGED�LINES�OF�A�BOSS�S�PHONE�


Voice Unit Initiator indicates that the event was the result of action by automated equipment (voicemail device, voice response unit, announcement) rather than the result of actionby a human user.


Table 6-2CSTA Event Report - Cause Relationships

Cause Call

Clr.

Conf Con.

Clr.

Dlv. Div. Est. Fail Held Net.

Rch.

Orig

.

Q-ed Retr. Svc.

Init.

Tran

Active Monitor y

Alternate y y y y

Busy y y

Call Back y y y y y y

Call Canceled y y y y

Call Forward y y y y y y

Call Fd. -Immediate

y y y y y

Call Fd. - Busy y y y y y

Call Fd. - NoAnswer

y y y y y y

Call Not Answered y y y y

Call Pickup y y

Camp On y y y

Dest. notObtainable

y y y

Do Not Disturb y y y y

Incpt. Destination y y y y

Invalid AccountCode

y y


Key Operation y y y y y y y y y y y y y y

Lockout y


Table 6-2 continuedCSTA Event Report - Cause Relationships

Cause Call

Clr.

Conf Con.

Clr.

Dlv. Div. Est. Fail Held Net.

Rch.

Orig

.

Q-ed Retr. Svc.

Init.

Tran

Maintenance y y

Net Congestion y y

Net Not Obtainable y y

New Call y y y y y

No AvailableAgents

y y y y

Overflow y y y y y y y

Override y y y y y y y y

Park y y

Recall y y y y y y y y y

Redirected y y y y y y

Reorder Tone y

Resrcs. notAvailable

y y y y y

Silent Monitor y y

Transfer y y y y y y y y

Trunks Busy y y

Voice Unit Initiator y y


C h a p t e r 7 Snapshot Services

An application uses CSTA Snapshot Services to query the current state of aCSTA Call or a Device object. Snapshot services query the switch to providean application with information about the object. The information is a "snap-shot" since the state of the Call or Device object changes over time.

The Call Snapshot Services return a list of the Devices and Connections asso-ciated with a given Call, and the Connection States for each of those Devices.As Figure 7-1 illustrates, the union of the Connection States for the Calldefines the overall Call State. Also refer to the definition of Call State inChapter 3.

Figure 7-1 shows a Call that has four associated devices. Recall from Chap-ter 3 that the relationship between a CSTA Call and a CSTA Device is aCSTA Connection (C1, C2, C3, and C4 are Connections). Each Connectionhas an associated Connection State. The Call Snapshot Services inform anapplication of each Device that is on a given Call and the associatedConnection State for those Devices. The Call State is the union of all theConnection States associated with the Call. The application can use snapshotinformation to control Connections. For example, if Figure 7-1 shows a four-party conference call, then an application can use the Call Snapshot Servicestogether with the cstaClearConnection( ) service to disconnect any partyfrom the conference. To disconnect connection C4, an application uses theCall Snapshot Services to obtain a Connection Identifier (for C4) that it thenpasses to the cstaClearConnection( ) service.


Figure 7-15Call Snapshot Service

$EVICE��

$EVICE�� $EVICE��

$EVICE��#ALL

#ALL�3TATE��

#� #�

#�#�

#� #� #� #�

#ONNECTION�3TATE

Device Snapshot Services return information about Calls that are associatedwith a given CSTA Device object. The information includes a list of Calls as-sociated with the given Device and the Connection State of each Call (at thatDevice). Note the duality here: Call Snapshot Services return informationabout Connections at all Devices associated with a given Call, while DeviceSnapshot Services return information about all Connections at a given Device.Applications use the Device Snapshot Services when they need to know whatis happening at a specific Device. As Figure 7-2 shows, Device SnapshotServices do not provide information about the other parties on those Calls con-nected to the given Device.

An application can use Device Snapshot information to manipulate any Con-nection, (C1, C2, or C3 in Figure 7-2) at the given Device.


Figure 7-16Device Snapshot Service

#ALL��

#ALL��

#ALL��

$EVICE�3TATE��

#�

#�

#�

$EVICE

#� #� #�

#ONNECTION�3TATE

Before an application requests the Call or Device Snapshot Services, it musthave previously obtained a Call or Device identifier (that it will use as aparameter to request those services). The identifier specifies a Call or Devicein the switching domain. Depending on the implementation, SnapshotServices may not provide information about devices or connections outside ofthat switching domain (devices not attached to that switch) .

.OTE


#ALL�3NAPSHOT�3ERVICES

This section defines the Call Snapshot Services that query the switch for thestatus of calls within the switching domain. Call Snapshot Services return in-formation about all Devices and Connections associated with a specifiedCSTA Call object.


CSTA3NAPSHOT#ALL2EQ��

The cstaSnapshotCallReq( ) service provides information about a Call objectin the switching domain. The service will return the Devices associated with agiven Call and the Connection State for each Device. The Call State is theunion of the Connection States.

Syntax


2ET#ODE?T��CSTA3NAPSHOT#ALL2EQ��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#ONNECTION)$?T SNAPSHOT/BJ�0RIVATE$ATA?T PRIVATE$ATA�

Parameters

acsHandle4HIS�IS�THE�HANDLE�TO�AN�ACTIVE�!#3�3TREAM�OVER�WHICH�THE�REQUESTWILL�BE�MADE�

invokeID4HIS�IS�AN�APPLICATION�PROVIDED�HANDLE�THAT�THE�APPLICATION�USES�TOMATCH�A�SPECIFIC�INSTANCE�OF�A�SERVICE�REQUEST�WITH�ITS�CONFIRMATIONEVENT��4HE�APPLICATION�SUPPLIES�THIS�PARAMETER�ONLY�WHEN�THE�)NVOKE)$�MECHANISM�IS�SET�FOR�!PPLICATION GENERATED�)$S�IN�ACS/PEN 3TREAM��4HE�!#3�,IBRARY�IGNORES�THIS�PARAMETER�WHEN�THE�3TREAMIS�SET�FOR�,IBRARY GENERATED�INVOKE�)$S�

snapshotObj4HIS�IS�A�POINTER�TO�THE�#ONNECTION�)DENTIFIER�IDENTIFYING�THE�#ALL�OB JECT�FOR�WHICH�3NAPSHOT�INFORMATION�IS�REQUESTED�

privateData4HIS�IS�AN�OPTIONAL�POINTER�TO�#34!�PRIVATE�DATA�

Return Values

CSTA3NAPSHOT#ALL2EQ��RETURNS�THE�FOLLOWING�VALUES�DEPENDING�ONWHETHER�THE�APPLICATION�IS�USING�LIBRARY�OR�APPLICATION GENERATED�IN VOKE�IDENTIFIERS�


,IBRARY GENERATED�)DENTIFIERS� �IF�THE�FUNCTION�CALL�COMPLETESSUCCESSFULLY�IT�WILL�RETURN�A�POSITIVE�VALUE��THE�INVOKEIDENTIFIER��)F�THE�CALL�FAILS�IT�WILL�RETURN�A�NEGATIVE�ERROR��&OR�LIBRARY GENERATED�IDENTIFIERS�THE�RETURN�WILL�NEVER�BEZERO��

!PPLICATION GENERATED�)DENTIFIERS� �IF�THE�FUNCTION�CALLCOMPLETES�SUCCESSFULLY�IT�WILL�RETURN�A�ZERO��VALUE��)F�THECALL�FAILS�IT�WILL�RETURN�A�NEGATIVE�ERROR��&OR�APPLICATION GENERATED�IDENTIFIERS�THE�RETURN�IS�NEVER�POSITIVE��

!N�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!3NAPSHOT#ALL#ONF% VENT�MESSAGE�TO�INSURE�THAT�THE�4ELEPHONY�3ERVER�AND�SWITCH�HAVE�AC KNOWLEDGED�AND�PROCESSED�THE�CSTA3NAPSHOT#ALL2EQ��REQUEST�


!#3%22?"!$($,4HE�APPLICATION�PROVIDED�A�BAD�OR�UNKNOWN�ACS(ANDLE�

!#3%22?342%!-?&!),%$!�PREVIOUSLY�ACTIVE�!#3�3TREAM�HAS�BEEN�ABNORMALLYABORTED�

Comments

!�CALL�TO�CSTA3NAPSHOT#ALL2EQ��RESULTS�IN�A�CONFIRMATION�EVENT�#34!3NAPSHOT#ALL#ONF%VENT� �THAT�RETURNS�THE�INFORMATION�ABOUTTHE�CALL��CSTA3NAPSHOT#ALL2EQ��PROVIDES�INFORMATION�ABOUT�CALLSTHAT�MAKE�FURTHER�MONITORING�MEANINGFUL��&OR�EXAMPLE��WHEN�ANAPPLICATION�REQUESTS�CSTA-ONITOR3TART ��THERE�MAY�ALREADY�BEACTIVE�CALLS�AT�THE�$EVICE�BEING�MONITORED��4HE�APPLICATION�CAN�USE#ALL�3NAPSHOT�INFORMATION�TO�OBTAIN�INFORMATION�ABOUT�THOSE�EXISTINGCALLS�PROCESS�ADDITIONAL�EVENTS�ABOUT�THEM�IN�A�REASONABLE�WAY�

CSTA3NAPSHOT#ALL2EQ��IS�PASSIVE�AND�DOES�NOT�AFFECT�THE�STATE�OFANY�OBJECT�IN�THE�SWITCHING�DOMAIN�


#34!3NAPSHOT#ALL#ONF%VENT

The Call Snapshot confirmation event returns call related information inresponse to the cstaSnapshotCallReq( ) service. The call informationincludes the static Device Identifiers, the Connection Identifiers, andConnection States for every endpoint in the specified call.

Syntax


TYPEDEF�STRUCT[!#3(ANDLE?T ACS(ANDLE�%VENT#LASS?T EVENT#LASS�

%VENT4YPE?T EVENT4YPE�]�!#3%VENT(EADER?T�


TYPEDEF�STRUCT[


STRUCT[


#34!3NAPSHOT#ALL#ONF%VENT?TSNAPSHOT#ALL�

]�U�]�CSTA#ONFIRMATION


TYPEDEF�STRUCT�#34!3NAPSHOT#ALL#ONF%VENT?T�[#34!3NAPSHOT#ALL$ATA?T�SNAPSHOT$ATA�

]�#34!3NAPSHOT#ALL#ONF%VENT?T�

TYPEDEF�STRUCT�#34!3NAPSHOT#ALL$ATA?T�[INT COUNT�STRUCT #34!3NAPSHOT#ALL2ESPONSE)NFO?T�INFO�

]�#34!3NAPSHOT#ALL$ATA?T�

TYPEDEF�STRUCT�#34!3NAPSHOT#ALL2ESPONSE)NFO?T�[3UBJECT$EVICE)$?T DEVICE/N#ALL�#ONNECTION)$?T CALL)DENTIFIER�,OCAL#ONNECTION3TATE?T LOCAL#ONNECTION3TATE�

]�#34!3NAPSHOT#ALL2ESPONSE)NFO%VENT?T�

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�!#3�3TREAM�OVER�WHICH�THE�CONFIRMATIONARRIVED��4HIS�IS�THE�SAME�AS�THE�!#3�3TREAM�OVER�WHICH�THE�REQUESTWAS�MADE�

eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICH�IDENTI FIES�THIS�MESSAGE�AS�AN�#34!�CONFIRMATION�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?3.!03(/4?#!,,?#/.&�WHICH�IDENTIFIES��THIS�MESSAGE�AS�AN�#34!3NAPSHOT#ALL#ONF%VENT�


invokeID4HIS�PARAMETER�SPECIFIES�THE�SERVICE�REQUEST�INSTANCE�FOR�THECSTA3NAPSHOT#ALL2EQ��4HE�APPLICATION�USES�THIS�PARAMETER�TOCORRELATE�RESPONSES�WITH�REQUESTS�

snapshotData#ONTAINS�ALL�THE�SNAPSHOT�INFORMATION�FOR�THE�#ALL�FOR�WHICH�THE�QUERYWAS�MADE�

COUNT��!�COUNT�OF�THE�NUMBER�OF#34!3NAPSHOT#ALL2ESPONSE)NFO?T�STRUCTURES��%ACHSTRUCTURE�CONTAINS�INFORMATION�ABOUT�ONE�DEVICE�ON�THE�CALL�

INFO��!�POINTER�TO�AN�ARRAY�OF#34!3NAPSHOT#ALL2ESPONSE)NFO?T�STRUCTURES��EACH�OF�WHICHCONTAINS�THE�FOLLOWING�FIELDS�

DEVICE/N#ALL� �!�POINTER�TO�THE�$EVICE�)DENTIFIEROF�A�DEVICE�THAT�IS�A�PARTY�ON�THE�CALL�FOR�WHICH�THEQUERY�WAS�MADE�

CALL)DENTIFIER� �4HE�#ONNECTION�)DENTIFIER�FOR�THE#ONNECTION��BETWEEN�THE�DEVICE/N#ALL�AND�THE�CALLFOR�WHICH�THE�QUERY�WAS�MADE�

LOCAL#ONNECTION3TATE � �4HE�#ONNECTION�3TATE�FORTHE�LOCAL�#ONNECTION�IN�THE�CALL)DENTIFIER�PARAMETER�

privateData)F�PRIVATE�DATA�ACCOMPANIES�THIS�EVENT��THEN�THE�PRIVATE�DATA�WOULD�BESTORED�IN�THE�LOCATION�THAT�THE�APPLICATION�SPECIFIED�AS�THE�PRIVATE$ATAPARAMETER�IN�THE�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��REQUEST��)F�THE�PRIVATE$ATA�POINTER�IS�SET�TO�.5,,�IN�THESE�REQUESTS�THEN�#34!3NAPSHOT#ALL#ONF%VENT�DOES�NOT�DELIVER�PRIVATE�DATA�TOTHE�APPLICATION�

Comments

4HE�#34!3NAPSHOT#ALL#ONF%VENT �RETURNS�AN�ARRAY�OR�VARIABLELENGTH�SINCE�THE�NUMBER�OF�DEVICES�ON�A�CALL�CAN�BE�GREATER�THAN�ONE�%ACH�ARRAY�ELEMENT�IDENTIFIES�A�$EVICE�ON�THE�CALL��THE�#ONNECTIONBETWEEN�THE�$EVICE�AND�THE�#ALL��AND�THE�#ONNECTION�3TATE��SEE&IGURE�� !N�APPLICATION�SHOULD�USE�COUNT�TO�DETERMINE�THENUMBER�OF�ARRAY�ELEMENTS�


$EVICE�3NAPSHOT�3ERVICE

This section defines the Device Snapshot Services that query the switch for thestatus of Devices within the switching domain. Device Snapshot Services re-turn information about Calls (Connections) associated with a specified Device.


CSTA3NAPSHOT$EVICE2EQ��

The cstaSnapshotDeviceReq( ) service returns information about a Deviceobject in the switching domain. The service returns a list of calls associatedwith the given Device and the Connection State of each of those calls at thatDevice.

Syntax


2ET#ODE?T��CSTA3NAPSHOT$EVICE2EQ��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T SNAPSHOT/BJ�0RIVATE$ATA?T PRIVATE$ATA�

Parameters

acsHandle4HIS�IS�THE�HANDLE�TO�AN�ACTIVE�!#3�3TREAM�OVER�WHICH�THE�REQUESTWILL�BE�MADE�

invokeID4HIS�IS�AN�APPLICATION�PROVIDED�HANDLE�THAT�THE�APPLICATION�USES�TOMATCH�A�SPECIFIC�INSTANCE�OF�A�SERVICE�REQUEST�WITH�ITS�CONFIRMATIONEVENT��4HE�APPLICATION�SUPPLIES�THIS�PARAMETER�ONLY�WHEN�THE�)NVOKE)$�MECHANISM�IS�SET�FOR�!PPLICATION GENERATED�)$S�IN�ACS/PEN 3TREAM��4HE�!#3�,IBRARY�IGNORES�THIS�PARAMETER�WHEN�THE�3TREAMIS�SET�FOR�,IBRARY GENERATED�INVOKE�)$S�

snapshotObj4HIS�PARAMETER�IS�A�POINTER�TO�THE�$EVICE�)DENTIFIER�FOR�THE�$EVICE�OB JECT�FOR�WHICH�3NAPSHOT�INFORMATION�IS�BEING�REQUESTED�


Return Values





4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!3NAPSHOT$EVICE#ONF%VENT�MESSAGE�TO�INSURE�THAT�THE4ELEPHONY�3ERVER�AND�THE�SWITCH�HAVE�ACKNOWLEDGED�AND�PROCESSEDTHE�CSTA3NAPSHOT$EVICE2EQ��REQUEST�




Comments

!�CALL�TO�CSTA3NAPSHOT$EVICE2EQ��RESULTS�IN�A�CONFIRMATION�EVENT�#34!3NAPSHOT$EVICE#ONF%VENT ��WHICH�RETURNS�INFORMATION�ABOUTTHE�$EVICE��CSTA3NAPSHOT$EVICE2EQ��PROVIDES�INFORMATION�ABOUT$EVICES�THAT�PERMIT�AN�APPLICATION�TO�SYNCHRONIZE�STATE�WITH�THESWITCHING�DOMAIN��&OR�EXAMPLE��AN�APPLICATION�CAN�CALL�CSTA3NAP SHOT$EVICE2EQ��TO�FIND�OUT�ABOUT�THE�#ALLS�PRESENT�AT�A�$EVICE�THEN�CALL�CSTA-ONITOR3TART ��TO�MONITOR�THE�$EVICE��4HEINFORMATION�FROM�THE�$EVICE�QUERY�PERMITS�THE�APPLICATION�TO�PROCESSTHE�MONITORING�EVENTS�IN�A�PROPER�CONTEXT�

4HE�CSTA3NAPSHOT$EVICE2EQ��IS�PASSIVE�AND�DOES�NOT�AFFECT�THESTATE�OF�ANY�OBJECT�WITHIN�THE�SWITCHING�DOMAIN�


#34!3NAPSHOT$EVICE#ONF%VENT

The Device Snapshot confirmation event returns Device related information inresponse to the cstaSnapshotDeviceReq( ) service. The Device informationincludes a Connection Identifier for each Call at the Device and theConnection State for each Call at the Device.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE��!#3�$ATA�4YPES�AND��#34!�$ATA4YPES�IN�SECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!3NAPSHOT$EVICE#ONF%VENT?TSNAPSHOT$EVICE�



TYPEDEF�STRUCT�#34!3NAPSHOT$EVICE#ONF%VENT?T�[#34!3NAPSHOT$EVICE$ATA?T�SNAPSHOT$ATA�

]�#34!3NAPSHOT$EVICE#ONF%VENT?T�

TYPEDEF�STRUCT�#34!3NAPSHOT$EVICE$ATA?T�[INT COUNT�STRUCT #34!3NAPSHOT$EVICE2ESPONSE)NFO?T�INFO�

]�#34!3NAPSHOT$EVICE$ATA?T�

TYPEDEF�STRUCT�#34!3NAPSHOT$EVICE2ESPONSE)NFO?T�[#ONNECTION)$?T CALL)DENTIFIER�#34!#ALL3TATE?T LOCALCALL3TATE�

]�#34!3NAPSHOT$EVICE2ESPONSE)NFO?T�

Telephony Services API 7-14

typedef struct CSTASnapshotDeviceResponseInfo_t {ConnectionID_t callIdentifier;CSTACallState_t localcallState;

} CSTASnapshotDeviceResponseInfo_t;

typedef struct CSTACallState_t {int

count;LocalConnectionState_t *state;

} CSTACallState_t;

typedef enum CSTASimpleCallState_t {CALL_NULL = 0,CALL_PENDING = 1,CALL_ORIGINATED = 3,CALL_DELIVERED = 35,CALL_DELIVERED_HELD = 36,CALL_RECEIVED = 50,CALL_ESTABLISHED = 51,CALL_ESTABLISHED_HELD = 52,CALL_RECEIVED_ON_HOLD = 66,CALL_ESTABLISHED_ON_HOLD = 67,CALL_QUEUED = 83,CALL_QUEUED_HELD = 84,CALL_FAILED = 99,CALL_FAILED_HELD = 100

} CSTASimpleCallState_t;

/* * */#define SIMPLE_CALL_STATE(ccs) (ccs.stat[0]+(ccs.state[1] << 4))

typedef struct CSTACallState_t {int

count;LocalConnectionState_t *state;

} CSTACallState_t;

Parameters

acsHandleThis is the handle for the ACS Stream over which the confirmationarrived. This is the same as the ACS Stream over which the requestwas made.

eventClassThis is a tag with the value CSTACONFIRMATION, which identi-fies this message as an CSTA confirmation event.


invokeID4HIS�PARAMETER�SPECIFIES�THE�SERVICE�REQUEST�INSTANCE�FOR�THECSTA3NAPSHOT$EVICE2EQ��4HE�APPLICATION�USES�THIS�PARAMETER�TOCORRELATE�RESPONSES�WITH�REQUESTS�

snapshotData#ONTAINS�ALL�THE�SNAPSHOT�INFORMATION�FOR�THE�$EVICE�FOR�WHICH�THEQUERY�WAS�MADE�

COUNT��!�COUNT�OF�THE�NUMBER�OF#34!3NAPSHOT$EVICE2ESPONSE)NFO?T�STRUCTURES��%ACHCONTAINS�INFORMATION�ABOUT�ONE�#ALL�AT�THE�$EVICE�

INFO��!�POINTER�TO�AN�ARRAY�OF#34!3NAPSHOT$EVICE2ESPONSE)NFO?T�STRUCTURES��EACH�OFWHICH�CONTAINS�THE�FOLLOWING�FIELDS�

CALL)DENTIFIER� �!�POINTER�TO�A�#ONNECTION)DENTIFIER�FOR�EACH�CALL�AT�THE�DEVICE��&OR�SOMEIMPLEMENTATIONS��THIS�PARAMETER�POINTS�TO�THEDEVICE�S�DYNAMIC�DEVICE�IDENTIFIER�FOR�THE�CALLOBJECT�

CALL3TATE� �4HE�#34!�#ALL�3TATE��4HE�#ALL�3TATEIS�RETURNED�AS�A�LIST�OF�LOCAL�#ALL�3TATES�

privateData)F�PRIVATE�DATA�ACCOMPANIES�THIS�EVENT��THEN�THE�PRIVATE�DATA�WOULD�BESTORED�IN�THE�LOCATION�THAT�THE�APPLICATION�SPECIFIED�AS�THE�PRIVATE$ATAPARAMETER�IN�THE�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��REQUEST��)F�THE�PRIVATE$ATA�POINTER�IS�SET�TO�.5,,�IN�THESE�REQUESTS�THEN�#34!3NAPSHOT$EVICE#ONF%VENT�DOES�NOT�DELIVER�PRIVATE�DATATO�THE�APPLICATION�

Comments

4HE�#34!3NAPSHOT$EVICE#ONF%VENT �RETURNS�A�LINKED�LIST�SINCE�THENUMBER�OF�CALLS�ON�A�DEVICE�CAN�BE�GREATER�THAN�ONE��%ACH�MEMBER�OFTHE�LIST�IDENTIFIES�A�CALL�AT�THE�DEVICE��AND�THE�LOCAL�CALL�STATE�OF�THE#ONNECTION�FOR�THAT�CALL�AT�THE�DEVICE��SEE�&IGURE�� !NAPPLICATION�SHOULD�BE�AWARE�THAT�THE�NUMBER�OF�MEMBERS�ON�THE�LIST�ISNOT�FIXED��4HE�POINTER��NEXT��WILL�BE�.5,,�FOR�THE�LAST�MEMBER�CALL�ON�THE�LIST�



C h a p t e r 8 CSTA Computing Function Services

CSTA Computing Functions are those functions where the switching domainis the client (service requester) and the computing domain is the server.Presently, Application Call Routing is the only CSTA Computing Function. Aswitch uses application call routing when it needs the application to supply calldestinations on a call-by-call basis. Applications can use internal databasestogether with call information to determine a destination for each call. ForExample, an application might use the caller’s number, caller-entered digits(provided as private data), or information in an application database to routeincoming calls.

43!0)�6ERSION��2OUTING

TSAPI Version 2 more closely aligns with the CSTA standard. Version 2adds two new TSAPI functions and provides additional information in twoevent reports. The new function calls are cstaRouteSelectInv( ) andcstaRouteEndInv( ), and the two enhanced events areCSTARouteRequestEvent and CSTARouteUsedEvent.

The new functions, cstaRouteSelectInv( ) and cstaRouteEndInv( ), allow anapplication to supply an invoke identifier (invokeID) in these requests.Although TSAPI does not define a confirmation event for these services, theCSTA standard does define a negative acknowledgement. By using theVersion 2 functions, the application can associate a potentialCSTAUniversalFailureConfEvent with the original request. This is not


possible with the Version 1 APIs because they did not include an invokeIDparameter (a PBX Driver may instead send a CSTARouteEndEvent toindicate an error, but doing so is not strictly in compliance with the CSTAstandard).

The enhancements in the routing event reports, CSTARouteRequestEventand CSTARouteUsedEvent allow inclusion of ExtendedDeviceID_t typefields for certain event data instead of the currently defined DeviceID_t types.In version 2, the currentRoute and callingDevice members ofCSTARouteRequestExtEvent are defined as CalledDeviceID_t andCallingDeviceID_t types, respectively. The routeUsed and callingDevicemembers of CSTARouteUsedEvent are defined as CalledDeviceID_t andCallingDeviceID_t types, respectively. The version 2 definitions align withthe CSTA standard. Note that a routing server application that requests andgets the TSAPI version 2 (i.e., "TS2") will always receive the version 2events. Existing applications that do not use version control to request theVersion 2 API version will continue to receive the Version 1 events.


!PPLICATION�#ALL�2OUTING

Application call routing requires that the switch be configured to direct calls toa special type of device know as the "routing device". When a call arrives at arouting device, the switch sends a message to the Telephony Server requestinga route for the call.

Before an application can route calls, it must register with the TelephonyServer as a routing server. The application may either register as the routingserver for a specific routing device or as the default routing server for anadvertised service. Recall that a PBX driver advertises its services. Oftenthese services correspond to a CTI link, so an application can, in effect,register to be the default routing server for a CTI link. An application usescstaRouteRegisterReq( ) to register as a routing server. This request has anassociated confirmation event, CSTARouteRegisterReqConfEvent, thatcontains the routing cross-reference identifier (routingCrossRefID) that theapplication uses to identify requests that arrive on this registration.

At any one time, one, and only one application can be the routing server for arouting device. Similarly, one, and only one application can be the defaultrouting server for an advertised service.

2OUTING�0ROCEDURE

The registration above must occur before this procedure can take place. Thisprocedure description uses the version 2 functions.

�� 4HE�SWITCH�QUEUES�AN�INCOMING�CALL�AT�A�SPECIAL�DEVICEOBJECT��THE�ROUTING�DEVICE��4HE�ROUTING�DEVICE�MAY�BE�A��SOFT�EXTENSION�ON�THE�SWITCH�FOR�APPLICATION BASED�ROUTING��OR�SIMILARDEVICE�DEFINED�WITHIN�THE�SWITCHING�DOMAIN�

�� 7HEN�THE�CALL�ARRIVES�AT�THE�ROUTING�DEVICE��THE�SWITCH�ANDTHE�4ELEPHONY�3ERVICES�0"8�DRIVER�CREATE�A�#34!�ROUTING�DIALOG

.OTE

123


FOR�THE�CALL��4HE�0"8�DRIVER�ALLOCATES�A�ROUTING�CROSS REFERENCEIDENTIFIER��ROUTING#ROSS2EF)$�THAT�REFERENCES�THIS�ROUTING�DIALOG�

�� 4HE�0"8�$RIVER�DIRECTS�THE�ROUTE�REQUEST�TO�THE�APPLICATIONREGISTERED�AS�THE�ROUTING�SERVER�FOR�THE�ROUTING�DEVICE��)F�NOAPPLICATION�IS�REGISTERED�FOR�THAT�SPECIFIC�ROUTING�DEVICE��THEN�THE0"8�$RIVER�DIRECTS�THE�ROUTE�REQUEST�TO�THE�DEFAULT�ROUTING�SERVERAPPLICATION�FOR�ITS�ADVERTISED�SERVICE��4HE�ROUTING�APPLICATIONRECEIVES�AN�UNSOLICITED�ROUTE�REQUEST�EVENT�#34!2OUTE2EQUEST%VENT�FOR�THE�CALL��4HIS�EVENT�CONTAINS�THEROUTING�CROSS REFERENCE�IDENTIFIER�AND�CALL�INFORMATION��SUCH�ASCALLING�AND�CALLED�NUMBERS��4HE�APPLICATION�WHICH�PROVIDES�THECALL�ROUTING�DESTINATION�IS�CALLED�THE��ROUTING�SERVER��FOR�THEROUTING�DEVICE�

�� THE�ROUTING�SERVER�SENDS�THE�SWITCH�A�ROUTE�SELECTMESSAGE��CSTA2OUTE3ELECT)NV�CONTAINING�A�DESTINATION�FOR�THE�CALL�4HE�ROUTING�SERVER�TYPICALLY�USES�INFORMATION�FROM�THE�ROUTEREQUEST�EVENT�TOGETHER�WITH�INFORMATION�FROM�AN�APPLICATIONDATABASE�TO�DETERMINE�THIS�DESTINATION��4HE�ROUTING�SERVER�MAYINCLUDE�AN�OPTIONAL�FLAG�IN�THE�ROUTE�SELECT��ROUTE5SED2EQINSTRUCTING�THE�SWITCH�TO�INFORM�IT�OF�THE�FINAL�DESTINATION�FOR�THECALL��4HE�FINAL�DESTINATION�MAY�BE�DIFFERENT�THAN�THE�APPLICATION PROVIDED�DESTINATION�WHEN�SWITCH�FEATURES�SUCH�AS�CALLFORWARDING�REDIRECT�THE�CALL�

�� THE�SWITCH�RECEIVES�THE�ROUTE�SELECT�MESSAGE�CSTA2OUTE3ELECT)NV�AND�ATTEMPTS�TO�ROUTE�THE�CALL�TO�THEAPPLICATION PROVIDED�DESTINATION��)F�THE�DESTINATION�IS�VALID��THESWITCH�ROUTES�THE�CALL�TO�THAT�DESTINATION�AND�SENDS�THEAPPLICATION�A�ROUTE�END�EVENT��CSTA2OUTE%ND)NV��4HIS�TERMINATESTHE�ROUTING�DIALOG�FOR�THAT�CALL��)F�THE�APPLICATION PROVIDEDDESTINATION�IS�NOT�VALID��AN�INVALID�EXTENSION�NUMBER��THEDESTINATION�IS�BUSY��ETC��THEN�THE�SWITCH�MAY�SEND�A�RE ROUTEEVENT��#34!2E2OUTE2EQUEST%VENT�TO�THE�APPLICATION�TO�REQUESTANOTHER�ROUTE�TO�A�DIFFERENT�DESTINATION�


�� )F�THE�APPLICATION�RECEIVES�A�RE ROUTE�EVENT�#34!2E2OUTE2EQUEST%VENT�IT�CAN�SELECT�A�DIFFERENT�DESTINATIONFOR�THE�CALL�AND�SEND�THE�SWITCH�ANOTHER�ROUTE�SELECT�MESSAGE�CSTA2OUTE3ELECT)NV��$EPENDING�ON�THE�SWITCH�IMPLEMENTATION��THERE ROUTING�MESSAGE�EXCHANGE��CAN�REPEAT�UNTIL�THE�APPLICATIONPROVIDES�A�VALID�ROUTE��4HE�ROUTING�SERVER�APPLICATION�WILL�FIND�OUTABOUT�A�SUCCESSFUL�ROUTE�IF�THE�SWITCH�SENDS�A�ROUTE�END�EVENT�CSTA2OUTE%ND)NV�OR�IF�THE�APPLICATION�INCLUDED�THE�ROUTE5SED2EQFLAG�IN�ITS�LAST�ROUTE�SELECT�MESSAGE��CSTA2OUTE3ELECT)NV�

Either the switch or the routing server (application) may send a route endevent (cstaRouteEndInv) to end the routing process and terminate the CSTArouting dialog (this releases the routing cross-reference identifier,routingCrossRefID for use in the future). Either endpoint may send a routeend at any time. This message indicates that the routing server does not wantto route the call, or the switch (usually in the absence of a cstaRouteSelectInvmessage) routed the call using some mechanism within the switching domain.

Certain switch implementations may not support the optional flags describedabove.

Figure 8-17 illustrates the Routing Procedure.

.OTE


Figure 8-17Routing Procedure

$RIVER�3WITCH�$OMAIN 2OUTING�3ERVER��APPLICATION

��A�CALL�ARRIVES�AT�THE�ROUTING�DEVICE

�ROUTING#ROSS2EF)$�CREATED�AND�

#34!2OUTE2EQUEST%VENT�IS�SENT

CALL�RELATED�)NFO�IS�PASSED

�E�G��!.)��$.)3��COLLECTED�DIGITS

��!PPLICATION�SELECTS�A�

DESTINATION�FOR�THE�CALL��BASED�ON�

THE�CALL�AND�OTHER�CUSTOMER�INFO��!CSTA2OUTE3ELECT)NV��MESSAGE�IS

�2OUTE�5SED

��THE�SWITCH�ATTEMPTS�TO��ROUTE�THE

QUEUED�CALL�TO�SELECTED�DEST��

��A�)F�DESTINATION�ADDRESS�IS�O�K��A�

#34!2OUTE%ND%VENT�IS�SENT

��B�)F�DESTINATION�IS�INVALID��THEN�A

#34!2E2OUTE%VENT�IS�SENTOR

��

��

��A

��B��A�)F��A�THEN�ROUTING#ROS2EF)$ �IS�NO�

LONGER�VALID�AND�ROUTE�IS�COMPLETED�

AS�SPECIFIED�IN��

��B�)F��B�THEN�SEND�A�SECOND�

CSTA2OUTE3ELECT)NV��WITH�A�DIFFERENT��B��THE�SWITCH�ATTEMPTS�TO��ROUTE�THE

QUEUED�CALL�TO�SELECTED�DEST��

��A�)F�DESTINATION�ADDRESS�O�K��A�

#34!2OUTE5SED%VENT�AND�

#34!2OUTE%ND%VENT�IS�SENT

��B�)F�DESTINATION�IS�INVALID��THEN�A

#34!2E2OUTE%VENT�IS�SENT

OR��A

��B

��A�)F��A�THEN�ROUTING#ROS2EF)$�IS�NO�

LONGER�VALID�AND�ROUTE�IS�COMPLETED�

AS�SPECIFIED�IN��B�

��B�)F��B�THEN�SEND�A�SECOND�

CSTA2OUTE3ELECT)NV�� WITH�A�DIFFERENT�

� ��OFF�

DESTINATION��2OUTE�5SED ��ON�

DESTINATION��2OUTE�5SED ��ON�

�SENT


2OUTING�2EGISTRATION�&UNCTIONS�AND�%VENTS

This section describes the service requests and events that an application usesto register with the Telephony Server as a call routing server


CSTA2OUTE2EGISTER2EQ��

An application uses cstaRouteRegisterReq( ) to register as a routing serverfor a specific routing device or as a default routing server for an advertisedservice. The application must register for routing services before it can receiveany route requests for a routing device. An application may be a routingserver for more than one routing device. However, only one application maybe a routing server for any given routing device. Similarly, only oneapplication may register as the default routing server for an advertised service.

Syntax


2ET#ODE?T�CSTA2OUTE2EGISTER2EQ��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�$EVICE)$?T ROUTING$EVICE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters

acsHandle4HIS�IS�THE�HANDLE�TO�AN�ACTIVE�!#3�3TREAM�OVER�WHICH�THE�ROUTINGDIALOG�WILL�TAKE�PLACE�

invokeID4HIS�IS�AN�APPLICATION�PROVIDED�HANDLE�THAT�THE�APPLICATION�USES�TOMATCH�A�SPECIFIC�INSTANCE�OF�CSTA2OUTE2EGISTER2EQ��REQUEST�WITHITS�#34!2OUTE2EGISTER2EQ#ONF%VENT�CONFIRMATION�EVENT��4HEAPPLICATION�SUPPLIES�THIS�PARAMETER�ONLY�WHEN�THE�)NVOKE�)$MECHANISM�IS�SET�FOR�!PPLICATION GENERATED�)$S�IN�ACS/PEN 3TREAM��4HE�!#3�,IBRARY�IGNORES�THIS�PARAMETER�WHEN�THE�3TREAMIS�SET�FOR�,IBRARY GENERATED�INVOKE�)$S�


routingDevice4HIS�IS�A�POINTER�TO�A�DEVICE�ID�FOR�THE�ROUTING�DEVICE�FOR�WHICH�THEAPPLICATION�REQUESTS�TO�BE�THE�ROUTING�SERVER��4HE�ROUTING�DEVICE�CANBE�ANY�DEVICE�TYPE�WHICH�THE�SWITCH�IMPLEMENTATION�SUPPORTS�AS�AROUTING�DEVICE��!�.5,,�VALUE�INDICATES�THAT�THE�REQUESTINGAPPLICATION�WILL�BE�THE�DEFAULT�ROUTING�SERVER�FOR�THE�3ERVER)$�AS SOCIATED�WITH�THE�ACS(ANDLE�IN�THE�CSTA2OUTE2EGISTER2EQ��4HEDEFAULT�ROUTING�SERVER�WILL�RECEIVE�SWITCH�ROUTING�REQUESTS�FOR�ANYROUTING�DEVICES�MAKING�ROUTING�REQUESTS�ON�THAT�ADVERTISED�SERVICETHAT�DO�NOT�HAVE�REGISTERED�ROUTING�SERVERS��4HUS��THE�DEFAULT�ROUTINGSERVER�WILL�RECEIVE�ROUTE�REQUESTS�WHEN�A�ROUTING�DEVICE�SENDS�A�ROUTEREQUEST�AND�THERE�IS�NO�CORRESPONDING�REGISTERED�ROUTING�SERVER�FORTHAT�ROUTING�DEVICE�


Return Values

CSTA2OUTE2EGISTER2EQ��RETURNS�THE�FOLLOWING�VALUESDEPENDING�ON�WHETHER�THE�APPLICATION�IS�USING�LIBRARY�ORAPPLICATION GENERATED�INVOKE�IDENTIFIERS��,IBRARY GENERATED)DENTIFIERS� �IF�THE�FUNCTION�CALL�COMPLETES�SUCCESSFULLY�IT�WILLRETURN�A�POSITIVE�VALUE��THE�INVOKE�IDENTIFIER��)F�THE�CALL�FAILSIT�WILL�RETURN�A�NEGATIVE�ERROR��&OR�LIBRARY GENERATEDIDENTIFIERS�THE�RETURN�WILL�NEVER�BE�ZERO��


!N�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!2OUTE2EGISTER 2EQ#ONF%VENT�MESSAGE�TO�ENSURE�TO�ENSURE�THAT�THE�4ELEPHONY3ERVER�AND�SWITCH�HAVE�ACKNOWLEDGED�THE�CSTA2OUTE2EGISTER2EQ��





Comments

)N�ORDER�FOR�AN�APPLICATION�TO�ROUTE�CALLS�THE�APPLICATION�MUST�SUCCESS FULLY�CALL�CSTA2OUTE2EGISTER2EQ��!N�APPLICATION�CAN�REGISTER�AS�

u A�ROUTING�SERVER�FOR�THE�SPECIFIED�ROUTING�DEVICE��OR

u AS�THE�DEFAULT�ROUTING�SERVER�FOR�ALL�ROUTING�DEVICESMAKING�REQUESTS�OF�A�SPECIFIC�4ELEPHONY�3ERVER�

4O�REGISTER�AS�A�DEFAULT�ROUTING�SERVER��AN�APPLICATION�SETS�THE�ROUT ING$EVICE�PARAMETER�TO�.5,,��/NE��AND�ONLY�ONE��APPLICATION�IS�AL LOWED�TO�REGISTER�AS�THE�ROUTING�SERVER�FOR�A�ROUTING$EVICE��OR�AS�THEDEFAULT�ROUTING�3ERVER�FOR�AN�ADVERTISED�SERVICE��!PPLICATIONS�MAYREGISTER�FOR�ROUTING�SERVICES�FOR�A�SPECIFIC�DEVICE�EVEN�WHEN�A�DEFAULTROUTING�SERVER�HAS�REGISTERED��!�DEFAULT�ROUTING�SERVER�WILL�NOTRECEIVE�ANY�ROUTING�REQUESTS�FROM�ANY�ROUTING�DEVICE�FOR�WHICH�THEREIS�A�REGISTERED�ROUTING�SERVER��/NCE�A�ROUTING�SERVER�IS�REGISTERED�#34!2OUTE2EQUEST%VENTS�CONVEY�THE�ROUTE�REQUESTS�TO�THE�ROUTINGSERVER�


#34!2OUTE2EGISTER2EQ#ONF%VENT

The RouteRegisterReqConfEvent indicates successful registration to anapplication. That application is now the call routing server for the requestedrouting device (or is the default routing server for the advertised service).

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�UNION[��#34!2OUTE2EGISTER2EQ#ONF%VENT?T��ROUTE2EGISTER�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�[2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�

]�#34!2OUTE2EGISTER2EQ#ONF%VENT?T�

TYPEDEF�LONG��2OUTE2EGISTER2EQ)$?T�

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�!#3�3TREAM�OVER�WHICH�THE2OUTE2EGISTER2EQ#ONF%VENT �CONFIRMATION�ARRIVED��4HIS�IS�THESAME�AS�THE�!#3�3TREAM�OVER�WHICH�THE�APPLICATION�MADE�THECORRESPONDING�CSTA2OUTE2EGISTER2EQ��REQUEST�


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICH�IDENTI FIES�THIS�MESSAGE�AS�AN�#34!�CONFIRMATION�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE#34!?2/54%?2%')34%22%1?#/.&��WHICH�IDENTIFIES��THISMESSAGE�AS�AN�#34!2OUTE2EGISTER2EQ#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�SERVICE�REQUEST�INSTANCE�FOR�THECSTA2OUTE2EGISTER2EQ��4HE�APPLICATION�USES�THIS�PARAMETER�TOCORRELATE�2OUTE2EGISTER2EQ#ONF%VENT�RESPONSES�WITH�REQUESTS�

routeRegisterReqID4HIS�PARAMETER�CONTAINS�A�HANDLE�TO�THE�ROUTING�REGISTRATION�SESSIONFOR�A�SPECIFIC�ROUTING�DEVICE��OR�FOR�THE�DEFAULT�ROUTING�SERVERDEPENDING�ON�THE�REGISTRATION�REQUEST��!LL�ROUTING�DIALOGS�ROUTING#ROSS2EF)$S�FOR�A�ROUTING�DEVICE�OCCUR�OVER�THIS�ROUTINGREGISTRATION�SESSION��4HE�0"8�$RIVER�SELECTS�ROUTE2EGISTER2EQ)$SSO�THAT�THEY�WILL�BE�UNIQUE�WITHIN�THE�ACS(ANDLE�

PRIVATE$ATA)F�PRIVATE�DATA�ACCOMPANIES�THIS�EVENT��THEN�THE�PRIVATE�DATA�WOULD�BESTORED�IN�THE�LOCATION�THAT�THE�APPLICATION�SPECIFIED�AS�THE�PRIVATE$ATAPARAMETER�IN�THE�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��REQUEST��)F�THE�PRIVATE$ATA�POINTER�IS�SET�TO�.5,,�IN�THESE�REQUESTS�THEN�#34!2OUTE2EGISTER2EQ#ONF%VENT�DOES�NOT�DELIVER�PRIVATEDATA�TO�THE�APPLICATION�

Comments

4HIS�EVENT�PROVIDES�THE�APPLICATION�WITH�A�POSITIVE�CONFIRMATION�TO�AREQUEST�FOR�ROUTING�REGISTRATION�


CSTA2OUTE2EGISTER#ANCEL��

Applications (routing servers) use cstaRouteRegisterCancel( ) to cancel apreviously registered routing server session. This request terminates therouting session and the application receives no further routing messages forthat session once it receives the confirmation to the cancel request.

Syntax


2ET#ODE?T�CSTA2OUTE2EGISTER#ANCEL��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�0RIVATE$ATA?T PRIVATE$ATA�

Parameters

acsHandle4HIS�IS�THE�HANDLE�TO�AN�ACTIVE�!#3�3TREAM�OVER�WHICH�THECSTA2OUTE2EGISTER#ANCEL��REQUEST�WILL�BE�MADE�

invokeID4HIS�IS�AN�APPLICATION�PROVIDED�HANDLE�THAT�THE�APPLICATION�USES�TOMATCH�A�SPECIFIC�INSTANCE�OF�A�CSTA2OUTE2EGISTER#ANCEL��REQUESTWITH�ITS�CONFIRMATION�EVENT��4HE�APPLICATION�SUPPLIES�THIS�PARAMETERONLY�WHEN�THE�)NVOKE�)$�MECHANISM�IS�SET�FOR�!PPLICATION GENERATED)$S�IN�ACS/PEN3TREAM��4HE�!#3�,IBRARY�IGNORES�THIS�PARAMETERWHEN�THE�3TREAM�IS�SET�FOR�,IBRARY GENERATED�INVOKE�)$S�

routeRegisterReqID4HIS�PARAMETER�IS�THE�HANDLE�TO�THE�ROUTING�REGISTRATION�SESSION�WHICHTHE�APPLICATION�IS�CANCELING��4HE�APPLICATION�RECEIVED�THIS�HANDLE�INTHE�CONFIRMATION�EVENT�FOR�THE�ROUTE�REGISTER�SERVICE�REQUEST��A#34!2OUTE2EGISTER2EQ#ONF%VENT �



Return Values

CSTA2OUTE2EGISTER#ANCEL��RETURNS�THE�FOLLOWING�VALUES�DEPENDINGON�WHETHER�THE�APPLICATION�IS�USING�LIBRARY�OR�APPLICATION GENERATEDINVOKE�IDENTIFIERS�



4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!2OUTE2EGISTER#ANCEL#ONF%VENT �MESSAGE�TO�ENSURE�THAT�THE4ELEPHONY�3ERVER�AND�SWITCH�HAVE�ACKNOWLEDGED�AND�PROCESSED�THECSTA2OUTE2EGISTER#ANCEL��REQUEST�




Comments

4HE�APPLICATION�MUST�CONTINUE�TO�PROCESS�OUTSTANDING�ROUTINGREQUESTS�FROM�THE�ROUTING�DEVICE�UNTIL�IT�RECEIVES#34!2OUTE2EGISTER#ANCEL#ONF%VENT��4HE�4ELEPHONY�3ERVER�WILLNOT�SEND�ANY�FURTHER�REQUESTS�ONCE�IT�HAS�SENT�THIS�CONFIRMATION�EVENT�


#34!2OUTE2EGISTER#ANCEL#ONF%VENT

CSTARouteRegisterCancelConfEvent confirms a previously issuedcstaRouteRegisterCancel( ) request for a routing registration. Once tanapplication receives this event, it invalidates the routing registration session.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[

!#3%VENT(EADER?T EVENT(EADER�UNION

[STRUCT

[)NVOKE)$?T INVOKE)$�UNION[

#34!2OUTE2EGISTER#ANCEL#ONF%VENT?T

ROUTE#ANCEL�]�U�


]�#34!%VENT?T�


]�#34!2OUTE2EGISTER#ANCEL#ONF%VENT?T�



Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�!#3�3TREAM�OVER�WHICH�THE#34!2OUTE2EGISTER#ANCEL#ONF%VENT�CONFIRMATION�ARRIVED��4HISIS�THE�SAME�AS�THE�!#3�3TREAM�OVER�WHICH�THECSTA2OUTE2EGISTER#ANCEL��REQUEST�WAS�MADE�

eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICH��IDENTI FIES�THIS�MESSAGE�AS�AN�#34!�CONFIRMATION�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE#34!?2/54%?2%')34%2?#!.#%,?#/.&��WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!2OUTE2EGISTER#ANCEL#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�SERVICE�REQUEST�INSTANCE�FOR�THECSTA2OUTE2EGISTER#ANCEL��4HE�APPLICATION�USES�THIS�PARAMETER�TOCORRELATE�THE�#34!2OUTE2EGISTER#ANCEL#ONF%VENT� RESPONSES�WITHREQUESTS�

routeRegisterReqID4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�A�ROUTING�REGISTRATION�FOR�WHICHTHE�APPLICATION�IS�PROVIDING�ROUTING�SERVICES��4HE�APPLICATIONOBTAINED�THIS�HANDLE�FROM�A�#34!2OUTE2EGISTER2EQ#ONF%VENT �4HIS�ROUTE2EGISTER2EQ)$�HANDLE�IS�NO�LONGER�VALID�ONCE�THE4ELEPHONY�3ERVER�SENDS�#34!2OUTE2EGISTER#ANCEL#ONF%VENT �

privateData)F�PRIVATE�DATA�ACCOMPANIES�THIS�EVENT��THEN�THE�PRIVATE�DATA�WOULD�BESTORED�IN�THE�LOCATION�THAT�THE�APPLICATION�SPECIFIED�AS�THE�PRIVATE$ATAPARAMETER�IN�THE�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��REQUEST��)F�THE�PRIVATE$ATA�POINTER�IS�SET�TO�.5,,�IN�THESE�REQUESTS�THEN�#34!3NAPSHOT#ALL#ONF%VENT�DOES�NOT�DELIVER�PRIVATE�DATA�TOTHE�APPLICATION�


Comments

#34!2OUTE2EGISTER#ANCEL#ONF%VENT �CONFIRMS�AN�APPLICATION�SCSTA2OUTE2EGISTER#ANCEL��SERVICE�REQUEST��WHICH�CANCELS�A�ROUTINGREGISTRATION�SESSION��4HE�4ELEPHONY�3ERVER�WILL�SEND�ANY�FURTHER�RE QUESTS�FROM�THE�ROUTING�DEVICE�TO�THE�DEFAULT�ROUTING�SERVER�


#34!2OUTE2EGISTER!BORT%VENT

The Telephony Server sends an application an unsolicitedCSTARouteRegisterAbortEvent to cancel an active routing dialog. Thisevent invalidates a routing registration session.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

UNION[

#34!2OUTE2EGISTER!BORT%VENT?TREGISTER!BORT�

]�U�]�CSTA%VENT2EPORT�



]�#34!2OUTE2EGISTER!BORT%VENT?T�


Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�OPENED�!#3�3TREAM��4HE�ROUTING�DIALOGBEING�CANCELED�IS�OCCURRING�ON�THIS�!#3�3TREAM�


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!%6%.42%0/24��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�#34!�EVENT�REPORT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?2/54%?2%')34%2?!"/24�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN�#34!2OUTE2EGISTER!BORT% VENT�

routeRegisterReqID4HIS�PARAMETER�IS�THE�HANDLE�TO�A�ROUTING�REGISTRATION�FOR�WHICH�THEAPPLICATION�IS�PROVIDING�ROUTING�SERVICES��4HE�APPLICATION�RECEIVEDTHIS�HANDLE�IN�A�#34!2OUTE2EGISTER2EQ#ONF%VENT ��4HE#34!2OUTE2EGISTER!BORT%VENT� INVALIDATES�THIS�HANDLE�

privateData)F�PRIVATE�DATA�ACCOMPANIES�#34!2OUTE2EGISTER!BORT%VENT ��THENTHE�PRIVATE�DATA�WOULD�BE�STORED�IN�THE�LOCATION�THAT�THE�APPLICATIONSPECIFIED�AS�THE�PRIVATE$ATA�PARAMETER�IN�THE�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��REQUEST��)F�THE�PRIVATE$ATA�POINTER�IS�SET�TO.5,,�IN�THESE�REQUESTS��THEN�#34!2OUTE2EGISTER!BORT%VENT�DOESNOT�DELIVER�PRIVATE�DATA�TO�THE�APPLICATION�

Comments

#34!2OUTE2EGISTER!BORT%VENT �NOTIFIES�THE�APPLICATION�THAT�THE0"8�DRIVER�OR�SWITCH�ABORTED�A�ROUTING�REGISTRATION�SESSION�


2OUTING�&UNCTIONS�AND�%VENTS

This section defines the CSTA call routing services for application callrouting. The switch queues calls at the routing device until the applicationprovides a destination for the call or a time-out condition occurs within theswitching domain. Figure 8-17 shows the Application-based call routing dia-log between a switch and the routing server (the application).

Once an application registers as a routing server, the application uses theservices in this section to route calls. The application receives aCSTARouteRequestEvent for each call which requires a routing destination.The application sends the switch a destination in cstaRouteSelectInv( ). Theswitch then attempts to route the call to that application-provided destination.The switch will respond with a CSTARouteEndEvent and/or aCSTARouteUsedEvent. If the application-provided destination is invalid, theswitch may send a CSTAReRouteRequestEvent to request an additionaldestination. See Figure 8-17 for a typical sequence of these events and servicerequests.


2EGISTER�2EQUEST�)$�AND�THE�2OUTING�#ROSS 2EFERENCE�)$

The routing services use two handles (identifiers) to refer to different softwareobjects in the Telephony Server. The register request identifier(routeRegisterReqID) identifies a routing session over which an applicationwill receive routing requests. This handle is tied to a routing device on theswitch, or it may indicate that the application is the default routing server foran advertised service. When the application uses cstaRouteRegisterReq( ) toregister for routing services, it receives a routeRegisterReqID in theconfirmation. The routeRegisterReqID is valid until the registration iscanceled or aborted.

Within a routing session (routeRegisterReqID) the switch may initiate manyrouting dialogs (shown in Figure 8-17) to route multiple calls. An applicationuses a routing cross reference-identifier (routingCrossRefID) to refer to eachrouting dialog. The application receives a routingCrossRefID in eachCSTARouteRequestEvent. The CSTARouteRequestEvent initiates arouting dialog. The routingCrossRefID is valid for the duration of the callrouting dialog.

The routing cross-reference identifier (routingCrossRefID) is unique withinthe routing session (routeRegisterReqID). Some switch implementations mayprovide the additional benefit of a unique routing cross reference-identifieracross the entire switching domain. Routing session identifiers(routeRegisterReqIDs) are unique within an ACS Stream (acsHandle).

If a call is not successfully routed by the routing server this does notnecessarily mean that the call is cleared or not answered. Most switchimplementations will have a default mechanism for handling a call at a routingdevice when the routing server has failed to provide a valid destination for thecall.

.OTE


#34!2OUTE2EQUEST%VENT

A routing server application receives a CSTARouteRequestEvent when theswitch requests a route for a call. The application may have registered as therouting server for the routing device on the switch that is making the request,or it may have registered as the default routing server for the advertisedservice. The CSTARouteRequestEvent event includes call relatedinformation (such as the called and calling number, when available). Arouting server application typically combines the call related information withan application database to determine a destination for the call. A routing serverapplication receives a CSTARouteRequestEvent for every call queued at therouting device.

TSAPI Version

!PPLICATIONS�USING�43!0)�6ERSION��MUST�USE�THE#34!2OUTE2EQUEST%VENT?T�STRUCTURE��APPLICATIONS�USING�ANY�OTHERVERSION�MUST�USE�THE�#34!2OUTE2EQUEST%XT%VENT?T�STRUCTURE�

Syntax


TYPEDEF�STRUCT�[!#3(ANDLE?T ACS(ANDLE�%VENT#LASS?T EVENT#LASS�%VENT4YPE?T EVENT4YPE�



TYPEDEF�STRUCT�[!#3%VENT(EADER?T EVENT(EADER�UNION[

STRUCT[


#34!2OUTE2EQUEST%VENT?T ROUTE2EQUEST�

��VERSION��UNION�ONLY��#34!2OUTE2EQUEST%XT%VENT?T ROUTE2EQUEST%XT

]�U�]�CSTA2EQUEST�


43!0)�6ERSION��TYPEDEF�STRUCT�[

2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�$EVICE)$?T CURRENT2OUTE�$EVICE)$?T CALLING$EVICE�#ONNECTION)$?T ROUTED#ALL�3ELECT6ALUE?T ROUTED3EL!LGORITHM�"OOLEAN PRIORITY�3ET5P6ALUES?T SETUP)NFORMATION�

]�#34!2OUTE2EQUEST%VENT?T�

43!0)�6ERSION��

TYPEDEF�STRUCT�[2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�#ALLED$EVICE)$?T CURRENT2OUTE� ��6��#ALLING$EVICE)$?T CALLING$EVICE� ��6��#ONNECTION)$?T ROUTED#ALL�3ELECT6ALUE?T ROUTED3EL!LGORITHM�"OOLEAN PRIORITY�3ET5P6ALUES?T SETUP)NFORMATION�

]�#34!2OUTE2EQUEST%XT%VENT?T� ��6��

TYPEDEF�ENUM�3ELECT6ALUE?T�[36?./2-!,��36?,%!34?#/34��36?%-%2'%.#9��36?!#$��36?53%2?$%&).%$��

]�3ELECT6ALUE?T�

TYPEDEF�STRUCT�3ET5P6ALUES?T�[INT LENGTH�UNSIGNED�CHAR VALUE�

]�3ET5P6ALUES?T�


Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�OPENED�!#3�3TREAM�ON�WHICH�THE�ROUTE�RE QUEST�EVENT�ARRIVES�

eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!2%15%34��WHICH�IDENTIFIES�THISMESSAGE�AS�AN�#34!�REQUEST�MESSAGE�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?2/54%?2%15%34��VERSION��OR�#34!?2/54%?2%15%34?%84��VERSION��WHICH�IDENTIFIESTHIS�MESSAGE�AS�AN�#34!2OUTE2EQUEST%VENT�

routeRegisterReqID4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�ROUTING�REGISTRATION�SESSIONFOR�WHICH�THE�APPLICATION�IS�PROVIDING�ROUTING�SERVICES��4HE�APPLICA TION�RECEIVED�THIS�HANDLE�IN�A�#34!2OUTE2EGISTER2EQ#ONF%VENTCONFIRMATION�TO�A�ROUTE�REGISTER�SERVICE�REQUEST�

routingCrossRefID4HE�APPLICATION�RECEIVES�THIS�NEW�HANDLE�FOR�THE�ROUTING�DIALOG�FORTHIS�CALL��4HIS�IDENTIFIER�HAS�A�NEW��UNIQUE�VALUE�WITHIN�THE�SCOPE�OFTHE�ROUTING�SESSION��ROUTE2EGISTER2EQ)$�

currentRoute4HIS�PARAMETER�INDICATES�THE�ORIGINALLY�REQUESTED�DESTINATION�FOR�THECALL�BEING�APPLICATION�ROUTED��/FTEN��THIS�IS�THE�$.)3��OR�DIALED�NUM BER�

callingDevice4HIS�IS�THE�ORIGINATING�DEVICE�OF�THE�CALL��I�E��THE�CALLING�PARTY�NUMBER�WHEN�AVAILABLE��)F�NOT�AVAILABLE��IT�MAY�BE�TRUNK�INFORMATION�

routedCall4HIS�PARAMETER�IS�A�#34!�#ONNECTION�)$�THAT�IDENTIFIES�THE�CALLBEING�ROUTED�

routedSelAlgorithm4HIS�PARAMETER�IDENTIFIES�THE�ROUTING�ALGORITHM�BEING�USED�


priority4HIS�PARAMETER�INDICATES�THE�PRIORITY�OF�THE�CALL�

SETUP)NFORMATION4HIS�PARAMETER�INCLUDES�AN�)3$.�CALL�SETUP�MESSAGE��IF�AVAILABLE�

PRIVATE$ATA)F�PRIVATE�DATA�ACCOMPANIES�#34!2OUTE2EQUEST%VENT��THEN�THE�PRI VATE�DATA�WOULD�BE�STORED�IN�THE�LOCATION�THAT�THE�APPLICATIONSPECIFIED�AS�THE�PRIVATE$ATA�PARAMETER�IN�THE�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��REQUEST��)F�THE�PRIVATE$ATA�POINTER�IS�SET�TO.5,,�IN�THESE�REQUESTS��THEN�#34!2OUTE2EQUEST%VENT�DOES�NOTDELIVER�PRIVATE�DATA�TO�THE�APPLICATION�

Comments

#34!2OUTE2EQUEST%VENT�INFORMS�THE�ROUTING�SERVER��APPLICATIONTHAT�THE�SWITCH�IS�REQUESTING�A�DESTINATION�FOR�A�CALL�QUEUED�AT�THEROUTING�DEVICE��4HE�APPLICATION�USES�CSTA2OUTE3ELECT)NV��ORCSTA2OUTE3ELECT��TO�RESPOND�WITH�A�DESTINATION�

CSTA requires that all events contain an invoke ID. During routing, theRouteRegisterReqID and the RoutingCrossRefID identify the routing dialogue.The invokeID is not used.

.OTE


#34!2E2OUTE2EQUEST%VENT

The switch sends an unsolicited CSTAReRouteRequestEvent to request ananother destination for a call. Typically, the destination that the applicationpreviously sent was invalid or busy. The switch previously sent call relatedinformation (such as the called and calling numbers) in theCSTARouteRequestEvent; Call related information is not re-sent in theCSTAReRouteRequestEvent. The routing server application responds usingthe cstaRouteSelectInv( ) or cstaRouteSelect( ) service.

Syntax

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!2E2OUTE2EQUEST?TRE2OUTE2EQUEST�

]�U�]�CSTA2EQUEST%VENT�


TYPEDEF�STRUCT[

2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�

]�#34!2E2OUTE2EQUEST?T�

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�OPENED�!#3�3TREAM�ON�WHICH�THE�RE ROUTEREQUEST�ARRIVES�


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!2%15%34��WHICH�IDENTIFIES�THISMESSAGE�AS�A�#34!�REQUEST�MESSAGE�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?2%?2/54%?2%15%34��WHICHIDENTIFIES��THIS�MESSAGE�AS�A�#34!2E2OUTE2EQUEST%VENT�


routingCrossRefID4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�#34!�CALL�ROUTING�DIALOGFOR�THIS�CALL��4HE�APPLICATION�PREVIOUSLY�RECEIVED�THIS�HANDLE�IN�A#34!2OUTE2EQUEST%VENT�FOR�THE�CALL�

privateData)F�PRIVATE�DATA�ACCOMPANIES�#34!2E2OUTE2EQUEST%VENT��THEN�THEPRIVATE�DATA�WOULD�BE�STORED�IN�THE�LOCATION�THAT�THE�APPLICATIONSPECIFIED�AS�THE�PRIVATE$ATA�PARAMETER�IN�THE�ACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��REQUEST��)F�THE�PRIVATE$ATA�POINTER�IS�SET�TO.5,,�IN�THESE�REQUESTS��THEN�#34!2E2OUTE2EQUEST%VENT�DOES�NOTDELIVER�PRIVATE�DATA�TO�THE�APPLICATION�

Comments

4HE�SWITCH�CAN�SEND�#34!2E2OUTE2EQUEST%VENT�TO�THE�ROUTINGSERVER�APPLICATION�WHEN�THE�APPLICATION�PREVIOUSLY�SENT�A�DESTINATIONTHAT�WAS�IS�INVALID�OR�OTHER�CIRCUMSTANCES�EXIST�WHERE�ROUTING�OF�THECALL�TO�THE�DESTINATION�IS�NOT�POSSIBLE��E�G��THE�DESTINATION�IS�BUSY�4HE�SWITCH�USES�#34!2E2OUTE2EQUEST%VENT�TO�REQUEST�ANOTHERDESTINATION�FOR�THE�CALL�QUEUED�AT�THE�ROUTING�DEVICE��4HE�APPLICATIONUSES�CSTA2OUTE3ELECT��TO�PROVIDE�THE�NEW�DESTINATION�

4HE�NUMBER�OF�RE ROUTE�REQUESTS�THAT�A�SWITCH�MAY�SEND�DEPENDS�ONTHE�IMPLEMENTATION�OR�ADMINISTRATION�WITHIN�THE�SWITCH��4HE�APPLICA TION�SHOULD�BE�PREPARED�TO�RESPOND�TO�ALL�RE ROUTE�REQUESTS�ORTERMINATE�THE�ROUTING�DIALOG�BY�USING�THE�CSTA2OUTE%ND��SERVICEREQUEST�WHEN�IT�CANNOT�PROVIDE�ADDITIONAL�DESTINATIONS�


CSTA requires that all events contain an invoke ID. During routing, theRouteRegisterReqID and the RoutingCrossRefID identify the routing dialogue.The invokeID is not used.

.OTE


CSTA2OUTE3ELECT��43!0)�6ERSION��/NLY

The routing server application uses cstaRouteSelect to send a routingdestination to the switch in response to a CSTARouteRequestEvent for acall.

TSAPI Version

!PPLICATIONS�USING�43!0)�6ERSION��MUST�USE�THE#34!2OUTE3ELECT��FUNCTION��APPLICATIONS�USING�ANY�OTHER�VERSIONMUST�USE�THE�#34!2OUTE3ELECT)NV��FUNCTION�

Syntax

�INCLUDE��CSTA�H��INCLUDE��ACS�H�

2ET#ODE?T�CSTA2OUTE3ELECT��!#3(ANDLE?T ACS(ANDLE�2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�$EVICE)$?T ROUTE3ELECTED�2ETRY6ALUE?T REMAIN2ETRY�3ET5P6ALUES?T SETUP)NFORMATION�"OOLEAN ROUTE5SED2EQ�0RIVATE$ATA?T PRIVATE$ATA�

Parameters

acsHandle4HIS�IS�THE�HANDLE�TO�THE�!#3�3TREAM�ON�WHICH�THE�ROUTING�DIALOG�FORTHE�CALL�IS�TAKING�PLACE�

routeRegisterReqID4HIS�PARAMETER�CONTAINS�THE�ACTIVE�HANDLE�TO�THE�ROUTING�REGISTRATIONSESSION�FOR�WHICH�THE�APPLICATION�IS�PROVIDING�ROUTING�SERVICES��4HEAPPLICATION�RECEIVED�THIS�HANDLE�IN�THE�CONFIRMATION�EVENT�FOR�THEROUTE�REGISTER�SERVICE�REQUEST�#34!2OUTE2EGISTER2EQ#ONF%VENT�FOR�THE�CALL�

routingCrossRefID4HIS�PARAMETER�CONTAINS� THE�HANDLE� TO� THE�#34!�CALL� ROUTING�DIALOGFOR� THIS� CALL��4HE� APPLICATION� PREVIOUSLY� RECEIVED� THIS� HANDLE� IN� THE#34!2OUTE2EQUEST%VENT�FOR�THE�CALL�


routeSelected4HE�APPLICATION�PROVIDES�THIS�PARAMETER�CONTAINING�A�$EVICE�)$�THATSPECIFIES�THE�DESTINATION�FOR�THE�CALL�

remainRetry4HE�APPLICATION�INDICATES�THE�NUMBER�OF�TIMES�IT�IS�WILLING�TO�RECEIVEA�#34!2E2OUTE2EQUEST%VENT�FOR�THIS�CALL�IN�THE�CASE�THAT�THESWITCH�NEEDS�TO�REQUEST�AN�ALTERNATE�ROUTE��43!0)�PROVIDES��DEFINEVALUES�THAT�AN�APPLICATION�MAY�USE�TO�INDICATE�THAT�IT�DOES�NOT�KEEPCOUNT��OR�THAT�THERE�IS�NO�LIMIT�

setupInformation4HE�APPLICATION�PROVIDES�THIS�OPTIONAL�PARAMETER�THAT��CONTAINSINFORMATION�FOR�THE�)3$.�CALL�SETUP�MESSAGE�THAT�THE�SWITCH�WILL�USETO�ROUTE�THE�CALL��3OME�SWITCHES�MAY�NOT�SUPPORT�THIS�OPTION�

routeUsedReq4HE�ROUTING�APPLICATION�USES�THIS�PARAMETER�TO�REQUEST�A#34!2OUTE5SED%VENT�FOR�THE�CALL��4HE�ROUTE�USED�EVENT�INFORMSTHE�APPLICATION�OF�THE�FINAL�DESTINATION�OF�THE�CALL�ONCE�IT�HAS�BEENROUTED�


Return Values

CSTA2OUTE3ELECT��RETURNS�A�NON ZERO�VALUE�IF�IT�COMPLETESSUCCESSFULLY�




There is no confirmation event for this service request, however thisservice request can generate a universal failure event.

.OTE


Comments

!N�APPLICATION�SHOULD�CALL�CSTA2OUTE3ELECT�ONLY�IN�RESPONSE�TO�A#34!2OUTE2EQUEST%VENT�OR�#34!2E2OUTE2EQUEST%VENT��4HECSTA2OUTE3ELECT�SERVICE�REQUEST�WILL�FAIL�IF�THE�APPLICATION�DOES�NOTPROVIDE�VALID�IDENTIFIERS�FROM�A�PREVIOUS�#34!2OUTE2EQUEST%VENT��ACS(ANDLE��ROUTE2EGISTER2EQ)$��AND�ROUTING#ROSS2EF)$��4HEAPPLICATION�SHOULD�CHECK�THE�RETURN�VALUE�FOR�THIS�FUNCTION�AND�ANYRESULTING�UNIVERSAL�FAILURE�EVENT�FOR�ERRORS�


CSTA2OUTE3ELECT)NV��

The routing server application uses cstaRouteSelectInv to send a routingdestination to the switch in response to a CSTARouteRequestEvent for acall.

The invoke identifier parameter lets the application correlate the routeselection with a CSTAUniversalFailureConfEvent in the case of a failure.

TSAPI Version

!PPLICATIONS�USING�43!0)�6ERSION��MUST�USE�THE#34!2OUTE3ELECT��FUNCTION��APPLICATIONS�USING�ANY�OTHER�VERSIONMUST�USE�THE�#34!2OUTE3ELECT)NV��FUNCTION�

Syntax


2ET#ODE?T�CSTA2OUTE3ELECT)NV��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$� ��6ERSION��2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�$EVICE)$?T ROUTE3ELECTED�2ETRY6ALUE?T REMAIN2ETRY�3ET5P6ALUES?T SETUP)NFORMATION�"OOLEAN ROUTE5SED2EQ�0RIVATE$ATA?T PRIVATE$ATA�

Parameters


invokeID!�HANDLE�PROVIDED�BY�THE�APPLICATION�TO�BE�USED�FOR�MATCHING�ASPECIFIC�INSTANCE�OF�A�FUNCTION�SERVICE�REQUEST�WITH�ANY�RESULTING#34!5NIVERSAL&AILURE#ONF%VENT ��4HIS�PARAMETER�IS�ONLY�USEDWHEN�THE�)NVOKE�)$�MECHANISM�IS�SET�FOR�!PPLICATION GENERATED�)$SIN�THE�ACS/PEN3TREAM��4HE�PARAMETER�IS�IGNORED�BY�THE�!#3,IBRARY�WHEN�THE�3TREAM�IS�SET�FOR�,IBRARY GENERATED�INVOKE�)$S�



routingCrossRefID4HIS�PARAMETER�CONTAINS� THE�HANDLE� TO� THE�#34!�CALL� ROUTING�DIALOGFOR� THIS� CALL��4HE� APPLICATION� PREVIOUSLY� RECEIVED� THIS� HANDLE� IN� THE#34!2OUTE2EQUEST%VENT�FOR�THE�CALL�

routeSelected4HE�APPLICATION�PROVIDES�THIS�PARAMETER�CONTAINING�A�$EVICE�)$�THATSPECIFIES�THE�DESTINATION�FOR�THE�CALL�

remainRetry4HE�APPLICATION�INDICATES�THE�NUMBER�OF�TIMES�IT�IS�WILLING�TO�RECEIVEA�#34!2E2OUTE2EQUEST%VENT�FOR�THIS�CALL�IN�THE�CASE�THAT�THESWITCH�NEEDS�TO�REQUEST�AN�ALTERNATE�ROUTE��43!0)�PROVIDES��DEFINEVALUES�THAT�AN�APPLICATION�MAY�USE�TO�INDICATE�THAT�IT�DOES�NOT�KEEPCOUNT��OR�THAT�THERE�IS�NO�LIMIT�

setupInformation4HE�APPLICATION�PROVIDES�THIS�OPTIONAL�PARAMETER�THAT��CONTAINSINFORMATION�FOR�THE�)3$.�CALL�SETUP�MESSAGE�THAT�THE�SWITCH�WILL�USETO�ROUTE�THE�CALL��3OME�SWITCHES�MAY�NOT�SUPPORT�THIS�OPTION�

routeUsedReq4HE�ROUTING�APPLICATION�USES�THIS�PARAMETER�TO�REQUEST�A#34!2OUTE5SED%VENT�FOR�THE�CALL��4HE�ROUTE�USED�EVENT�INFORMSTHE�APPLICATION�OF�THE�FINAL�DESTINATION�OF�THE�CALL�ONCE�IT�HAS�BEENROUTED�



Return Values

CSTA2OUTE3ELECT)NV��RETURNS�THE�FOLLOWING�VALUES�DEPENDING�ONWHETHER�THE�APPLICATION�IS�USING�LIBRARY�OR�APPLICATION GENERATEDINVOKE�IDENTIFIERS�






There is no confirmation event for this service request, however thisservice request can generate a universal failure event.

Comments

!N�APPLICATION�SHOULD�CALL�CSTA2OUTE3ELECT)NV�ONLY�IN�RESPONSE�TO�A#34!2OUTE2EQUEST%VENT�OR�#34!2E2OUTE2EQUEST%VENT��4HECSTA2OUTE3ELECT)NV�SERVICE�REQUEST�WILL�FAIL�IF�THE�APPLICATION�DOESNOT�PROVIDE�VALID�IDENTIFIERS�FROM�A�PREVIOUS#34!2OUTE2EQUEST%VENT�OR�#34!2E2OUTE2EQUEST%VENT�ACS(ANDLE��ROUTE2EGISTER2EQ)$��AND�ROUTING#ROSS2EF)$��4HEAPPLICATION�SHOULD�CHECK�THE�RETURN�VALUE�FOR�THIS�FUNCTION�AND�ANYRESULTING�UNIVERSAL�FAILURE�EVENT�FOR�ERRORS�

.OTE


#34!2OUTE5SED%VENT

The CSTARouteUsed event provides a routing server application with theactual destination of a call for which the application previously sent acstaRouteSelect( ) or cstaRouteSelectInv( ). To receive a CSTARouteUsed,the application must set the cstaRouteSelect( ) or cstaRouteSelectInv( )parameter routeUsedReq to TRUE.

TSAPI Version

!PPLICATIONS�USING�43!0)�6ERSION��MUST�USE�THE#34!2OUTE5SED%VENT?T�STRUCTURE��APPLICATIONS�USING�ANY�OTHERVERSION�MUST�USE�THE�#34!2OUTE5SED%XT%VENT?T�STRUCTURE�

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

UNION[

#34!2OUTE5SED%VENT?T ROUTE5SED�

��VERSION��ONLY��#34!2OUTE5SED%XT%VENT?T ROUTE5SED%XT




43!0)�6ERSION��TYPEDEF�STRUCT[

2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�$EVICE)$?T ROUTE5SED�$EVICE)$?T CALLING$EVICE�"OOLEAN DOMAIN�

]�#34!2OUTE5SED%VENT?T�

43!0)�6ERSION��TYPEDEF�STRUCT[

2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�#ALLED$EVICE)$?T ROUTE5SED� �6ERSION��#ALLING$EVICE)$?T CALLING$EVICE� �6ERSION��"OOLEAN DOMAIN�

]�#34!2OUTE5SED%XT%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!%6%.42%0/24��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?2/54%?53%$��VERSION��OR#34!?2/54%?53%$?%84��VERSION��WHICH�IDENTIFIES�THISMESSAGE�AS�AN�#34!2OUTE5SED%VENT�



routingCrossRefID4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�#34!�CALL�ROUTING�DIALOGFOR�THIS�CALL��4HE�APPLICATION�PREVIOUSLY�RECEIVED�THIS�HANDLE�IN�THE#34!2OUTE2EQUEST%VENT�FOR�THE�CALL�ROUTE5SED��4HIS�PARAMETERIDENTIFIES�THE�SELECTED�AND�FINAL�DESTINATION�FOR�THE�CALL�

callingDevice4HIS�PARAMETER�CONTAINS�THE�ORIGINATING�DEVICE�OF�THE�CALL��I�E��THECALLING�PARTY�NUMBER��WHEN�AVAILABLE�

domain4HIS�PARAMETER�WILL�INDICATE�WHETHER�THE�CALL�HAS�LEFT�THE�SWITCHINGDOMAIN�ACCESSIBLE�TO�THE�4ELEPHONY�3ERVER��THE�3ERVER)$�DEFINED�INTHE�ACTIVE�ACS(ANDLE��4YPICALLY��A�CALL�LEAVES�A�SWITCHING�DOMAINWHEN�IT�IS�ROUTED�TO�A�TRUNK�CONNECTED�TO�ANOTHER�SWITCH�OR�TO�THE�PUB LIC�SWITCHED�NETWORK�

privateData)F�PRIVATE�DATA�ACCOMPANIES�#34!2OUTE5SED%VENT��THEN�THE�PRIVATEDATA�WOULD�BE�STORED�IN�THE�LOCATION�THAT�THE�APPLICATION�SPECIFIED�ASTHE�PRIVATE$ATA�PARAMETER�IN�THE�ACS'ET%VENT"LOCK��OR�ACS'ET% VENT0OLL��REQUEST��)F�THE�PRIVATE$ATA�POINTER�IS�SET�TO�.5,,�INTHESE�REQUESTS��THEN�#34!2OUTE5SED%VENT�DOES�NOT�DELIVER�PRIVATEDATA�TO�THE�APPLICATION�

Comments

!N�APPLICATION�USES�#34!2OUTE5SED%VENT�TO�DETERMINE�THE�FINALDESTINATION�OF�A�CALL�THAT�IT�ROUTED�USING�THE�CSTA2OUTE3ELECT��ORCSTA2OUTE3ELECT)NV��3WITCH�FEATURES�SUCH�AS�FORWARDING�OR�ROUTINGTABLES�MAY�DIRECT�THE�CALL�TO�A�DEVICE�OTHER�THAN�THE�APPLICATIONSUPPLIED�DESTINATION��4HE�#34!2OUTE5SED%VENT�INDICATES�THE�FINALDESTINATION�FOR�THE�CALL�


#34!2OUTE%ND%VENT

The switch sends CSTARouteEndEvent to terminate a routing dialog. Theevent includes a cause value giving the reason for the dialog termination.

Note that when an application wishes to terminate a routing interaction, itshould use CSTARouteEnd( ) (version 1) or CSTARouteEndInv( )(version 2).

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

UNION[

#34!2OUTE%ND%VENT?T��ROUTE%ND�]�U�

]�CSTA%VENT2EPORT�]�EVENT�

]�#34!%VENT?T�

TYPEDEF�STRUCT[

2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�#34!5NIVERSAL&AILURE?T ERROR6ALUE�

]�#34!2OUTE%ND%VENT?T�


Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�OPENED�!#3�3TREAM�ON�WHICH�ROUTINGDIALOG�IS�ENDING�

eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!%6%.42%0/24��WHICHIDENTIFIES�THIS�MESSAGE�AS�A�#34!�UNSOLICITED�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?2/54%?%.$��WHICH�IDENTIFIESTHIS�MESSAGE�AS�A�#34!2OUTE%ND%VENT�


routingCrossRefID4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�#34!�CALL�ROUTING�DIALOGFOR�THIS�CALL��4HE�APPLICATION�PREVIOUSLY�RECEIVED�THIS�HANDLE�IN�THE#34!2OUTE2EQUEST%VENT�FOR�THE�CALL�

errorValue4HIS�PARAMETER�CONTAINS�A�CAUSE�CODE�WHICH�GIVING�THE�REASON�WHYTHE�ROUTING�DIALOG�ENDED�

privateData)F�PRIVATE�DATA�ACCOMPANIES�#34!2OUTE%ND%VENT��THEN�THE�PRIVATEDATA�WOULD�BE�STORED�IN�THE�LOCATION�THAT�THE�APPLICATION�SPECIFIED�ASTHE�PRIVATE$ATA�PARAMETER�IN�THE�ACS'ET%VENT"LOCK��OR�ACS'ET% VENT0OLL��REQUEST��)F�THE�PRIVATE$ATA�POINTER�IS�SET�TO�.5,,�INTHESE�REQUESTS��THEN�#34!2OUTE%ND%VENT�DOES�NOT�DELIVER�PRIVATEDATA�TO�THE�APPLICATION�

Comments

4HE�SWITCH�SENDS�#34!2OUTE%ND%VENT�WHEN�A�CALL�HAS�BEEN�SUC CESSFULLY�ROUTED��CLEARED��OR�WHEN�THE�ROUTING�SERVER�HAS�FAILED�TO�PRO VIDE�A�ROUTE�SELECT�WITHIN�THE�SWITCH�S�TIME�LIMIT��4HIS�EVENT�ISUNSOLICITED�AND�CAN�OCCUR�AT�ANY�TIME�



CSTA2OUTE%ND��43!0)�6ERSION��/NLY

A routing application uses cstaRouteEnd( ) to cancel an active routing dialogfor a call. The service request includes a cause value giving the reason for therouting dialog termination. Note that when the switch terminates an activerouting dialog, it uses cstaRouteEndEvent.

TSAPI Version

!PPLICATIONS�USING�43!0)�6ERSION��MUST�USE�THE#34!2OUTE%ND��FUNCTION��APPLICATIONS�USING�ANY�OTHER�VERSIONMUST�USE�THE�#34!2OUTE%ND)NV��FUNCTION�

Syntax


2ET#ODE?T�CSTA2OUTE%ND��!#3(ANDLE?T ACS(ANDLE�2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�#34!5NIVERSAL&AILURE?T ERROR6ALUE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�OPENED�!#3�3TREAM�ON�WHICH�THE�APPLICA TION�IS�TERMINATING�A�ROUTING�DIALOG�FOR�A�CALL�


routingCrossRefID4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�#34!�CALL�ROUTING�DIALOGFOR�A�CALL��4HE�APPLICATION�PREVIOUSLY�RECEIVED�THIS�HANDLE�IN�THE#34!2OUTE2EQUEST%VENT�FOR�THE�CALL��4HIS�IS�THE�ROUTING�DIALOGTHAT�THE�APPLICATION�IS�ENDING�


errorValue4HE�APPLICATION�SUPPLIES�THIS�CAUSE�CODE�GIVING�THE�REASON�WHY�IT�ISENDING�THE�ROUTING�DIALOG�


Return Values

CSTA2OUTE%ND��RETURNS�A�NON NEGATIVE�VALUE�WHEN�SUCCESSFUL�




Comments

!�ROUTING�APPLICATION�CAN�USE�CSTA2OUTE%ND��WHEN�IT�CANNOT�ROUTEA�CALL��4HIS�CAN�OCCUR�IF�

u the application receives a routing request for a call withoutsufficient call information and it cannot determine a routingdestination.

u the application has already routed calls to all availabledestinations and those calls remain active at thosedestinations.

u the application does not have access to a database necessaryto route the call

)N�THESE�CASES��THE�APPLICATION�USES�CSTA2OUTE%ND��TO�INFORM�THESWITCH�THAT�IT�WILL�NOT�ROUTE�THE�CALL�IN�QUESTION��CSTA2OUTE%ND��WILLTERMINATE�THE�#34!�ROUTING�DIALOG��ROUTING#ROSS2EF)$�FOR�THE�CALL�CSTA2OUTE%ND��DOES�NOT�CLEAR�THE�CALL��4HE�SWITCH�WILL�CONTINUE�TOPROCESS�THE�CALL�USING�WHATEVER�DEFAULT�ROUTING�ALGORITHM�IS�AVAILABLE�IMPLEMENTATION�SPECIFIC�

.OTE�THAT�WHEN�THE�SWITCH�TERMINATES�AN�ACTIVE�ROUTING�DIALOG��IT�USESCSTA2OUTE%ND%VENT �


CSTA2OUTE%ND)NV��

4HE�ROUTING�SERVER��APPLICATION�USES�CSTA2OUTE%ND��TO�CANCEL�ANACTIVE�ROUTING�DIALOG�FOR�A�CALL��4HE�SERVICE�REQUEST�INCLUDES�A�CAUSEVALUE�GIVING�THE�REASON�FOR�THE�ROUTING�DIALOG�TERMINATION��.OTE�THATWHEN�THE�SWITCH�TERMINATES�AN�ACTIVE�ROUTING�DIALOG��IT�USESCSTA2OUTE%ND%VENT �

TSAPI Version

!PPLICATIONS�USING�43!0)�6ERSION��MUST�USE�THE#34!2OUTE%ND��FUNCTION��APPLICATIONS�USING�ANY�OTHER�VERSIONMUST�USE�THE�#34!2OUTE%ND)NV��FUNCTION�

Syntax


2ET#ODE?T�CSTA2OUTE%ND��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$� ��6ERSION��2OUTE2EGISTER2EQ)$?T ROUTE2EGISTER2EQ)$�2OUTING#ROSS2EF)$?T ROUTING#ROSS2EF)$�#34!5NIVERSAL&AILURE?T ERROR6ALUE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters

acsHandle4HIS�IS�THE�HANDLE�FOR�THE�OPENED�!#3�3TREAM�ON�WHICH�THE�APPLICA TION�IS�TERMINATING�A�ROUTING�DIALOG�FOR�A�CALL�

invokeID!�HANDLE�PROVIDED�BY�THE�APPLICATION�TO�BE�USED�FOR�MATCHING�ASPECIFIC�INSTANCE�OF�A�FUNCTION�SERVICE�REQUEST�WITH�ANY�RESULTING#34!5NIVERSAL&AILURE#ONF%VENT ��4HIS�PARAMETER�IS�ONLY�USEDWHEN�THE�)NVOKE�)$�MECHANISM�IS�SET�FOR�!PPLICATION GENERATED�)$SIN�THE�ACS/PEN3TREAM��4HE�PARAMETER�IS�IGNORED�BY�THE�!#3,IBRARY�WHEN�THE�3TREAM�IS�SET�FOR�,IBRARY GENERATED�INVOKE�)$S�



routingCrossRefID4HIS�PARAMETER�CONTAINS�THE�HANDLE�TO�THE�#34!�CALL�ROUTING�DIALOGFOR�A�CALL��4HE�APPLICATION�PREVIOUSLY�RECEIVED�THIS�HANDLE�IN�THE#34!2OUTE2EQUEST%VENT�FOR�THE�CALL��4HIS�IS�THE�ROUTING�DIALOGTHAT�THE�APPLICATION�IS�ENDING�

errorValue4HE�APPLICATION�SUPPLIES�THIS�CAUSE�CODE�GIVING�THE�REASON�WHY�IT�ISENDING�THE�ROUTING�DIALOG�


Return Values

CSTA2OUTE%ND)NV��RETURNS�THE�FOLLOWING�VALUES�DEPENDING�ONWHETHER�THE�APPLICATION�IS�USING�LIBRARY�OR�APPLICATION GENERATEDINVOKE�IDENTIFIERS�







Comments

!�ROUTING�SERVER�APPLICATION�CAN�USE�CSTA2OUTE%ND)NV��WHEN�ITCANNOT�ROUTE�A�CALL��4HIS�CAN�OCCUR�IF�

u the application receives a routing request for a call withoutsufficient call information and it cannot determine a routingdestination.

u the application has already routed calls to all availabledestinations and those calls remain active at thosedestinations.

u the application does not have access to a database necessaryto route the call

In these cases, the application uses cstaRouteEnd( ) to inform the switch thatit will not route the call in question. cstaRouteEnd( ) will terminate the CSTArouting dialog (routingCrossRefID) for the call. cstaRouteEnd( ) does notclear the call. The switch will continue to process the call using whateverdefault routing algorithm is available (implementation specific).

An application can use this function to respond to either a route request or are-route request.

Note that when the switch terminates an active routing dialog, it usescstaRouteEndEvent.



C h a p t e r 9 Escape and MaintenanceServices

This chapter describes the CSTA Escape and Maintenance Services.

%SCAPE�3ERVICES

Switching domains use Escape Services to enhance TSAPI functions with"private" services which are specific to the switch or PBX Driverimplementation (see Section 2.3). Each switch vendor may define functionswithin the CSTA private services framework, even though CSTA does notincorporate these services. Although the functions defined within escapeservices can vary from one implementation to the next, the way the applicationaccesses these functions is consistent. Escape Services use the sameprogramming model as all other CSTA services. Figure 9-18 illustrates thismodel.


When an application requests an escape service from a server it receives aconfirmation event or a Universal Failure in the same fashion as for otherTSAPI services. The Escape Service request parameters are an acsHandle (tothe open stream), an invokeID and a private data parameter. The confirmationevent includes the acsHandle, the invokeID, and the private data response.

Escape Services also includes an unsolicited private event which a server cansend to an application at any time a CSTA monitor association exists on aCSTA call or device object (see Section 6 - cstaMonitorStart( )).

Figure 9-18Escape Services Model

%SCAPE�3ERVICE2EQUEST

%SCAPE�3ERVICE2ESPONSE

%SCAPE�3ERVICE5NSOLICITED�%VENT

!PPLICATION�CLIENT

0"8�$RIVER3WITCHING�$OMAIN)MPLEMENTATION

�SERVER

Applications can also send Escape Services requests to a switch. For mostCSTA services the application is always a client in the computing domain.However, an escape service could operate in the opposite direction (such asrouting does). Although the client/server role may change, services are alwaysuni-directional where either the switch or application is always the requesterfor a service.


TSAPI includes escape service definitions for both the "Application as the Cli-ent" and the "Switch as the Client".

See vendor specific documentation for more information on what, if any, Es-cape Services are supported by a specific vendor. Escape Service Functionsare generally not portable across different vendor implementations. Someimplementations may support Escape Services either bi-directionally or uni-directionally (one-way only) depending on the needs and capabilities of theswitch driver

.OTE


-AINTENANCE�3ERVICES

There are two different types of CSTA maintenance services:

u device status maintenance events which provide status information fordevice objects, and

u bi-directional system status maintenance services which provideinformation on the overall status of the system.

The device status events inform the application when the switch places amonitored device in or out of service. When a device object is removed fromservice, the application may monitor the device (e.g. cstaMonitorStart( ) orcstaDevSnapshotReq( )) but may not request services for that device. For ex-ample, an application request for a cstaMakeCall( ) returns an error when thedevice is out of service.

System Status services inform applications or switches about the status of theswitching or computing domains, respectively. Table 9-3 shows the SystemStatus Services’ system status information (cause codes).


Table 9-3System Status Cause Codes

System Status

Cause Code

Cause Code Definitions

Initializing the system is re-initializing or restarting. This status indicatesthat the system is temporarily unable to respond to anyrequests. If provided, this status message shall be followedby an Enable status message that indicates that theinitialization process is completed.

Enabled request and responses are enabled, usually after a disruptionor restart. This status indication shall be sent after aninitializing status indicator has been sent and my be sentunder other conditions. This status indicates that there are nooutstanding monitor requests.

Normal a System Status Event with this cause value can be sent atany time to indicate that the status is normal. This status hasno effect on other services.

Message Lost this status indicates that a request, response, or event reportmay have been lost.

Disabled this cause value indicates that active cstaMonitorStart( )monitor requests via have been disabled. Other requests andresponses may also be disabled, but, unlike monitors, rejectresponses are provided for those.

Overload Imminent the system (driver, switch, or application) is about to reach anoverload condition. The "client" should shed load to remedythe situation.

Overload Reached the system (driver, switch, or application) has reached anoverload condition and may take action to shed load. Theserver (the application, driver, or switch) may then take actionto decrease message traffic. This may include stoppingexisting monitors or rejecting any new requests sent by theclient.

Overload Relieved the system (driver, switch, or application) has determined thatthe overload condition has passed and normal applicationoperation may resume.


The System Status services are bi-directional and thus can originate at the ap-plication domain or at the driver/switch domain. Figure 9-19 shows SystemStatus Maintenance Services.

Figure 9-19System Status Maintenance Services

3YSTEM�3TATUS�3ERVICE2EQUEST

3YSTEM�3TATUS�3ERVICE2ESPONSE

3YSTEM�3TATUS�3ERVICE5NSOLICITED�%VENT

!PPLICATION�CLIENT�OR�SERVERDEPENDING�ONDIRECTION�OF�REQUEST

0"8�$RIVER3WITCHING�$OMAIN)MPLEMENTATION�SERVER�OR�CLIENTDEPENDING�ONDIRECTION�OF�REQUEST

An application can obtain System Status information in one of two differentways :

u the client can ask for the information using a request to the "server" andobtain the information in a confirmation event, or


u the client can register for System Status messages and receiveunsolicited events containing system status changes.

A switch or application may issue the System Status request(cstaSysStatReq( )) to obtain status information from the "server" (the appli-cation or switch, respectively, depending on the direction of the request). ASystem Status response (CSTASysStatReqConfEvent) provides the "client"with the current system status information for the "server". The "server" maysend unsolicited events the client if the client used the cstaSysStatStart( )service to register for System Status events. The System Status unsolicitedevent (CSTASysStatEvent) is the same in structure as the confirmation event(CSTASysStatReqConfEvent) except that the "server" sends it to the "client"automatically.


%SCAPE�3ERVICES��!PPLICATION�AS�#LIENT

This section defines escape services for situation where the application is theservice requester in the client/server relationship (see Figure 9-18). Theservices include an escape service request, a confirmation event to the request,and an unsolicited escape service event that originates at the driver orswitching domain.


CSTA%SCAPE3ERVICE��

This service allows the application to request a service which is not defined bythe CSTA Standard but rather by a switch vendor. A service request made bythis function will be specific to an implementation.

Syntax


2ET#ODE?T��CSTA%SCAPE3ERVICE��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�0RIVATE$ATA?T PRIVATE$ATA�

Parameters


invokeID!�HANDLE�PROVIDED�BY�THE�APPLICATION�TO�BE�USED�FOR�MATCHING�A�SPE CIFIC�INSTANCE�OF�A�FUNCTION�SERVICE�REQUEST�WITH�ITS�ASSOCIATED�CONFIR MATION�EVENT��4HIS�PARAMETER�IS�ONLY�VALID�WHEN�THE�)NVOKE�)$MECHANISM�IS�SET�FOR�!PPLICATION GENERATED�)$S�IN�THE�ACS/PEN 3TREAM��4HE�PARAMETER�IS�IGNORED�BY�THE�!#3�,IBRARY�WHEN�THE3TREAM�IS�SET�FOR�,IBRARY GENERATED�INVOKE�)$S�

privateData4HIS�IS�A�POINTER�TO�THE�#34!�PRIVATE�DATA�EXTENSION�MECHANISM�4HIS�PARAMETER�IN�./4�OPTIONAL�FOR�THIS�FUNCTION�AND�MUST�BE�PASSEDBY�THE�APPLICATION��)F�THE�PARAMETER�IS�.5,,�AN�ERROR�WILL�BE�RETURNEDTO�THE�APPLICATION�AND�THE�!0)�#LIENT�,IBRARY�$RIVER�WILL�REJECT�THESERVICE�REQUEST�

Return Values


,IBRARY GENERATED�)DENTIFIERS� �IF�THE�FUNCTION�CALL�COMPLETESSUCCESSFULLY�IT�WILL�RETURN�A�POSITIVE�VALUE��I�E��THE�INVOKE


IDENTIFIER��)F�THE�CALL�FAILS�A�NEGATIVE�ERROR��CONDITION�WILLBE�RETURNED��&OR�LIBRARY GENERATED�IDENTIFIERS�THE�RETURN�WILLNEVER�BE�ZERO��


4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE#34!%SCAPE3ERVICE#ONF%VENT�MESSAGE�TO�INSURE�THAT�THE�SERVICEREQUEST�HAS�BEEN�ACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY3ERVER�AND�THE�SWITCH�



!#3%22?./#/..4HIS�RETURN�VALUE�INDICATES�THAT�A�PREVIOUSLY�ACTIVE�!#33TREAM�HAS�BEEN�ABNORMALLY�ABORTED�

!#3%22?2%1$%.)%$4HIS�RETURN�VALUE�INDICATES�THAT�A�!#3�3TREAM�IS�ESTABLISHEDBUT�A�REQUESTED�CAPABILITY�HAS�BEEN�DENIED�BY�THE�#LIENT�,I BRARY�3OFTWARE�$RIVER�

!#3%22?.5,,0!2!-%4%24HIS�ERROR�INDICATES�THAT�THE�POINTER�TO�THE�#34!�0RIVATE$ATA�INFORMATION�IS�.5,,�AND�THUS�NO�PRIVATE�DATA�ISAVAILABLE�TO�SEND�TO�THE�DRIVER�SWITCH��.O�ACTION�IS�TAKEN�BYTHE�!0)�#LIENT�,IBRARY�$RIVER�

Comments

4HIS�FUNCTION�IS�USED�TO�SEND�PRIVATE�DATA�INFORMATION�TO�THEDRIVER�SWITCH�


#34!%SCAPE3ERVICE#ONF%VENT

This confirmation event is sent in response to the cstaEscapeService( )service and provides the positive acknowledgment to the request. The eventincludes any private information that is to be provided as part of aconfirmation event to the service request.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$�]�CSTA#ONFIRMATION�


Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICH��IDENTI FIES��THIS�MESSAGE�AS�AN�#34!�CONFIRMATION�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?%3#!0%?3%26)#%?#/.&WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN#34!%SCAPE3ERVICE#ONF%VENT�




Comments

4HIS�EVENT�ALWAYS�OCCURS�AS�A�RESULT�OF�A�NORMAL��POSITIVE�SERVICE�RE QUEST�MADE�THROUGH�THE�CSTA%SCAPE3ERVICE��SERVICE��4HE�INFORMA TION�CONTAINED�IN�THE�PRIVATE$ATA�PARAMETER�IS�IMPLEMENTATION�SPE CIFIC�


#34!0RIVATE%VENT

This event report allows for unsolicited, implementation specific eventreporting. The informational contents of this event will be defined by aspecific implementation.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

UNION[

#34!0RIVATE%VENT?T��PRIVATE$ATA�]�U�


]�#34!%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!%6%.42%0/24��WHICH��IDENTI FIES��THIS�MESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?02)6!4%��WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!0RIVATE%VENT�


monitorCrossRefID$OES�NOT�APPLY�TO�THIS�EVENT�

privateData)F�PRIVATE�DATA�ACCOMPANIED�THIS�EVENT��THEN�THE�PRIVATE�DATA�WOULD�BECOPIED�TO�THE�LOCATION�POINTED�TO�BY�THE�PRIVATE$ATA�POINTER�IN�THEACS'ET%VENT"LOCK��OR�ACS'ET%VENT0OLL��FUNCTION��)F�THE�PRIVATE $ATA�POINTER�IS�SET�TO�.5,,�IN�THESE�FUNCTIONS��THEN�NO�PRIVATE�DATAWILL�BE�DELIVERED�TO�THE�APPLICATION�

Comments

4HIS�EVENT�IS�TYPICALLY�USED�FOR�PROVIDING�UNSOLICITED��IMPLEMENTATIONSPECIFIC�EVENT�INFORMATION��4HIS�EVENT�CAN�OCCUR�AT�ANY�TIME�AND�DOESNOT�HAVE�BE�SPECIFIC�TO�A�MONITORED�OBJECT��4HE�EVENT�CAN�BE�SENT�BYTHE�DRIVER�SWITCH�EVEN�THOUGH�THE�APPLICATION�DOES�NOT�HAVE�AMONITORED�OBJECT��7HEN�A�MONITOR�EXISTS��THE�0RIVATE3TATUS%VENT �ISUSED�BY�THE�DRIVER�SWITCH�TO�SEND�PRIVATE�STATUS�INFORMATIONPERTAINING�TO�A�MONITORED�OBJECT��4HE�0RIVATE%VENT�IS�USED�FOR�ALLOTHER�CASES�OF�UNSOLICITED�PRIVATE�EVENTS�AND�IS�NOT�ASSOCIATED�WITH�AMONITORING�ASSOCIATION�


#34!0RIVATE3TATUS%VENT

This event report allows for unsolicited, implementation specific eventreporting for a monitored object. The informational contents of this event willbe defined by a specific implementation.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

#34!-ONITOR#ROSS2EF)$?TMONITOR#ROSS2EF)$�]�CSTA5NSOLICITED�


Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?02)6!4%?34!453��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!0RIVATE3TATUS%VENT�




Comments

4HIS�EVENT�IS�TYPICALLY�USED�FOR�PROVIDING�IMPLEMENTATION�SPECIFICEVENT�INFORMATION�WHICH�IS�NOT�DEFINED�IN�ANY�OTHER�EVENT�IN�THE�!0)�4HE�EVENT�IS�ALWAYS�USED�FOR�PRIVATE�INFORMATION�ON�A�MONITORING�AS SOCIATION��!�MONITOR�MUST�BE�ACTIVE�;CSTA-ONITOR$EVICE ��CSTA-ONITOR#ALL��CSTA-ONITOR#ALLS6IA$EVICE ��=�BEFORE�THISEVENT�CAN�BE�SENT�TO�THE�APPLICATION�BY�THE�DRIVER�SWITCH��4HIS�EVENT�ISALWAYS�SENT�FROM�THE�DRIVER�SWITCH�TO�THE�APPLICATION�AND�IT�IS�NOT�BI DIRECTIONAL�


%SCAPE�3ERVICE��$RIVER�3WITCH�AS�THE�#LIENT

This section defines escape services for cases where the Driver/Switch is theservice requester in the client/server relationship (see Figure 9-1). The servicesinclude an escape service request event, a confirmation function for therequest, and an unsolicited escape service event that originates at theapplication domain.


#34!%SCAPE3ERVICE2EQ

This unsolicited event is sent by the driver/switch to request a private servicefrom the application. The event includes the service request as privateinformation for which the application must provide a positive or negativeacknowledgment.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!%SCAPE3VC2EQ%VENT?TESCAPE3VC2EQEUST�



Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!2%15%34��WHICH��IDENTIFIES��THISMESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�


eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?%3#!0%?36#?2%1��WHICHIDENTIFIES��THIS�MESSAGE�AS�AN�#34!%SCAPE3ERVICE2EQ

invokeID4HIS�PARAMETER�DEFINES�THE�INVOKE�IDENTIFIER�SELECTED�BY�THEDRIVER�SWITCH�FOR�THE�SPECIFIC�PRIVATE�REQUEST��4HIS�PARAMETER�MUST�BERETURNED��UNCHANGED��IN�THE�RESPONSE�TO�THIS�REQUEST�IN�ORDER�FOR�THEDRIVER�SWITCH�TO�MATCH�A�SERVICE�REQUEST�WITH�A�SERVICE�RESPONSE�


Comments

4HIS�EVENT�IS�SENT�BY�THE�DRIVER�SWITCH�TO�REQUEST�AN�ESCAPE�OR�PRIVATESERVICE�WHEN�THE�APPLICATION�IS�PROVIDING�THE��SERVER��FUNCTION�IN�THECLIENT�SERVER�RELATIONSHIP��4HE�RESPONSE�TO�THIS�EVENT�WILL�BE�ACCOM PLISHED�VIA�THE�CSTA%SCAPE3ERVICE#ONF��SERVICE�


CSTA%SCAPE3ERVICE#ONF��

This service allows the application to respond to a CSTAEscapeServiceEventwhich originated at the driver/switch. A service response made by thisfunction will be specific to an implementation.

Syntax


2ET#ODE?T��CSTA%SCAPE3ERVICE#ONF��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�#34!5NIVERSAL&AILURE?T ERROR� ��NEGATIVE�!#+��0RIVATE$ATA?T PRIVATE$ATA� ��POSITIVE�!#+��

Parameters


invokeID4HE�INVOKE�IDENTIFIER�USED�IN�THIS�FUNCTION�MUST�BE�THE�SAME�VALUE�UNCHANGED�AS�THAT�PROVIDED�IN�THE�#34!%SCAPE3ERVICE2EQ�FORWHICH�THIS�SERVICES�REQUEST�IS�BEING�CALLED��4HE�SAME�INVOKE)$�VALUEMUST�BE�USED�IN�ORDER�FOR�THE�DRIVER�SWITCH�TO�MATCH�THE�INSTANCES�OF�APREVIOUS�SERVICE�EVENT�AND�THE�SERVICE�CONFIRMATION�TO�THAT�EVENT�PRO VIDED�BY�THIS�FUNCTION�CALL�

error4HIS�PARAMETER�IS�USED�TO�PROVIDE�A�NEGATIVE�ACKNOWLEDGMENT�TO�THE#34!%SCAPE3ERVICE2EQ��3EE�#34!5NIVERSAL&AILURE#ONF%VENTFOR�A�DEFINITION�OF�THE�POSSIBLE�ERROR�VALUES�FOR�THIS�PARAMETER��)F�THEERROR�POINTER�IS�.5,,�THIS�WILL�INDICATES�THAT�THE�EVENT�CONTAINS�APOSITIVE�ACKNOWLEDGMENT�

privateData4HIS�IS�A�POINTER�TO�THE�#34!�PRIVATE�DATA�EXTENSION�MECHANISMWHICH�CONTAINS�THE�POSITIVE�ACKNOWLEDGMENT�TO�THE#34!%SCAPE3ERVICE%VENT��)F�THE�PRIVATE�POINTER�IS�.5,,�THIS�WILLINDICATE�THAT�THE�EVENT�CONTAINS�A�NEGATIVE�ACKNOWLEDGMENT�


Return Values

4HIS�FUNCTION�NEVER�RETURNS�AN�INVOKE�IDENTIFIER�SINCE�THERE�IS�NO�CON FIRMATION�EVENT�FOR�THIS�SERVICE��4HE�FUNCTION�DOES�RETURN�ERRORSCONDITIONS�DURING�THE�PROCESSING�OF�THE�REQUEST�BY�THE�!0)�#LIENT,IBRARY��!�RETURN�VALUE�OF�ZERO��INDICATES�THAT�THE�REQUEST�HAS�BEENACCEPTED�BY�THE�,IBRARY��4HIS�FUNCTION�NEVER�RETURNS�A�POSITIVE�VALUE�





!#3%22?./.5,,4HIS�ERROR�INDICATES�THAT�NEITHER�THE�ERROR�OR�PRIVATE$ATAPOINTERS�ARE�.5,,��/NE�OF�THESE�POINTERS�MUST�BE�.5,,�TOINDICATE�EITHER�A�POSITIVE�OR�NEGATIVE�ACKNOWLEDGMENT�TO�THEREQUEST��.O�ACTION�IS�TAKEN�BY�THE�!0)�#LIENT�,IBRARY�

!#3%22?./2%30/.3%4HIS�ERROR�INDICATES�THAT�BOTH�THE�ERROR�OR�THE�PRIVATE$ATAPOINTER�ARE�.5,,��)N�THIS�CASE�THE�!0)�#LIENT�,IBRARY�HASNOTHING�TO�SEND�TO�THE�DRIVER�SWITCH�AND�REJECTS�THE�RESPONSE�4HE�REQUEST�ASSOCIATED�WITH�THE�INVOKE�IDENTIFIER�FROM�THEDRIVER�SERVER�WILL�STILL�BE�OUTSTANDING�AND�THE�APPLICATIONMUST�RESPOND�BY�CALLING�THIS�FUNCTION�WITH�ACCEPTABLEPARAMETERS�

!#3%22?"!$).6/+%)$4HIS�ERROR�INDICATES�THAT�THE�INVOKE�IDENTIFIER�BEING�RETURNEDBY�THE�APPLICATION�IS�NOT�ONE�THAT�IS�OUTSTANDING�FROM�THEDRIVER�SWITCH��4HE�!0)�#LIENT�,IBRARY�WILL�KEEP�TRACK�OF�THEDRIVER�SWITCH BASED�INVOKE�ID�S�UNTIL�THE�APPLICATIONRESPONDS�TO�THE�SPECIFIC�REQUEST�FROM�THE�DRIVER�SWITCH�


Comments

4HIS�FUNCTION�IS�USED�TO�SEND�A�RESPONSE�TO�A�PRIVATE�REQUEST�FROM�THEDRIVER�SWITCH��4HE�EVENT�SUPPORTS�BOTH�A�POSITIVE�AND�NEGATIVE�AC KNOWLEDGMENT�TO�THE�REQUEST��/NE�OF�THE�TWO�POINTERS��ERROR�OR�PRI VATE$ATA�MUST�BE�.5,,�IN�ORDER�FOR�THE�REQUEST�TO�BE�SUCCESSFULLYPROCESSED�BY�THE�!0)�#LIENT�,IBRARY��4HIS�WOULD�INDICATE�A�POSITIVEOR�NEGATIVE�ACKNOWLEDGMENT�TO�THE�REQUEST�MADE�BY�THEDRIVER�SWITCH�


CSTA3END0RIVATE%VENT��

This service allows the application to send an unsolicited private event to thedriver/switch. An event sent by this function will be specific to animplementation.

Syntax


2ET#ODE?T��CSTA3END0RIVATE%VENT��!#3(ANDLE?T ACS(ANDLE�0RIVATE$ATA?T PRIVATE$ATA�

Parameters


privateData4HIS�IS�A�POINTER�TO�THE�#34!�PRIVATE�DATA�EXTENSION�MECHANISM�4HIS�PARAMETER�IN�./4�OPTIONAL�FOR�THIS�FUNCTION�AND�MUST�BE�PASSEDBY�THE�APPLICATION��)F�THE�PARAMETER�IS�.5,,�AN�ERROR�WILL�BE�RETURNEDTO�THE�APPLICATION�AND�THE�!0)�#LIENT�,IBRARY�$RIVER�WILL�REJECT�THESERVICE�REQUEST�

Return Values

4HIS�FUNCTION�NEVER�RETURNS�AN�INVOKE�IDENTIFIER�SINCE�THERE�IS�NO�CON FIRMATION�EVENT�FOR�THIS�SERVICE��4HE�FUNCTION�DOES�RETURN�ERRORSCONDITIONS�DURING�THE�PROCESSING�OF�THE�REQUEST�BY�THE�!0)�#LIENT,IBRARY��!�RETURN�VALUE�OF�ZERO��INDICATES�THAT�THE�REQUEST�HAS�BEENACCEPTED�BY�THE�,IBRARY��4HIS�FUNCTION�NEVER�RETURNS�A�POSITIVE�VALUE�






!#3%22?.5,,0!2!-%4%24HIS�ERROR�INDICATES�THAT�THE�POINTER�TO�THE�#34!�0RIVATE$ATA�INFORMATION�IS�.5,,�AND�THUS�NO�PRIVATE�DATA�ISAVAILABLE�TO�SEND�TO�THE�DRIVER�SWITCH��.O�ACTION�IS�TAKEN�BYTHE�!0)�#LIENT�,IBRARY�$RIVER�

Comments

4HIS�FUNCTION�IS�USED�TO�SEND�UNSOLICITED��PRIVATE�DATA�INFORMATION�TOTHE�DRIVER�SWITCH�WHEN�THE�APPLICATION�IS�SUPPORTING�THE��SERVER��ROLEIN�THE�CLIENT�SERVER�RELATIONSHIP�


-AINTENANCE�3ERVICES��$EVICE�3TATUS

This section describes the CSTA Maintenance Services which provide devicestatus information. To receive device status information, an application mustmonitor the device(e.g. the application must have an activemonitorCrossRefID for the device). These events are unidirectional andalways originate in the switch domain.


#34!"ACK)N3ERVICE%VENT

This event report indicates that a monitored device object has returned toservices and operates normally.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

#34!-ONITOR#ROSS2EF)$?TMONITOR#ROSS2EF)$�

UNION[

#34!"ACK)N3ERVICE%VENT?TBACK)N3ERVICE�

]�U�]�CSTA5NSOLICITED�


TYPEDEF�STRUCT[

$EVICE)$?T DEVICE�#34!%VENT#AUSE?T CAUSE�

]�#34!"ACK)N3ERVICE%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!5.3/,)#)4%$��WHICH�IDENTIFIESTHIS�MESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�


eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?"!#+?).?3%26)#%��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�#34!"ACK)N3ERVICE%VENT�


device3PECIFIES�THE�DEVICE�WHICH�IS�BACK�IN�SERVICE��)F�THE�DEVICE�IS�NOTSPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THAT�THE�DEVICE�WAS�NOTKNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

cause4HIS�PARAMETER�INDICATES�THE�REASON�OR�EXPLANATION�FOR�THE�OCCURRENCEOF�THIS�EVENT��3EE�3ECTION��FOR�MORE�INFORMATION�


Comments

4HIS�EVENT�INDICATES�THAT�A�PREVIOUSLY�INACTIVE�DEVICE��A�DEVICE�WHICHIS�OUT�SERVICE�HAS�RESUMED�NORMAL�OPERATION��/NCE�THIS�EVENT�HAS�OC CURRED�THE�APPLICATION�CAN�THEN�INITIATE�AN�ACTIVE�SERVICE�REQUEST��E�G�CSTA-AKE#ALL��FOR�THAT�SPECIFIC�DEVICE��!�PASSIVE�SERVICE�REQUESTCAN�BE�DONE�WHILE�A�DEVICE�IS�OUT�OF�SERVICE��I�E��MONITORING�OR�3NAP SHOT�3ERVICES�


#34!/UT/F3ERVICE%VENT

This event report indicates that a monitored device object has entered amaintenance state and can no longer accept calls or be actively manipulated bythe application.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

#34!-ONITOR#ROSS2EF)$?TMONITOR#ROSS2EF)$�

UNION[

#34!/UT/F3ERVICE%VENT?TOUT/F3ERVICE�

]�U�]�CSTA5NSOLICITED�


TYPEDEF�STRUCT[

$EVICE)$?T DEVICE�#34!%VENT#AUSE?T CAUSE�

]�#34!/UT/F3ERVICE%VENT?T�

Parameters



eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!5.3/,)#)4%$��WHICH�IDENTIFIESTHIS�MESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?/54?/&?3%26)#%��WHICHIDENTIFIES�THIS�MESSAGE�AS�AN�#34!/UT/F3ERVICE%VENT�


device4HIS�PARAMETER�INDICATES�THE�DEVICE�WHICH�HAS�BEEN�TAKEN�OUT�OF�SERV ICE��)F�THE�DEVICE�IS�NOT�SPECIFIED��THEN�THE�PARAMETER�WILL�INDICATE�THATTHE�DEVICE�WAS�NOT�KNOWN�OR�THAT�IT�WAS�NOT�REQUIRED�

cause4HIS�PARAMETER�INDICATES�THE�REASON�OR�EXPLANATION�FOR�THE

OCCURRENCE�OF�THIS�EVENT��3EE�3ECTION��FOR�MORE�INFORMATION�


Comments

4HIS�EVENT�INDICATES�THAT�A�PREVIOUSLY�ACTIVE�DEVICE��A�DEVICE�WHICH�ISIN�SERVICE�HAS�ENTERED�INTO�A�MAINTENANCE�STATE��I�E��THE�DEVICE�HASBEEN�TAKEN�OUT�OF�SERVICE��/NCE�THIS�EVENT�HAS�OCCURRED�THEAPPLICATION�CAN�NOT�INITIATE�ANY�NEW�ACTIVE�SERVICE�REQUEST��E�G�CSTA-AKE#ALL��FOR�THAT�SPECIFIC�DEVICE��!�PASSIVE�SERVICE�REQUEST�E�G��MONITORING�OR�3NAPSHOT�3ERVICES�CAN�BE�DONE�WHILE�A�DEVICE�ISOUT�OF�SERVICE�


3YSTEM�3TATUS� �!PPLICATION�AS�THE�#LIENT

This section defines the services which provide system level statusinformation to the application or the driver/switch. The System Status serviceis bi-directional and thus the client/server relationship (see Figure 9-2) can bereversed.


CSTA3YS3TAT2EQ��

This service allows the application to request system status information fromthe driver/switch domain.

Syntax


2ET#ODE?T��CSTA3YS3TAT2EQ��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



privateData4HIS�IS�A�POINTER�TO�THE�#34!�PRIVATE�DATA�EXTENSION�MECHANISM�4HIS�IS�OPTIONAL�

Return Values





4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!3YS3TAT2EQ#ONF% VENT�MESSAGE�TO�INSURE�THAT�THE�SERVICE�REQUEST�HAS�BEENACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THESWITCH�





Comments

4HIS�FUNCTION�IS�USED�TO�REQUEST�THE�CURRENT�OVERALL�SYSTEM�STATUS�FORTHE�DRIVER�SWITCH�


#34!3YS3TAT2EQ#ONF%VENT

This event is in response to the cstaSysStatReq( ) service and informs theapplication of the overall system status of the driver/switch.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!3YS3TAT2EQ#ONF%VENT?TSYS3TAT2EQ�



TYPEDEF�STRUCT�#34!3YS3TAT2EQ#ONF%VENT?T��3YSTEM3TATUS?T SYSTEM3TATUS�

�#34!3YS3TAT3TAT2EQ#ONF%VENT?T�

TYPEDEF�ENUM�3YSTEM3TATUS?T�[��33?).)4)!,):).'��33?%.!",%$��33?./2-!,��33?-%33!'%3?,/34��33?$)3!",%$��33?/6%2,/!$?)--).%.4��33?/6%2,/!$?2%!#(%$��33?/6%2,/!$?2%,)%6%$��]�3YSTEM3TATUS?T�


Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICH�IDENTI FIES�THIS�MESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?393?34!4?2%1?#/.&�WHICH�IDENTIFIES�THIS�MESSAGE�AS�AN�#34!3YS3TAT2EQ#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION�OREVENT��)T�IS�USED�TO�MATCH�A�SPECIFIC�FUNCTION�CALL�REQUEST�WITH�ITS�CON FIRMATION�EVENTS�


systemStatus4HIS�PARAMETER�PROVIDES�THE�APPLICATION�WITH�A�CAUSE�CODE�DEFININGTHE�OVERALL�SYSTEM�STATUS�AS�FIN�4ABLE��


Table 9-4Overall System Status Codes


Initializing the driver/switch is re-initializing or restarting. This statusindicates that the driver/switch is temporarily unable torespond to any requests. If provided, this status messageshall be followed by an Enable status message to indicatethat the initialization process is completed.

Enabled request and responses are re-enabled, usually after adisruption or restart. This status indication shall be sentafter an initializing status indicator has been sent and maybe sent under other conditions. This status indicates thatthere are no outstanding monitor request.

Normal this cause value can be sent at any time by thedriver/switch to indicate that the status is normal. Thisstatus has no effect on other services.

Message Lost this status indicates that a request and/or responses mayhave been lost, including Event Reports.

Disabled this cause value indicates that existing monitor requestsvia cstaMonitorStart( ) have been disabled. Otherrequests and responses may also be disabled, but rejectresponses should be provided.

OverloadImminent

the driver/switch is about to reach a overload conditionand the application should shed load to better thesituation.

OverloadReached

the driver/switch has reach overload and may takeinitiative to shed load. This cause may be followed byaction on the part of the driver/switch to decreasemessage traffic. This may include stopping existing orrejecting any new monitor requests sent by the client, andrejections to additional new service requests.

OverloadRelieved

the driver/switch has determined that the overloadcondition has passed and normal application operationmay continue.


Comments

4HIS�CONFIRMATION�EVENT�PROVIDES�THE�APPLICATION�WITH�CERTAIN�INFOR MATION�REGARDING�THE�STATE�OF�THE�OVERALL�DRIVER�SWITCH�SYSTEM��4HISEVENT�IS�IMPORTANT�FOR�PROPER�APPLICATION�OPERATION�AND�SHOULD�BEPROCESSED�ACCORDINGLY��4HIS�IS�ESPECIALLY�IMPORTANT�FOR�CAUSE�VALUESFOR�THE�OVERLOAD�CONDITION��)F�THE�DRIVER�SWITCH�HAS�INFORMED�THEAPPLICATION�THAT�AN�OVERLOAD�CONDITION�IS�IMMINENT�ALL�APPLICATIONSSHOULD�ATTEMPT�TO�DECREASE�THE�OVERALL�TRAFFIC�TO�THE�DRIVER�SWITCH�4HIS�CAN�BE�ACCOMPLISHED��FOR�EXAMPLE��BY�STOPPING�ALL�NON ESSENTIALMONITORS�ON�CALL�OR�DEVICE�OBJECTS�ON�THE�SWITCH�THUS�REDUCING�THETRAFFIC�BETWEEN�THE�SERVER�AND�THE�SWITCH��&REQUENT�OCCURRENCE�OF�THE/VERLOAD�)MMINENT�CAUSE�VALUE�CAN�BE�A�SYMPTOMS�OF�A�POORLYENGINEERED�SYSTEM�WHICH�SHOULD�REVIEWED�FOR�PROPER�LOADING�


CSTA3YS3TAT3TART��

This services allows the application to register for System Status eventreporting. It can be used by an application to automatically receive aCSTASysStatEvent each time the status of the driver/switch changes.

Syntax


2ET#ODE?T CSTA3YS3TAT3TART��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�3YSTEM3TATUS&ILTER?T STATUS&ILTER�0RIVATE$ATA?T PRIVATE$ATA�

TYPEDEF�UNSIGNED�CHAR��3YSTEM3TATUS&ILTER?T��DEFINE��3&?).)4)!,):).'��X��DEFINE��3&?%.!",%$��X��DEFINE��3&?./2-!,��X��DEFINE��3&?-%33!'%3?,/34��X��DEFINE��3&?$)3!",%$��X��DEFINE��3&?/6%2,/!$?)--).%.4��X��DEFINE��3&?/6%2,/!$?2%!#(%$��X��DEFINE��3&?/6%2,/!$?2%,)%6%$��X��

Parameters



statusFilter4HIS�PARAMETER�IS�USED�TO�SPECIFY�A�FILTER�FOR�SPECIFIC�CAUSE�VALUES�INWHICH�THE�APPLICATION�IS�NOT�INTERESTED��4HE�PARAMETER�CAN�BE�USED�BYTHE�APPLICATION�TO�FILTER�OUT�UNWANTED�STATUS�INFORMATION��E�G��THE.ORMAL�STATUS


privateData0RIVATE�DATA�EXTENSION�MECHANISM��4HIS�IS�OPTIONAL�

Return Values




4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!3YS3TAT3TART#ONF% VENT�MESSAGE�TO�INSURE�THAT�THE�SERVICE�REQUEST�HAS�BEENACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THESWITCH�






Comments

4HIS�FUNCTION�IS�USED�TO�START�A�MONITOR�FOR�SYSTEM�STATUS�INFORMATION�4HE�SYSTEM�STATUS�INFORMATION�IS�PROVIDED�VIA�THE�#34!3YS3TAT% VENT��/NLY�ONE�3YSTEM�3TATUS�REGISTER�IS�ALLOWED�PER�OPENED�!#33TREAM�


#34!3YS3TAT3TART#ONF%VENT

This event is in response to the cstaSysStatStart( ) function and confirms anactive System Status monitor. Once this event is issued the application willstart to automatically receive unsolicited System Status events.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!3YS3TAT3TART#ONF%VENT?TSYS3TAT3TART�



TYPEDEF�STRUCT�#34!3YS3TAT3TART#ONF%VENT?T��3YSTEM3TATUS&ILTER?T STATUS&ILTER�

�#34!3YS3TAT3TAT3TART#ONF%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!#/.&)2-!4)/.��WHICH��IDENTI FIES��THIS�MESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�


eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?393?34!4?34!24?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN�#34!3YS3TAT3TART#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION�OREVENT��)T�IS�USED�TO�MATCH�A�SPECIFIC�FUNCTIONS�CALL�REQUEST�WITH�ITSCONFIRMATION�EVENTS�

statusFilter4HIS�PARAMETER�IS�USED�TO�SPECIFY�THE�FILTER�TYPE�WHICH�IS�ACTIVE�ON�THE3YSTEM�3TATUS�MONITOR�REQUESTED�BY�THE�APPLICATION��4HE�PARAMETERIDENTIFIES�WHICH�FILTER�WAS�ACCEPTED�BY�THE�DRIVER�SWITCH��.OTE�THATTHE�FILTER�RETURNED�BY�THIS�FUNCTION�MAY�BE�DIFFERENT�THAN�THE�FILTER�RE QUESTED�IN�THE�CSTA3YS3TAT3TART��SERVICE�REQUEST��4HIS�CAN�OCCURWHEN�THE�DRIVER�SWITCH�REJECTED�THE�REQUEST�FILTER�AND�SELECTED�ADEFAULT�FILTER�


Comments

4HIS�CONFIRMATION�EVENT�SHOULD�BE�CHECKED�BY�THE�APPLICATION�TOINSURE�THAT�THE�3YSTEM�3TATUS�MONITOR�HAS�BEEN�ACTIVATED�AND�THAT�THEREQUESTED�FILTER�IS�ACTIVE�


CSTA3YS3TAT3TOP��

This service is used to cancel a previously registered monitor for SystemStatus information.

Syntax


2ET#ODE?T CSTA3YS3TAT3TOP��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�0RIVATE$ATA?T PRIVATE$ATA�

Parameters




Return Values



!PPLICATION GENERATED�)DENTIFIERS� �IF�THE�FUNCTION�CALLCOMPLETES�SUCCESSFULLY�IT�WILL�RETURN�A�ZERO��VALUE��)F�THE


CALL�FAILS�A�NEGATIVE�ERROR��CONDITION�WILL�BE�RETURNED�&OR�APPLICATION GENERATED�IDENTIFIERS�THE�RETURN�WILL�NEVER�BEPOSITIVE��

4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!3YS3TAT3TOP#ONF% VENT�MESSAGE�TO�INSURE�THAT�THE�SERVICE�REQUEST�HAS�BEENACKNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THESWITCH�





Comments

4HIS�FUNCTION�IS�USED�TO�CANCEL�A�PREVIOUSLY�REGISTERED�3YSTEM�3TATUSMONITOR��/NCE�A�CONFIRMATION�EVENT�IS�ISSUED�FOR�THIS�FUNCTION��I�E��A#34!3YS3TAT3TOP#ONF%VENT ��THE�DRIVER�SWITCH�WILL�TERMINATE�AUTO MATIC�3YSTEM�3TATUS�EVENT�NOTIFICATION��)F�REQUIRED��THE�APPLICATIONCAN�STILL�CONTINUE�TO�POLL�FOR�SYSTEM�STATUS�INFORMATION�USING�THECSTA3YS3TAT2EQ��SERVICE��EVEN�AFTER�A�3YSTEM�3TATUS�REGISTER�ISCLOSED�


#34!3YS3TAT3TOP#ONF%VENT

This event is in response to the cstaSysStatStop( ) function and confirms acancellation of the active System Status monitor. Once this event is issued theapplication will not continue to receive unsolicited System Status events.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

)NVOKE)$?T INVOKE)$?T�]�CSTA#ONFIRMATION�


Parameters



eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?393?34!4?34/0?#/.&�WHICH��IDENTIFIES��THIS�MESSAGE�AS�AN�#34!3YS3TAT3TOP#ONF%VENT�


invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE�FUNCTION�OREVENT��)T�IS�USED�TO�MATCH�A�SPECIFIC�FUNCTIONS�CALL�REQUEST�WITH�ITSCONFIRMATION�EVENTS�


Comments

4HIS�CONFIRMATION�EVENT�SHOULD�BE�CHECKED�BY�THE�APPLICATION�TOINSURE�THAT�THE�3YSTEM�3TATUS�MONITOR�HAS�BEEN�DEACTIVATED��/NCE�THISEVENT�IS�SENT��AUTOMATIC�NOTIFICATION�OF�3YSTEM�3TATUS�EVENTS�WILL�BEDISCONTINUED��4HE�APPLICATION�MUST�POLL�USING�THE�CSTA3YS3TAT2EQ��SERVICE�IN�ORDER�TO�OBTAIN�ANY�3YSTEM�3TATUS�INFORMATION�


CSTA#HANGE3YS3TAT&ILTER��

This function is used to request a change in the filter options for automaticSystem Status event reporting for a specific ACS Stream. It allows theapplication to specify which System Status events it requires.

Syntax


2ET#ODE?T CSTA#HANGE3YS3TAT&ILTER��!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�3YSTEM3TATUS&ILTER?T STATUS&ILTER�0RIVATE$ATA?T PRIVATE$ATA�

Parameters



statusFilter4HIS�PARAMETER�IDENTIFIES�THE�NEW�FILTER�MASK�TO�BE�APPLIED�TO�THEEXISTING�ACTIVE�3YSTEM�3TATUS�MONITOR��4HE�NEW�MASK�WILL�REPLACE�THEEXISTING�MASK�


Return Values





4HE�APPLICATION�SHOULD�ALWAYS�CHECK�THE�#34!#HANGE3YS3TAT&IL TER#ONF%VENT�MESSAGE�TO�INSURE�THAT�THE�SERVICE�REQUEST�HAS�BEEN�AC KNOWLEDGED�AND�PROCESSED�BY�THE�4ELEPHONY�3ERVER�AND�THE�SWITCH�





Comments

4HIS�SERVICE�IS�USED�WHENEVER�THE�APPLICATION�WISHES�TO�CHANGE�A�PRE VIOUSLY�DEFINED�3YSTEM�3TATUS�EVENT�FILTER��.OTE�THAT�APPLICATION�WILLNOT�RECEIVE�ANY�3YSTEM�3TATUS�MESSAGE�WHICH�HAS�ITS�BIT�MASK�TURNEDOFF�


#34!#HANGE3YS3TAT&ILTER#ONF%VENT

This event occurs as a result of the cstaChangeSysStatFilter( ) service andinforms the application which event filter was set by the server.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�!#3�$ATA�4YPES�AND�#34!�$ATA4YPES�IN�SECTION��FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!#HANGE3YS3TAT&ILTER#ONF%VENT?T��CHANGE3YS3TAT&ILTER�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT�#34!#HANGE3YS3TAT&ILTER#ONF%VENT?T��3YSTEM3TATUS&ILTER?T STATUS&ILTER3ELECTED�3YSTEM3TATUS&ILTER?T STATUS&ILTER!CTIVE�

]�#34!#HANGE3YS3TAT&ILTER#ONF%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE#34!?#(!.'%?393?34!4?&),4%2?#/.&��WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!#HANGE3YS3TAT&ILTER#ONF%VENT�

invokeID4HIS�PARAMETER�SPECIFIES�THE�REQUESTED�INSTANCE�OF�THE

FUNCTION�OR�EVENT��)T�IS�USED�TO�MATCH�A�SPECIFIC�FUNCTIONS�CALL�REQUESTWITH�ITS�CONFIRMATION�EVENTS�

statusFilterSelected4HIS�PARAMETER�SPECIFIES�THE�3YSTEM�3TATUS�EVENT�FILTERS�WHICH�ARE�AC TIVE�AS�A�RESULT�OF�THE�CSTA#HANGE3YS3TAT&ILTER��SERVICE�REQUEST�4HIS�FILTER�MAY�BE�DIFFERENT�THAN�THE�ONE�REQUESTED�BY�THE�APPLICATION�4HIS�CAN�OCCUR�IF�THE�IMPLEMENTATION�REJECTS�A�PARTICULAR�FILTERREQUEST�

eventFilterActive4HIS�PARAMETER�INDICATES�THE�FILTERS�WHICH�ARE�ALREADY�ACTIVE�ON�THEGIVEN�#34!�ASSOCIATION�


Comments

4HIS�CONFIRMATION�EVENT�SHOULD�BE�CHECK�BY�THE�APPLICATION�TO�INSURETHAT�THE�EVENT�FILTER�REQUESTED�HAS�BEEN�ACTIVATED�AND�WHICH�FILTERS�AREALREADY�ACTIVE�ON�THE�GIVEN�3YSTEM�3TATUS�MONITOR�


#34!3YS3TAT%VENT

This unsolicited event informs the application of the overall system status ofthe driver/switch. The application must register for System Status eventsbefore this event is sent to the application.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

UNION[

#34!3YS3TAT%VENT?T��SYS3TAT�]�U�


]�#34!%VENT?T�

TYPEDEF�STRUCT[

3YSTEM3TATUS?T SYSTEM3TATUS�]�#34!3YS3TAT%VENT?T�



Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!%6%.42%0/24��WHICH��IDENTI FIES��THIS�MESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�

eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?393?34!4��WHICH��IDENTIFIESTHIS�MESSAGE�AS�AN�#34!3YS3TAT%VENT�


systemStatus4HIS�PARAMETER�PROVIDES�THE�APPLICATION�WITH�A�CAUSE�CODE�DEFININGTHE�OVERALL�SYSTEM�STATUS��3EE�4ABLE�� FOR�THE�POSSIBLE�VALUES�OFTHIS�PARAMETER�


Comments

4HIS�EVENT�PROVIDES�THE�APPLICATION�WITH�CERTAIN�INFORMATIONREGARDING�THE�STATE�OF�THE�OVERALL�DRIVER�SWITCH�SYSTEM��4HIS�EVENT�ISIMPORTANT�FOR�PROPER�APPLICATION�OPERATION�AND�SHOULD�BE�PROCESSEDACCORDINGLY��4HIS�IS�ESPECIALLY�IMPORTANT�FOR�CAUSE�VALUES�FOR�THEOVERLOAD�CONDITION��)F�THE�DRIVER�SWITCH�HAS�INFORMED�THE�APPLICATIONTHAT�AN�OVERLOAD�CONDITION�IS�IMMINENT�ALL�APPLICATIONS�SHOULD�ATTEMPTTO�DECREASE�THE�OVERALL�TRAFFIC�TO�THE�DRIVER�SWITCH��4HIS�CAN�BEACCOMPLISHED��FOR�EXAMPLE��BY�STOPPING�ALL�NON ESSENTIAL�MONITORS�ONCALL�OR�DEVICE�OBJECTS�ON�THE�SWITCH�THUS�REDUCING�THE�TRAFFIC�BETWEENTHE�SERVER�AND�THE�SWITCH��&REQUENT�OCCURRENCE�OF�THE�/VERLOAD)MMINENT�EVENT�CAN�BE�A�SYMPTOMS�OF�A�POORLY�ENGINEERED�SYSTEMWHICH�SHOULD�REVIEWED�FOR�PROPER�LOADING�

0"8�DRIVERS�THAT�FOLLOW�DRIVER�PROGRAMMING�RECOMMENDATIONS�WILLSEND�#34!3YS3TAT%VENT�WHEN�A�#4)�LINK�GOES�UP�OR�DOWN��7HEN�ALINK�THAT�IS�IN�SERVICE�GOES�DOWN��THE�SYSTEM3TATUS�WILL�BE)NITIALIZING ��7HEN�A�LINK�ENTERS�SERVICE��THE�SYSTEM3TATUS�WILL�BE%NABLED ��)F�A�DRIVER�USES�MULTIPLE�#4)�LINKS�TO�PROVIDE�SERVICE�THEN�THE�DRIVER�MAY�ONLY�SEND�THE� )NITIALIZING �MESSAGE�WHEN�THEREARE�NO�#4)�LINKS�IN�SERVICE�AND�MAY�SEND�THE� %NABLED �WHEN�AT�LEASTONE�LINK�IS�IN�SERVICE�

#ERTAIN��NON ESSENTIAL�CAUSE�VALUES�CAN�BE�SENT�AT�ANY�TIME�OR�DEPEND ING�ON�THE�DRIVER�SWITCH�IMPLEMENTATION�EVEN�AT�REGULAR�INTERVALS��E�G�THE�.ORMAL�CAUSE�VALUE�TO�INDICATE�THAT�THE�SYSTEM�STATUS�IS�/�+��ANDOPERATING�NORMALLY��4HIS�CAN�BE�TURNED�OFF�BY�THE�APPLICATION�TO�AVOIDTHE�OVERHEAD�ASSOCIATED�WITH�PROCESSING�THESE�NORMAL�MESSAGES��4HISIS�ACCOMPLISHED�BY�CHANGING�THE�EVENT�FILTER�TYPE�BY�USING�THECSTA#HANGE3YS3TAT&ILTER��SERVICE��4HIS�SERVICE�CAN�BE�USED�TO�DIS CONTINUE�THE�DELIVERY�OF��NON ESSENTIAL��SYSTEM�STATUS�EVENTS�TO�THEAPPLICATION�


#34!3YS3TAT%NDED%VENT

The driver uses this event to cancel a previously registered monitor for SystemStatus information.

Syntax


TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[

UNION[

#34!3YS3TAT%NDED%VENT?TSYS3TAT%NDED�



TYPEDEF�STRUCT�#34!3YS3TAT%NDED%VENT?T�[��.ULLTYPE��NULL�]�#34!3YS3TAT%NDED%VENT?T�

Parameters


eventClass4HIS�IS�A�TAG�WITH�THE�VALUE�#34!%6%.42%0/24��WHICH�IDENTI FIES��THIS�MESSAGE�AS�AN�#34!�UNSOLICITED�EVENT�


eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?393?34!4?%.$%$��WHICHIDENTIFIES��THIS�MESSAGE�AS�A�#34!3YS3TAT3TOP%VENT�

monitorCrossRefID4HIS�PARAMETER�IS�UNUSED�IN�THIS�MESSAGE�



3YSTEM�3TATUS��$RIVER�3WITCH�AS�THE�#LIENT

This section defines the services which provide system level statusinformation to the driver/switch form the application. The System Statusservice is bi-directional and thus the client/server relationship (see Figure 9-2)can be reversed.


#34!3YS3TAT2EQ%VENT

This unsolicited event is sent by the driver/switch to request system statusinformation from the application.

Syntax

4HE�FOLLOWING�STRUCTURE�SHOWS�ONLY�THE�RELEVANT�PORTIONS�OF�THEUNIONS�FOR�THIS�MESSAGE��3EE�SECTION��!#3�$ATA�4YPES�AND��#34!�$ATA�4YPES�FOR�A�COMPLETE�DESCRIPTION�OF�THE�EVENT�STRUCTURE�

TYPEDEF�STRUCT[



TYPEDEF�STRUCT[


STRUCT[


#34!3YS3TAT2EQ%VENT?TSYS3TAT2EQUEST�



TYPEDEF�STRUCT�#34!3YS3TAT2EQ%VENT?T�[��.ULLTYPE��NULL�]�#34!3YS3TAT2EQ%VENT?T�

Parameters




eventType4HIS�IS�A�TAG�WITH�THE�VALUE�#34!?393?34!4?2%1��WHICH��IDENTI FIES��THIS�MESSAGE�AS�AN�#34!3YS3TAT2EQ%VENT�

InvokeID4HIS�PARAMETER�IDENTIFIES�THE�INSTANCE�OF�THE�REQUEST�GENERATED�BY�THESWITCH�DRIVER��4HIS�SAME�VALUE�MUST�BE�USED��UNCHANGED��IN�THE�RE SPONSE�TO�THIS�EVENT��CSTA3YS3TAT2EQ#ONF��


Comments

4HIS�EVENT�IS�SENT�BY�THE�DRIVER�SWITCH�TO�REQUEST�STATUS�INFORMATIONPERTAINING�TO�THE�APPLICATION��)T�IS�THE�BI DIRECTIONAL�EQUIVALENT�OF�THECSTA3YS3TAT2EQ��FUNCTION�WHICH�IS�ISSUED�BY�THE�APPLICATION�TO�RE QUEST�STATUS�INFORMATION�FROM�THE�DRIVER�SWITCH��4HE�APPLICATION�RE SPONDS�TO�THIS�UNSOLICITED�EVENT�REQUEST�UTILIZING�THE�CSTA3YS3TA T2EQ#ONF��FUNCTION�


CSTA3YS3TAT2EQ#ONF��

This service is used to respond to a CSTASysStatReqEvent unsolicited eventfrom the driver/switch. It provides the driver/switch with informationregarding the status of the application.

Syntax

�INCLUDE��CSTA�H�

2ET#ODE?T CSTA3YS3TAT2EQ#ONF��

!#3(ANDLE?T ACS(ANDLE�)NVOKE)$?T INVOKE)$�3YSTEM3TATUS?T SYSTEM3TATUS�0RIVATE$ATA?T PRIVATE$ATA�


Parameters


InvokeID4HE�VALUE�OF�THIS�PARAMETER�MUST�BE�THE�SAME��UNCHANGED�AS�THATPROVIDED�IN�THE�CSTA3YS3TAT2EQ%VENT�SO�THAT�THE�DRIVER�SWITCH�CANMATCH�AN�INSTANCE�OF�A�SERVICE�REQUEST�WITH�THE�RESPONSE�TO�THAT�RE QUEST�

systemStatus4HIS�PARAMETER�PROVIDES�THE�DRIVER�SWITCH�WITH�A�CAUSE�CODE�DEFININGTHE�OVERALL�SYSTEM�STATUS��3EE�4ABLE�� FOR�THE�POSSIBLE�VALUES�OFTHIS�PARAMETER�



Return Values

4HIS�FUNCTION�NEVER�RETURNS�AN�INVOKE�IDENTIFIER�SINCE�THERE�IS�NO�CON FIRMATION�EVENT�FOR�THIS�SERVICE��4HE�FUNCTION�DOES�RETURN�ERRORSCONDITIONS�DURING�THE�PROCESSING�OF�THE�REQUEST�BY�THE�!0)�#LIENT,IBRARY��!�RETURN�VALUE�OF�ZERO��INDICATES�THAT�THE�REQUEST�HAS�BEENACCEPTED�BY�THE�,IBRARY�





Comments

4HIS�CONFIRMATION�RESPONSE�PROVIDES�THE�DRIVER�SWITCH�WITH�CERTAIN�IN FORMATION�REGARDING�THE�STATE�OF�THE�OVERALL�APPLICATION��4HE�INFORMA TION�CAN�BE�USED�BY�THE�DRIVER�SWITCH�TO�DETERMINE�THE�OVERALL�STATE�OFTHE�APPLICATION��4HE�DRIVER�SWITCH�MAY�ACT�ON�THIS�INFORMATION�INORDER�TO�INSURE�PROPER�END TO END�SYSTEM�OPERATION�AND�PERFORMANCE�&REQUENT�OCCURRENCE�OF�THE�/VERLOAD�)MMINENT�CAUSE�VALUE�CAN�BE�ASYMPTOMS�OF�A�POORLY�ENGINEERED�APPLICATION�SYSTEM�WHICH�SHOULDREVIEWED�FOR�PROPER�LOADING�


CSTA3YS3TAT%VENT��

This service is used to send application system status information in the formof an unsolicited event to the driver/switch without a formal request for theinformation. This status information can be sent at any time.

Syntax

�INCLUDE��CSTA�H�

2ET#ODE?T CSTA3YS3TAT%VENT��!#3(ANDLE?T ACS(ANDLE�3YSTEM3TATUS?T SYSTEM3TATUS�0RIVATE$ATA?T PRIVATE$ATA�


Parameters


systemStatus4HIS�PARAMETER�PROVIDES�THE�DRIVER�SWITCH�WITH�A�CAUSE�CODE�DEFININGTHE�OVERALL�SYSTEM�STATUS��3EE�4ABLE�� FOR�THE�POSSIBLE�VALUES�OFTHIS�PARAMETER�


Return Values

4HIS�FUNCTION�NEVER�RETURNS�AN�INVOKE�IDENTIFIER�SINCE�THERE�IS�NO�CON FIRMATION�EVENT�FOR�THIS�SERVICE��4HE�FUNCTION�DOES�RETURN�ERRORSCONDITIONS�DURING�THE�PROCESSING�OF�THE�REQUEST�BY�THE�!0)�#LIENT,IBRARY��!�RETURN�VALUE�OF�ZERO��INDICATES�THAT�THE�REQUEST�HAS�BEENACCEPTED�BY�THE�,IBRARY�






Comments

4HIS�UNSOLICITED�SERVICE�EVENT�IS�SENT�TO�THE�DRIVER�SWITCH�IN�ORDER�TOINFORM�IT�OF�THE�STATE�OF�THE�OVERALL�APPLICATION�SYSTEM��4HEDRIVER�SWITCH�MAY�ACT�ON�THIS�INFORMATION�IN�ORDER�TO�INSURE�PROPEREND TO END�SYSTEM�OPERATION�AND�PERFORMANCE��&REQUENT�OCCURRENCEOF�THE�/VERLOAD�)MMINENT�CAUSE�VALUE�CAN�BE�A�SYMPTOMS�OF�A�POORLYENGINEERED�APPLICATION�SYSTEM�WHICH�SHOULD�REVIEWED�FOR�PROPERLOADING�

4ELEPHONY�3ERVICES�!0) ��

C h a p t e r 10 Programming Notes

This chapter contains information about using the TSAPI libraries on variousoperating system platforms.


43!0)�ON�-ACINTOSH

-ACINTOSH�0ROGRAMMING�/VERVIEW

Read this section for information on developing TSAPI applications onMacintosh. You need not be familiar with the CSTA call model or API beforereading further, but you should read Chapter 4, ACS Control Services.

-ACINTOSH�$EVELOPMENT�0LATFORMS

Telephony Services applications may be created in any Macintoshdevelopment environment; the TSAPI headers in this SDK contain explicitsupport for Metrowerks C and C++, Apple’s MPW C and PPCC and SymantecC++ and THINK C. Creating applications with other compilers may requireyou to modify these headers.

9OU�SHOULD�BE�AWARE�OF�THE�FOLLOWING�COMPILER�ENVIRONMENT�CONSIDERATIONSWHEN�USING�43!0)�

u 43!0)�REQUIRES�ENUMERATED�TYPES�TO�BE�VARIABLE�SIZES

Many Macintosh C compilers support two different storage classes forthe enumerated type. All compilers supported by TSAPI allowenumerated types to be the size of the minimum integral type necessaryto store their range of enumerated values. This option is sometimescalled “packed enums”. Many compilers also support forcingenumerated types to be the same size as INT.

Table 10-1 describes compiler settings necessary to enable variable-sized enums.


Table 10-1Enum Settings in Macintosh Compilers

Compiler Enum Packing Directive

Apple MPW C 3.2 N/A

Apple PPCC 1.0 -enum min

Metrowerks Codewarrior C & C++, 68k Language: Enums Always Int unchecked

Metrowerks Codewarrior C & C++, PPC Language: Enums Always Int unchecked

Metrowerks mwcPPC -enum off

Symantec THINK C 6.0, 7.0 Language Settings:enums are always ints unchecked

Symantec C++ for Macintosh 6.0, 7.0 Language Settings:enums are always ints unchecked

u 43!0)�STRUCTURES�REQUIRE�MAC��K�ALIGNMENT

TSAPI requires 68k Macintosh compilers to use two-byte structurealignment. For Macintosh compilers targeting PowerPC, TSAPIdeclares all structures using the �PRAGMA�OPTIONSALIGN�MAC��K directive. If your PowerPC compiler does not supportthis pragma or does not define either POWERC or ??POWERC, you mustmanually specify 2-byte alignment.

Table 10-2 describes compiler settings necessary to enable 2-bytestructure alignment:


Table 10-2Structure Alignment Settings in Macintosh Compilers

Compiler Structure Alignment Directive

Apple MPW C 3.2 N/A

Apple PPCC 1.0 N/A

Metrowerks Codewarrior C & C++, 68k Processor: Struct Alignment: 68k

Metrowerks Codewarrior C & C++, PPC N/A

Metrowerks mwcPPC N/A

Symantec THINK C 6.0, 7.0 Processor Settings:align arrays of char checked

Symantec C++ for Macintosh 6.0, 7.0 Processor Settings:Struct Field Alignment:Align to 2 byte boundary

43!0)�AND�'ESTALT

Call Gestalt with GESTALT43!0)#STA6ERSION as the selector parameterto find out the current version of the Macintosh Telephony Services clientlibrary.

If the library is available, the response parameter will point to the libraryversion.

If the library is unavailable, Gestalt will return an error or the responseparameter will contain zero.

For more information on using the Gestalt manager, see reference [6].

$YNAMIC�,INKING

This section describes how to dynamically link with the Telephony Serviceslibrary on Macintosh.


��X��-ACINTOSH�$YNAMIC�,INKING

On other TSAPI platforms, client applications use inherent operating systemfacilities to dynamically link with the Telephony Services library. TheMacintosh 68k runtime model does not provide such a facility. Instead, Appleprovides several methods for achieving runtime linking — drivers, theComponent Manager and the Apple Shared Library Manager.

The Macintosh Telephony Services library is a faceless backgroundapplication that exports TSAPI using the Component Manager. The SDKcontains static link libraries in MPW .o, THINK/Symantec library andMetrowerks library object formats that translate from TSAPI to theComponent Manager calls necessary for using the Telephony Serviceslibrary's CSTA component.

You need not use Gestalt to determine if the 68k Telephony Services libraryis running before using any TSAPI functions. If you do not use Gestalt, youshould verify that you are running on a 68020 or better processor beforemaking TSAPI calls.

Refer to your compiler documentation for instructions on linking MPW .oformat object modules with your 68k code.

0OWER0#�-ACINTOSH�$YNAMIC�,INKING

On Power Macintosh, the Telephony Services application is supplemented byan import library that exports TSAPI to PowerPC-native applications. TheTelephony Services application is still used to export TSAPI through theComponent Manager to 68k applications.

You must use Gestalt as described above to determine if the PowerPCTelephony Services application is running before using any TSAPI functions.Failure to do so may result in crashing the host Macintosh.

The SDK contains the Telephony Services import library in XCOFF formatfor use with PPCC. Metrowerks projects should include the shared libraryfrom the Macintosh Client package.

See reference [7] for more information on the Code Fragment Manager andshared libraries.

.OTE


5SING�!PPLICATION�#ONTROL�3ERVICES

This section discusses how to use application control services (ACS) for suchtasks as event notification and retrieval on Macintosh. If you are porting codethat uses Telephony Services, you should read this section to get an overviewof the differences between Macintosh and other platforms.

%VENT�.OTIFICATION

On Macintosh both ACS%VENT.OTIFY� and ACS3ET%32� are availableand are analogous to their Windows counterparts.

To use ACS%VENT.OTIFY�, you should understand how to receive andinterpret Apple Events in your application. You can find information on usingApple Events in reference [4].

As with its counterparts on other platforms, ACS%VENT.OTIFY� can post amessage to your application whenever any message is received from theTelephony Server (notifyAll = TRUE) or simply whenever a previously emptystream receives an event (notifyAll = FALSE).

The special feature of ACS%VENT.OTIFY� on Macintosh is that theprocess identifier is an !%!DDRESS$ESC. This allows your program tospecify any legal address for an AppleEvent — network visible PPC entitiesincluded. The Telephony Services library will send notification AppleEventsusing the K!%.EVER)NTERACT flag; if the target application you specify ison a server to which the Macintosh is not authenticated, notification will fail.All notification events are sent with the K!%.O2EPLY flag.

If you are using acsEventNotify( ), you should use notifyAll = FALSE.Otherwise, the performance lag caused by processing Apple Events mayunacceptably slow your application. The ability to post a message for everyreceived event has been preserved for compatibility with TSAPI on otherplatforms.

To optimize your application for speed, you should use ACS3ET%32� toincrement or set a variable in your application. Examine this variable todetermine when to retrieve incoming events.

.OTE


The following example demonstrates acsSetESR() being used to "preempt" anarbitrary lengthy processing task without polling for events — an importantspeed optimization. The example uses no global variables under 68k andhence may be easily implemented in any standalone code resource.


��$EMONSTRATION�OF�USING�ACS3ET%32��TO�ALLOW�COMPUTE BOUND��TASKS�TO�HANDLE�TELEPHONY�TRAFFIC��W�I�T�H�O�U�T��POLLING��OR�GLOBAL�VARIABLES��

STATIC�PASCAL�VOID�ESR��UNSIGNED�LONG�ESR0ARAM��

�IF�53%32/54).%$%3#2)04/23STATIC�2OUTINE$ESCRIPTOR�ESR2$��

"5),$?2/54).%?$%3#2)04/2��UPP%SR&UNC0ROC)NFO��ESR��ENDIF

��%32�EXAMPLE��STATIC�PASCAL�VOIDESR��UNSIGNED�LONG�ESR0ARAM�[

��ESR0ARAM�POINTS�TO�THE�QUEUED%VENTS�VARIABLE��UNSIGNED�SHORT�QUEUED%VENTS0TR��

�UNSIGNED�SHORTESR0ARAM�

��INCREMENT�GLOBAL�VARIABLE��G1UEUED%VENTS0TR��

]

VOIDCOMPUTE7HILE7ATCHING3TREAM��!#3(ANDLE?T�THE3TREAM�[

2ET#ODE?T RC�SHORT �QUEUED%VENTS� ��COUNTING��SEMAPHORE��THAT��

��TRACKS�NUMBER�OF�EVENTS�THAT��HAVE�BEEN�RECEIVED�BUT�NOT��PROCESSED��

��REGISTER�CALLBACK�REQUEST�NOTIFICATION�FOR�EACH�EVENT��IF�53%32/54).%$%3#2)04/23RC��ACS3ET%32�THE3TREAM��ESR2$��QUEUED%VENTS��425%��ELSERC��ACS3ET%32��THE3TREAM��ESR��QUEUED%VENTS��425%��ENDIF

IF��RC��!#30/3)4)6%?!#+�[

��THE�CALLBACK�COULD�NOT�BE�REGISTERED��SO�FAIL�AND�RETURN��

RETURN�]

��BEGIN�ITERATIVE�COMPUTATION�PROCESS��WHILE��3/-%?,%.'4(9?#/-054!4)/.?).?02/'2%33�[

IF��QUEUED%VENTS��[

�


��2ETRIEVE�EVENTS�HERE��OR�BREAK�OUT�OF�LOOP��ETC�

��]

��PROCESS�ONE�STEP�OF�A�LENGTHY�COMPUTATION��]

��REMOVE�%32�BEFORE�RETURNING�SINCE�IT�WAS�USING�LOCAL��STORAGE�TO�HOLD�THE�QUEUE�COUNT��RC��ACS3ET%32��THE3TREAM��.5,,��425%��

]


2ECEIVING�%VENTS

This section discusses event reception using ACS'ET%VENT0OLL� andACS'ET%VENT"LOCK� on Macintosh.

"LOCKING�6ERSUS�0OLLING

Macintosh applications should generally use ACS'ET%VENT0OLL� insteadof ACS'ET%VENT"LOCK�.

Whereas ACS'ET%VENT"LOCK� prevents most system activity fromcontinuing until the calling application receives an event,ACS'ET%VENT0OLL� returns control immediately if no event is waitingfor the caller.

Calling ACS'ET%VENT0OLL� frequently — particularly from 68kapplications — can unduly consume processor time and resources. Instead ofusing polling as a method of determining whether messages are waiting inyour application's receive queue, consider using event notification to trigger apolling call to receive events.

Neither acsGetEventBlock() nor acsGetEventBlock() may be called from acallback procedure registered with acsSetESR(). See the overview of eventnotification for an example of implementing a callback procedure to reducepolling.

2ECEIVING�%VENTS�&ROM�!NY�3TREAM

An application may specify a NULL stream handle when callingACS'ET%VENT0OLL� or ACS'ET%VENT"LOCK� to request that theTelephony Services library return the first event available on any of thatapplication's streams.

When using a NULL stream handle with ACS'ET%VENT0OLL� orACS'ET%VENT"LOCK�, your application or code resource must have avalid global context. For 68k applications, this requires a valid A5-world. For

.OTE


68k standalone code, A4 must be valid. No code using the MPW “no globals”.o static link library may use a NULL stream handle.

This restriction does not apply to PowerPC applications and standalone code.

43!0)�2ESOURCE�-ANAGEMENT

The Telephony Services library allocates session resources such as ACSstream memory and network connection resources from the heap active whenACS/PEN3TREAM� is called.

5SING�43!0)�)N�3TANDALONE�#ODE

The Telephony Services library may be called from any type of code —applications, drivers, extensions, plug-ins et al. — but there are someprecautions to follow when calling TSAPI from non-application code.

u 3TREAM�HANDLES�ARE�NOT�VALID�ACROSS�PROCESSES

A stream handle opened while process A is running may not be usedwhile process B is running. TSAPI calls made using a stream handle inthe incorrect "process context" will return !#3%22?"!$($,.

u 3TREAMS�WILL�BE�CLOSED�WHEN�THE�OWNER�PROCESS�EXITS

A stream handle opened while process "TSCLIENT" is running will beclosed when process "TSCLIENT" exits. You need to open streamsusing a persistent process if you are writing a code resource — anextension or Gestalt procedure, for example — that expects to remainalive while the host Macintosh is on.


43!0)�ON�/3��

TSAPI is fully supported under OS/2. Application developers can program toTSAPI to develop both Presentation Manager (PM) and non PM OS/2applications. The IBM CSet++ 2.1, Borland C/C++ 1.5 and Watcom C/C++10.0 OS/2 compilers are all supported. Using any other compiler may requireuser modification or conversion of header files.

Two TSAPI calls acsEnumServerNames() and acsSetESR() require the userto specify a callback function. These callback functions need to be definedwith the _System calling convention.

OS/2 applications open ACS streams to the Telephony Server using thestandard procedure outlined in this document. Once an ACS stream has beensuccessfully opened, there are two ways for an OS/2 application to be notifiedthat a TSAPI event is available to be retrieved. PM applications can use theacsEventNotify() TSAPI call to designate a user defined message be posted toits application queue when a TSAPI event is available. PM and non-PMapplications can use the acsSetESR() TSAPI call to designate an EventService Routine to be called whenever a TSAPI event is available.Alternatively, both PM and non-PM applications can forego event notificationand receive events by creating a separate thread that uses acsGetEventBlock()or acsGetEventPoll() directly, to block until an event is received or to poll forevents.

Both acsEventNotify() and acsSetESR() only signal the availability of aTSAPI message. The application must still call acsGetEventBlock() oracsGetEventPoll( ) to actually retrieve the event from the Client API Libraryqueue.


ACS%VENT.OTIFY�


2ET#ODE?T�ACS%VENT.OTIFY��!#3(ANDLE?T ACS(ANDLE�(7.$ HWND�5,/.' MSG�"OOLEAN NOTIFY!LL�

acsHandleIS�THE�VALUE�OF�THE�UNIQUE�HANDLE�TO�THE�OPENED�!#3�3TREAM�FORWHICH�EVENT�NOTIFICATION�MESSAGES�WILL�BE�POSTED��

hwndIS�THE�HANDLE�OF�THE�WINDOW�WHICH�IS�TO�RECEIVE�EVENT�NOTIFICATIONMESSAGES��)F�THIS�PARAMETER�IS�.5,,��EVENT�NOTIFICATION�IS�DISABLED�

msg�IS�THE�USER DEFINED�MESSAGE�TO�BE�POSTED�WHEN�AN�INCOMING�EVENTBECOMES�AVAILABLE��4HE�MP��AND�MP��PARAMETERS�OF�THE�MESSAGE�WILLCONTAIN�THE�FOLLOWING�MEMBERS�OF�THE�!#3%VENT(EADER?T�STRUCTURE�

MP� ��ACS(ANDLE

3(/24�&2/--0�MP� ��EVENT#LASS

3(/24�&2/--0�MP� ��EVENT4YPE

notifyAllSPECIFIES�WHETHER�A�MESSAGE�WILL�BE�POSTED�FOR�EVERY�EVENT��)F�THISPARAMETER�IS�425%�THEN�A�MESSAGE�WILL�BE�POSTED�FOR�EVERY�EVENT��)FIT�IS�&!,3%�THEN�A�MESSAGE�WILL�ONLY�BE�POSTED�EACH�TIME�THE�RECEIVEQUEUE�BECOMES�NON EMPTY��I�E��THE�QUEUE�COUNT�CHANGES�FROM�ZERO��TO�ONE��4HIS�OPTION�MAY�BE�USED�TO�REDUCE�THE�OVERHEAD�OFNOTIFICATION��OR�THE�LIKELIHOOD�OF�OVERFLOWING�THE�APPLICATION�SMESSAGE�QUEUE�

%XAMPLE4HIS�EXAMPLE�USES�THE�ACS%VENT.OTIFY�FUNCTION�TO�ENABLE�EVENTNOTIFICATION�

�DEFINE�7-?!#3%6%.4�7-?53%2��

-2%35,4�%80%.4297ND0ROC��(7.$�HWND��5,/.'�MSG��-0!2!-�MP��-0!2!-�MP�[




��POST�7-?!#3%6%.4�TO�THIS�WINDOW��WHENEVER�AN�!#3�EVENT�ARRIVES�ACS%VENT.OTIFY��ACS(ANDLE��HWND��7-?!#3%6%.4��425%�


CASE�7-?!#3%6%.4�

��MP��CONTAINS�AN�!#3(ANDLE?T��3(/24�&2/--0�MP��CONTAINS�AN�%VENT#LASS?T��3(/24�&2/--0�MP��CONTAINS�AN�%VENT4YPE?T


RETURN��


]RETURN�7IN$EF7INDOW0ROC��HWND��MSG��MP��MP��

]

ACS3ET%32�

The ESR mechanism can be used by the application to receive anasynchronous notification of the arrival of an incoming event from the OpenACS Stream. The application can use the ESR mechanism to trigger specificevents (e.g. post an event semaphore). The ESR routine will receive one user-defined parameter. The ESR should not call ACS functions, otherwise theresults will be indeterminate. The syntax of acsSetESR() is as follows:


TYPEDEF�VOID��%SR&UNC�5,/.'�ESR0ARAM

2ET#ODE?T ACS3ET%32�� !#3(ANDLE?T ACS(ANDLE�� %SR&UNC ESR�

5,/.' ESR0ARAM�"OOLEAN NOTIFY!LL�


acsHandle�IS�THE�VALUE�OF�THE�UNIQUE�HANDLE�TO�THE�OPENED�3TREAM�FOR�WHICH�THIS%32�ROUTINE�WILL�APPLY��/NLY�ONE�%32�IS�ALLOWED�PER�ACTIVEACS(ANDLE�

esrPOINTS�TO�THE�%32��THE�ADDRESS�OF�A�FUNCTION��4HIS�FUNCTION�MUST�USETHE�?3YSTEM�CALLING�CONVENTION��!�MULTI THREADED�APPLICATION�THATREGISTERS�THE�SAME�%32�FOR�MULTIPLE�OPEN�STREAMS�NEEDS�TO�ENSURE�THATTHIS�FUNCTION�IS�REENTRANT��!�.5,,�POINTER�IS�USED�TO�DISABLE�THECURRENT�%32�MECHANISM�

esrParamDEFINES�PARAMETER�WHICH�WILL�BE�PASSED�TO�THE�%32�WHEN�IT�IS�CALLED�

notifyAllSPECIFIES�WHETHER�THE�%32�WILL�BE�CALLED�FOR�EVERY�EVENT��)F�THISPARAMETER�IS�425%�THEN�THE�%32�WILL�BE�CALLED�FOR�EVERY�EVENT��)F�ITIS�&!,3%�THEN�THE�%32�WILL�ONLY�BE�CALLED�EACH�TIME�THE�RECEIVEQUEUE�BECOMES�NON EMPTY��I�E��THE�QUEUE�COUNT�CHANGES�FROM�ZERO��TO�ONE��4HIS�OPTION�MAY�BE�USED�TO�REDUCE�THE�OVERHEAD�OFNOTIFICATION�


43!0)�ON�7IN��

0ROGRAMMING�/VERVIEW

Read this section for information on developing TSAPI applications forWindows NT or Windows 95. You do not need to be familiar with the CSTAcall model or API before reading further, but you should read Chapter 4, ACSControl Services.

$EVELOPMENT�0LATFORMS

The TSAPI header files and import libraries in this SDK are compatible withthe Microsoft Visual C++ Development System. Using another compiler mayrequire you to modify the header files, for example, to account for differencesin structure alignment, size of enumerated data types, etc. The Win32 TSAPIlibrary assumes the default 8-byte structure packing and an ENUM size of 4bytes.

,INKING�TO�THE�43!0)�,IBRARY

The TSAPI for Win32 is implemented as a dynamic link library,#34!��$,,. Specify the #34!��,)" import library when compilingyour application.


This section discusses how to use application control services (ACS) toretrieve events on Win32 platforms. If you are porting code that usesTelephony Services, you should read this section to get an overview of thedifferences between Win32 and other platforms.



ACS%VENT.OTIFY� enables asynchronous notification of incoming eventsvia Windows messages.

ACS3ET%32� enables asynchronous notification of incoming events via anapplication-defined callback routine. This routine will be called in the contextof a background thread created by the TSAPI Library, not a thread created bythe application. The callback should not invoke TSAPI Library functions.

2ECEIVING�%VENTS

This section discusses event reception using ACS'ET%VENT0OLL� andACS'ET%VENT"LOCK� on Win32.


ACS'ET%VENT"LOCK� suspends the calling thread until it receives anevent. ACS'ET%VENT0OLL� returns control immediately if no event isavailable, allowing the application to query other input sources or events.

Calling ACS'ET%VENT0OLL� repetitively can unduly consume processortime and resources, to the detriment of other applications. Instead of polling,consider creating a separate thread which calls ACS'ET%VENT"LOCK�, oruse ACS%VENT.OTIFY� to receive asynchronous notifications.


An application may specify a NULL stream handle when callingACS'ET%VENT0OLL� or ACS'ET%VENT"LOCK� to request that theTelephony Services library return the first event available on any of thatapplication’s streams.


3HARING�!#3�3TREAMS�"ETWEEN�4HREADS

The ACS handle value is global to all threads in a given application process.This handle can be accessed in any thread, even threads that did not originallyopen the handle. For example, one thread can call the ACS/PEN3TREAM�function, which returns an ACS handle. A different thread in the same processcan make other TSAPI calls with the returned ACS handle. No special actionis required to enable the second thread to use the handle; it just needs to obtainthe handle value.

While permitted, it normally does not make sense for more than one thread toretrieve events from a single stream. The TSAPI Library allows calls fromdifferent threads to be safely interleaved, but coordination of the resultingactions and events is the responsibility of the application.

-ESSAGE�4RACE

The TSSPY32.EXE program may be used to obtain a trace of messagesflowing between applications and the Telephony Server.


43!0)�ON�5NIX7ARE


Read this section for information on developing TSAPI applications onUnixWare. You do not need to be familiar with the CSTA call model or APIbefore reading further, but you should read Chapter 4, ACS Control Services.


Telephony Services applications must be built with an environment thatsupports the Executable and Linking Format (ELF) and dynamic linking. TheTSAPI header files in this SDK are compatible with the C OptimizedCompilation System provided with the UnixWare Software Development Kit.Using another compiler may require you to modify the header files, forexample, to account for differences in structure alignment, size of enumerateddata types, etc.

TSAPI works with both UnixWare 1.x and UnixWare 2.x, and is thread-safefor 2.x applications.


The TSAPI for UnixWare is implemented as a shared object library,LIBCSTA�SO, and follows the standard conventions for library path searchand dynamic linking. If LIBCSTA�SO�is installed in one of the standarddirectories, it is only necessary to include " LCSTA " in your link step, forexample:

CC� O�MYPROG�MYPROG�C� LCSTA

Note that LIBCSTA�SO depends upon the Networking Support Library,LIBNSL�SO�



This section discusses how to use application control services (ACS) toretrieve events on UnixWare. If you are porting code that uses TelephonyServices, you should read this section to get an overview of the differencesbetween UnixWare and other platforms.


The ACS%VENT.OTIFY� and ACS3ET%32� functions are not providedon the UnixWare platform.

Unlike other Telephony Services platforms, UnixWare does not directlypromote an event-driven programming model, but rather a file-oriented one.To work most effectively in the UnixWare environment, the TSAPI eventstream should appear as a file. The ACS'ET&ILE� function returns theSTREAMS file descriptor associated with an ACS stream handle. Thereturned value may be used like any other file descriptor in an I/Omultiplexing call, such as POLL� or SELECT�, to determine theavailability of TSAPI events. Alternatively, an application may register toreceive the 3)'0/,, signal using the )?3%43)'�IOCTL� call. Refer toProgramming with UNIX System Calls - STREAMS Polling and Multiplexingin the UnixWare SDK documentation.

Do not perform other I/O or control operations directly on this file descriptor.Doing so may lead to unpredictable results from the TSAPI library.

2ECEIVING�%VENTS

This section discusses event reception using ACS'ET%VENT0OLL� andACS'ET%VENT"LOCK� on UnixWare.


ACS'ET%VENT"LOCK� suspends the calling application until it receives anevent. If your application has no other work to perform in the meantime, this isthe simplest and most efficient way to receive events from the TSAPI.


Typically, however, an application needs to respond to input from the user orother sources, and cannot afford to wait exclusively for TSAPI events.ACS'ET%VENT0OLL� returns control immediately if no event is available,allowing the application to query other input sources or events.

Calling ACS'ET%VENT0OLL� repetitively can unduly consume processortime and resources, to the detriment of other applications. Instead of polling,consider multiplexing your input sources via the POLL� system call, orinstalling a 3)'0/,, handler.



-ESSAGE�4RACE

To create a log file of TSAPI messages sent to and received from theTelephony Server, set the shell environment variable #34!42!#% to thepathname of the desired file, prior to starting your application. The log filewill be created if necessary, or appended to if it already exists.

3AMPLE�#ODE

The following pseudo-code illustrates the use of the ACS'ET&ILE�function to set up an asynchronous event handler.

INT�%VENT)S0ENDING��

��HANDLE%VENT��CALLED�WHEN�3)'0/,,�IS�RECEIVED��

VOIDHANDLE%VENT��INT�SIG[

%VENT)S0ENDING��]

VOIDMAIN��VOID


[!#3(ANDLE?TACS(ANDLE�INT ACS?FD�

��

��INSTALL�THE�SIGNAL�HANDLER��SIGNAL��3)'0/,,��HANDLE%VENT�

��OPEN�AN�!#3�STREAM��ACS/PEN3TREAM��ACS(ANDLE��ETC��

��GET�ITS�FILE�DESCRIPTOR��ACS?FD��ACS'ET&ILE��ACS(ANDLE�

��ENABLE�3)'0/,,�ON�NORMAL��READ��EVENTS��IOCTL��ACS?FD��)?3%43)'��3?2$./2-�

��PROCEED�WITH�APPLICATION�PROCESSING��WHILE��NOT$ONE[

IF��%VENT)S0ENDING��[

��RETRIEVE�A�43!0)�EVENT��ACS'ET%VENT0OLL��ACS(ANDLE��ETC��%VENT)S0ENDING��RE ENABLE�HANDLER��SIGNAL��3)'0/,,��HANDLE%VENT�

]��PERFORM�OTHER�BACKGROUND�PROCESSING��

]]


43!0)�ON�(0 58


Read this section for information on developing TSAPI applications onHP-UX. You do not need to be familiar with the CSTA call model or APIbefore reading further, but you should read Chapter 4, ACS Control Services.


The TSAPI header files in this SDK are compatible with the HP-UX CCompiler. Using another compiler may require you to modify the header files,for example, to account for differences in structure alignment, size ofenumerated data types, etc.


The TSAPI for HP-UX is implemented as a shared object library,LIBCSTA�SL, and follows the standard conventions for library path searchand dynamic linking. If LIBCSTA�SL�is installed in one of the standarddirectories, it is only necessary to include " LCSTA" in your link step, forexample:

CC�!E� O�MYPROG�MYPROG�C� LCSTA


This section discusses how to use application control services (ACS) toretrieve events on HP-UX. If you are porting code that uses TelephonyServices, you should read this section to get an overview of the differencesbetween HP-UX and other platforms.



The ACS%VENT.OTIFY� and ACS3ET%32� functions are not providedon the HP-UX platform.

Unlike other Telephony Services platforms, HP-UX does not directly promotean event-driven programming model, but rather a file-oriented one. To workmost effectively in the HP-UX environment, the TSAPI event stream shouldappear as a file. The ACS'ET&ILE� function returns the file descriptorassociated with an ACS stream handle. The returned value may be used likeany other file descriptor in an I/O multiplexing call, such as POLL� orSELECT�, to determine the availability of TSAPI events.

Do not perform other I/O or control operations directly on this file descriptor.Doing so may lead to unpredictable results from the TSAPI library.

2ECEIVING�%VENTS

This section discusses event reception using ACS'ET%VENT0OLL� andACS'ET%VENT"LOCK� on HP-UX.


ACS'ET%VENT"LOCK� suspends the calling application until it receives anevent. If your application has no other work to perform in the meantime, thisis the simplest and most efficient way to receive events from the TSAPI.Typically, however, an application needs to respond to input from the user orother sources, and cannot afford to wait exclusively for TSAPI events.ACS'ET%VENT0OLL� returns control immediately if no event is available,allowing the application to query other input sources or events.

Calling ACS'ET%VENT0OLL� repetitively can unduly consume processortime and resources, to the detriment of other applications. Instead of polling,consider multiplexing your input sources via the POLL� or SELECT�system calls.




-ESSAGE�4RACE

To create a log file of TSAPI messages sent to and received from theTelephony Server, set the shell environment variable #34!42!#% to thepathname of the desired file, prior to starting your application. The log filewill be created if necessary, or appended to if it already exists.


5SING�(IGH�-EMORY�ON�7INDOWS�#LIENTS

Windows client application developers need to be aware of interactionsbetween the TSAPI DLL and Windows memory allocation.

The CSTA Telephony Server client library, csta.dll, is required to occupyfixed memory, because it interfaces to NetWare drivers. As a result, whencsta.dll loads into memory, Windows memory allocation attempts to place it inthe lowest possible memory location by moving all movable memory to higherlocations. If the client loads multiple applications with this same behavior,then memory below one megabyte may become exhausted. A symptom is thatwhen the user attempts to start an application Windows displays "insufficientmemory to start this application."

Developers can code their programs to force Windows to allocate low memorybefore the TSAPI DLL loads, then free up the memory after the DLL loads.The C code below illustrates how to do this. Note that if any other applicationhas already loaded csta.dll the following code has no effect, because csta.dll isfixed in memory.

FOR��I��I��I�[ ��GRAB�AS�MUCH�BASE�MEMORY�AS�POSSIBLE

IF��'LOB$RET�'LOBAL$OS!LLOC��,��.5,,['SELECTOR$OS�;I=��,/7/2$�'LOB$RET�]

ELSE�IF��'LOB$RET�'LOBAL$OS!LLOC��,��.5,,['SELECTOR$OS�;I=��,/7/2$�'LOB$RET�]



ELSE�BREAK�]

FOR��I��I�� I[ ��FREE�SOME�OF�THE�GRABBED�BASE�MEMORY

IF��'SELECTOR$OS�;I=�


['LOBAL$OS&REE�'SELECTOR$OS�;I=�'SELECTOR$OS�;I=��BREAK�]

]

��LOAD�THE��DLL�OR�START�THE�APPLICATION�THAT�WILL�LOAD�IT�

FOR��I��I��I[ ��FREE�ALL�THE�CAPTURED�BASE�MEMORY

IF��'SELECTOR$OS�;I=�['LOBAL$OS&REE�'SELECTOR$OS�;I=�]

ELSE[BREAK�]

]


C h a p t e r 11 CSTA Data Types

4HIS�SECTION�DESCRIBES�THE�DATA�TYPES�USED�BY�THE�FUNCTIONS�AND�MESSAGES�DE FINED�FOR� THE�43!0)�� 4HE�DATA� TYPE�ARE�DIVIDED� INTO� TWO�CATEGORIES�� #34!$ATA�4YPE�WHICH�ARE�ASSOCIATED�WITH� TELEPHONY� FUNCTIONS�AND� )NTERFACE�$ATA4YPES�WHICH� ARE� ASSOCIATED�WITH� THE�!0)� ITSELF� AND� THE� 4ELEPHONY� 3ERVICESCLIENT�SERVER�INTERFACE�

$EVICE�)DENTIFIERS

TYPEDEF�CHAR ��.ULLTYPE�

TYPEDEF�CHAR��$EVICE)$?T;��=�

TYPEDEF�ENUM�#ONNECTION)$?$EVICE?T�[��34!4)#?)$��$9.!-)#?)$��]�#ONNECTION)$?$EVICE?T�

TYPEDEF�STRUCT�#ONNECTION)$?T�[��LONG��CALL)$��$EVICE)$?T��DEVICE)$��#ONNECTION)$?$EVICE?T�DEV)$4YPE�]�#ONNECTION)$?T�


"ASIC�#ALL�#ONTROL�#ONFIRMATION�%VENTS

#34!!LTERNATE#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!!LTERNATE#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!!LTERNATE#ALL#ONF%VENT?T�

#34!!NSWER#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!!NSWER#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!!NSWER#ALL#ONF%VENT?T�

TYPEDEF�ENUM�&EATURE?T�[��&4?#!-0/.��&4?#!,,"!#+��&4?).425$%��]�&EATURE?T�

#34!#ALL#OMPLETION#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!#ALL#OMPLETION#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!#ALL#OMPLETION#ONF%VENT?T�

#34!#LEAR#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!#LEAR#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!#LEAR#ALL#ONF%VENT?T�

#34!#LEAR#ONNECTION#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!#LEAR#ONNECTION#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!#LEAR#ONNECTION#ONF%VENT?T�


#34!#ONFERENCE#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#ONNECTION?T�[��#ONNECTION)$?T��PARTY��$EVICE)$?T��STATIC$EVICE��.5,,�FOR�NOT�PRESENT��]�#ONNECTION?T�

TYPEDEF�STRUCT�#ONNECTION,IST�[��INT��COUNT��#ONNECTION?T��CONNECTION�]�#ONNECTION,IST�

TYPEDEF�STRUCT�#34!#ONFERENCE#ALL#ONF%VENT?T�[��#ONNECTION)$?T��ACTIVE#ALL��#ONNECTION,IST��CONN,IST�]�#34!#ONFERENCE#ALL#ONF%VENT?T�

#34!#ONSULTATION#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!#ONSULTATION#ALL#ONF%VENT?T�[��#ONNECTION)$?T��NEW#ALL�]�#34!#ONSULTATION#ALL#ONF%VENT?T�

#34!$EFLECT#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!$EFLECT#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!$EFLECT#ALL#ONF%VENT?T�

#34!'ROUP0ICKUP#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!'ROUP0ICKUP#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!'ROUP0ICKUP#ALL#ONF%VENT?T�

#34!(OLD#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!(OLD#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!(OLD#ALL#ONF%VENT?T�

#34!-AKE#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!-AKE#ALL#ONF%VENT?T�[��#ONNECTION)$?T��NEW#ALL�]�#34!-AKE#ALL#ONF%VENT?T�


#34!-AKE0REDICITIVE#ALL#ONF%VENT�STRUCTURES

TYPEDEF�ENUM�!LLOCATION3TATE?T�[��!3?#!,,?$%,)6%2%$��!3?#!,,?%34!",)3(%$��]�!LLOCATION3TATE?T�

TYPEDEF�STRUCT�#34!-AKE0REDICTIVE#ALL#ONF%VENT?T�[��#ONNECTION)$?T��NEW#ALL�]�#34!-AKE0REDICTIVE#ALL#ONF%VENT?T�

#34!0ICKUP#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!0ICKUP#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!0ICKUP#ALL#ONF%VENT?T�

#34!2ECONNECT#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!2ECONNECT#ALL#ONF%VENT?T�[]�#34!2ECONNECT#ALL#ONF%VENT?T�

#34!2ETRIEVE#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!2ETRIEVE#ALL#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!2ETRIEVE#ALL#ONF%VENT?T�

#34!4RANSFER#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!4RANSFER#ALL#ONF%VENT?T�[��#ONNECTION)$?T��RESULTING#ALL��#ONNECTION,IST��CONN,IST�]�#34!4RANSFER#ALL#ONF%VENT?T�


#34!5NIVERSAL&AILURE%VENT�STRUCTURES

TYPEDEF�ENUM�#34!5NIVERSAL&AILURE?T�[��'%.%2)#?5.30%#)&)%$��'%.%2)#?/0%2!4)/.��2%15%34?).#/-0!4)",%?7)4(?/"*%#4��6!,5%?/54?/&?2!.'%��/"*%#4?./4?+./7.��).6!,)$?#!,,).'?$%6)#%��).6!,)$?#!,,%$?$%6)#%��).6!,)$?&/27!2$).'?$%34).!4)/.��02)6),%'%?6)/,!4)/.?/.?30%#)&)%$?$%6)#%��02)6),%'%?6)/,!4)/.?/.?#!,,%$?$%6)#%��02)6),%'%?6)/,!4)/.?/.?#!,,).'?$%6)#%��).6!,)$?#34!?#!,,?)$%.4)&)%2��).6!,)$?#34!?$%6)#%?)$%.4)&)%2��).6!,)$?#34!?#/..%#4)/.?)$%.4)&)%2��).6!,)$?$%34).!4)/.��).6!,)$?&%!452%��).6!,)$?!,,/#!4)/.?34!4%��).6!,)$?#2/33?2%&?)$��).6!,)$?/"*%#4?490%��3%#52)49?6)/,!4)/.��'%.%2)#?34!4%?).#/-0!4)"),)49��).6!,)$?/"*%#4?34!4%��).6!,)$?#/..%#4)/.?)$��./?!#4)6%?#!,,��./?(%,$?#!,,��./?#!,,?4/?#,%!2��./?#/..%#4)/.?4/?#,%!2��./?#!,,?4/?!.37%2��./?#!,,?4/?#/-0,%4%��'%.%2)#?3934%-?2%3/52#%?!6!),!"),)49��3%26)#%?"539��2%3/52#%?"539��2%3/52#%?/54?/&?3%26)#%��.%47/2+?"539��.%47/2+?/54?/&?3%26)#%��/6%2!,,?-/.)4/2?,)-)4?%8#%%$%$��#/.&%2%.#%?-%-"%2?,)-)4?%8#%%$%$��'%.%2)#?35"3#2)"%$?2%3/52#%?!6!),!"),)49��/"*%#4?-/.)4/2?,)-)4?%8#%%$%$��%84%2.!,?425.+?,)-)4?%8#%%$%$��/5434!.$).'?2%15%34?,)-)4?%8#%%$%$��'%.%2)#?0%2&/2-!.#%?-!.!'%-%.4��0%2&/2-!.#%?,)-)4?%8#%%$%$��3%15%.#%?.5-"%2?6)/,!4%$��4)-%?34!-0?6)/,!4%$��0!#?6)/,!4%$��3%!,?6)/,!4%$��]�#34!5NIVERSAL&AILURE?T�

TYPEDEF�STRUCT�#34!5NIVERSAL&AILURE#ONF%VENT?T�[


��#34!5NIVERSAL&AILURE?T�ERROR�]�#34!5NIVERSAL&AILURE#ONF%VENT?T�

4ELEPHONY�3UPPLEMENTARY�#ONFIRMATION�%VENTS

#34!3ET-SG7AITING#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!3ET-WI#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!3ET-WI#ONF%VENT?T�

#34!3ET$ND#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!3ET$ND#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!3ET$ND#ONF%VENT?T�

#34!3ET&WD#ONF%VENT�STRUCTURES


TYPEDEF�STRUCT�&ORWARDING)NFO?T�[��&ORWARDING4YPE?T�FORWARDING4YPE��"OOLEAN��FORWARDING/N��$EVICE)$?T��FORWARD$.��.5,,�FOR�NOT�PRESENT��]�&ORWARDING)NFO?T�

TYPEDEF�STRUCT�#34!3ET&WD#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!3ET&WD#ONF%VENT?T�


#34!3ET!GENT3TATE#ONF%VENT�STRUCTURES

TYPEDEF�ENUM�!GENT-ODE?T�[��!-?,/'?).��!-?,/'?/54��!-?./4?2%!$9��!-?2%!$9��!-?7/2+?./4?2%!$9��!-?7/2+?2%!$9��]�!GENT-ODE?T�

TYPEDEF�CHAR��!GENT)$?T;��=�

TYPEDEF�$EVICE)$?T��!GENT'ROUP?T�

TYPEDEF�CHAR��!GENT0ASSWORD?T;��=�

TYPEDEF�STRUCT�#34!3ET!GENT3TATE#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!3ET!GENT3TATE#ONF%VENT?T�

#34!1UERY-WI#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!1UERY-WI#ONF%VENT?T�[��"OOLEAN��MESSAGES�]�#34!1UERY-WI#ONF%VENT?T�

#34!1UERY$ND#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!1UERY$ND#ONF%VENT?T�[��"OOLEAN��DO.OT$ISTURB�]�#34!1UERY$ND#ONF%VENT?T�


#34!1UERY&WD#ONF%VENT�STRUCTURES


TYPEDEF�STRUCT�&ORWARDING)NFO?T�[��&ORWARDING4YPE?T�FORWARDING4YPE��"OOLEAN��FORWARDING/N��$EVICE)$?T��FORWARD$.�]�&ORWARDING)NFO?T�

TYPEDEF�STRUCT�,IST&ORWARD0ARAMETERS?T�[��SHORT��COUNT��&ORWARDING)NFO?T�PARAM;�=�]�,IST&ORWARD0ARAMETERS?T�

TYPEDEF�STRUCT�#34!1UERY&WD#ONF%VENT?T�[��,IST&ORWARD0ARAMETERS?T�FORWARD�]�#34!1UERY&WD#ONF%VENT?T�

#34!1UERY!GENT3TATE#ONF%VENT�STRUCTURES

TYPEDEF�ENUM�!GENT3TATE?T�[��!'?./4?2%!$9��!'?.5,,��!'?2%!$9��!'?7/2+?./4?2%!$9��!'?7/2+?2%!$9��]�!GENT3TATE?T�

TYPEDEF�STRUCT�#34!1UERY!GENT3TATE#ONF%VENT?T�[��!GENT3TATE?T��AGENT3TATE�]�#34!1UERY!GENT3TATE#ONF%VENT?T�

#34!1UERY,AST.UMBER#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!1UERY,AST.UMBER#ONF%VENT?T�[��$EVICE)$?T��LAST.UMBER�]�#34!1UERY,AST.UMBER#ONF%VENT?T�


#34!1UERY$EVICE)NFO#ONF%VENT�STRUCTURES

TYPEDEF�ENUM�$EVICE4YPE?T�[��$4?34!4)/.��$4?,).%��$4?"544/.��$4?!#$��$4?425.+��$4?/0%2!4/2��$4?34!4)/.?'2/50��$4?,).%?'2/50��$4?"544/.?'2/50��$4?!#$?'2/50��$4?425.+?'2/50��$4?/0%2!4/2?'2/50��$4?/4(%2��]�$EVICE4YPE?T�

TYPEDEF�UNSIGNED�CHAR��$EVICE#LASS?T��DEFINE��$#?6/)#%��X��DEFINE��$#?$!4!��X��DEFINE��$#?)-!'%��X��DEFINE��$#?/4(%2��X��

TYPEDEF�STRUCT�#34!1UERY$EVICE)NFO#ONF%VENT?T�[��$EVICE)$?T��DEVICE��$EVICE4YPE?T��DEVICE4YPE��$EVICE#LASS?T��DEVICE#LASS�]�#34!1UERY$EVICE)NFO#ONF%VENT?T�


3TATUS�2EPORTING�#ONFIRMATION�%VENTS

CSTA-ONITOR$EVICE�STRUCTURES

TYPEDEF�LONG��#34!-ONITOR#ROSS2EF)$?T�

TYPEDEF�#34!/BJECT?T��#34!-ONITOR/BJECT?T�

TYPEDEF�UNSIGNED�SHORT��#34!#ALL&ILTER?T��#&?#!,,?#,%!2%$��X��#&?#/.&%2%.#%$��X��#&?#/..%#4)/.?#,%!2%$��X��#&?$%,)6%2%$��X��#&?$)6%24%$��X��#&?%34!",)3(%$��X��#&?&!),%$��X��#&?(%,$��X��#&?.%47/2+?2%!#(%$��X��#&?/2)').!4%$��X��#&?15%5%$��X��#&?2%42)%6%$��X��#&?3%26)#%?).)4)!4%$��X��#&?42!.3&%22%$��X��

TYPEDEF�UNSIGNED�CHAR��#34!&EATURE&ILTER?T��&&?#!,,?).&/2-!4)/.��X��&&?$/?./4?$)3452"��X��&&?&/27!2$).'��X��&&?-%33!'%?7!)4).'��X��

TYPEDEF�UNSIGNED�CHAR��#34!!GENT&ILTER?T��!&?,/''%$?/.��X��!&?,/''%$?/&&��X��!&?./4?2%!$9��X��!&?2%!$9��X��!&?7/2+?./4?2%!$9��X��!&?7/2+?2%!$9��X��

TYPEDEF�UNSIGNED�CHAR��#34!-AINTENANCE&ILTER?T��-&?"!#+?).?3%26)#%��X��-&?/54?/&?3%26)#%��X��

TYPEDEF�STRUCT�#34!-ONITOR&ILTER?T�[��#34!#ALL&ILTER?T�CALL��#34!&EATURE&ILTER?T�FEATURE��#34!!GENT&ILTER?T�AGENT��#34!-AINTENANCE&ILTER?T�MAINTENANCE��"OOLEAN��PRIVATE�]�#34!-ONITOR&ILTER?T�

TYPEDEF�ENUM�#34!-ONITOR4YPE?T�[


��-4?#!,,��-4?$%6)#%��]�#34!-ONITOR4YPE?T�

CSTA-ONITOR#ALL�STRUCTURES

3EE�CSTA-ONITOR$EVICE�STRUCTURES �

CSTA-ONITOR#ALLS6IA$EVICE�STRUCTURES

3EE�CSTA-ONITOR$EVICE�STRUCTURES �

#34!-ONITOR#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!-ONITOR3TART#ONF%VENT?T�[��#34!-ONITOR#ROSS2EF)$?T�MONITOR#ROSS2EF)$��#34!-ONITOR&ILTER?T�MONITOR&ILTER�]�#34!-ONITOR3TART#ONF%VENT?T�

#34!#HANGE-ONITOR&ILTER#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!#HANGE-ONITOR&ILTER#ONF%VENT?T�[��#34!-ONITOR&ILTER?T�FILTER,IST�]�#34!#HANGE-ONITOR&ILTER#ONF%VENT?T�

#34!-ONITOR3TOP#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!-ONITOR3TOP#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!-ONITOR3TOP#ONF%VENT?T�

#34!-ONITOR3TOP%VENT�STRUCTURES

TYPEDEF�STRUECT�#34!-ONITOR3TOP%VENT?T�[��)NVOKE)$?T INVOKE)$�]�#34!-ONITOR3TOP%VENT?T


#ALL�%VENT�2EPORTS

#ALL�%VENT�2EPORT�DATA�STRUCTURES

TYPEDEF�ENUM�,OCAL#ONNECTION3TATE?T�[��#3?.5,,��#3?).)4)!4%��#3?!,%24).'��#3?#/..%#4��#3?(/,$��#3?15%5%$��#3?&!),��]�,OCAL#ONNECTION3TATE?T�

TYPEDEF�ENUM�#34!%VENT#AUSE?T�[��!#4)6%?-/.)4/2��!,4%2.!4%��"539��#!,,?"!#+��#!,,?#!.#%,,%$��#!,,?&/27!2$?!,7!93��#!,,?&/27!2$?"539��#!,,?&/27!2$?./?!.37%2��#!,,?&/27!2$��#!,,?./4?!.37%2%$��#!,,?0)#+50��#!-0?/.��$%34?./4?/"4!).!",%��$/?./4?$)3452"��).#/-0!4)",%?$%34).!4)/.��).6!,)$?!##/5.4?#/$%��+%9?#/.&%2%.#%��,/#+/54��-!).4%.!.#%��.%47/2+?#/.'%34)/.��.%47/2+?./4?/"4!).!",%��.%7?#!,,��./?!6!),!",%?!'%.43��/6%22)$%��0!2+��/6%2&,/7��2%#!,,��2%$)2%#4%$��2%/2$%2?4/.%��2%3/52#%3?./4?!6!),!",%��3),%.4?-/.)4/2��42!.3&%2��425.+3?"539��6/)#%?5.)4?).)4)!4/2��]�#34!%VENT#AUSE?T�


#34!#ALL#LEARED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!#ALL#LEARED%VENT?T�[��#ONNECTION)$?T��CLEARED#ALL��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!#ALL#LEARED%VENT?T�

#34!#ONFERENCED%VENT�STRUCTURES

TYPEDEF�ENUM�$EVICE)$4YPE?T�[��$%6)#%?)$%.4)&)%2��)-0,)#)4?05",)#��%80,)#)4?05",)#?5.+./7.��%80,)#)4?05",)#?).4%2.!4)/.!,��%80,)#)4?05",)#?.!4)/.!,��%80,)#)4?05",)#?.%47/2+?30%#)&)#��%80,)#)4?05",)#?35"3#2)"%2��%80,)#)4?05",)#?!""2%6)!4%$��)-0,)#)4?02)6!4%��%80,)#)4?02)6!4%?5.+./7.��%80,)#)4?02)6!4%?,%6%,�?2%')/.!,?.5-"%2��%80,)#)4?02)6!4%?,%6%,�?2%')/.!,?.5-"%2��%80,)#)4?02)6!4%?,%6%,�?2%')/.!,?.5-"%2��%80,)#)4?02)6!4%?04.?30%#)&)#?.5-"%2��%80,)#)4?02)6!4%?,/#!,?.5-"%2��%80,)#)4?02)6!4%?!""2%6)!4%$��/4(%2?0,!.��]�$EVICE)$4YPE?T�

TYPEDEF�ENUM�$EVICE)$3TATUS?T�[��02/6)$%$��./4?+./7.��./4?2%15)2%$��]�$EVICE)$3TATUS?T�

TYPEDEF�STRUCT�%XTENDED$EVICE)$?T�[��$EVICE)$?T��DEVICE)$��$EVICE)$4YPE?T��DEVICE)$4YPE��$EVICE)$3TATUS?T�DEVICE)$3TATUS�]�%XTENDED$EVICE)$?T�

TYPEDEF�%XTENDED$EVICE)$?T�3UBJECT$EVICE)$?T�

TYPEDEF�STRUCT�#34!#ONFERENCED%VENT?T�[��#ONNECTION)$?T��PRIMARY/LD#ALL��#ONNECTION)$?T��SECONDARY/LD#ALL��3UBJECT$EVICE)$?T�CONF#ONTROLLER��3UBJECT$EVICE)$?T�ADDED0ARTY��#ONNECTION,IST��CONFERENCE#ONNECTIONS��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!#ONFERENCED%VENT?T�


#34!#ONNECTION#LEARED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!#ONNECTION#LEARED%VENT?T�[��#ONNECTION)$?T��DROPPED#ONNECTION��3UBJECT$EVICE)$?T�RELEASING$EVICE��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!#ONNECTION#LEARED%VENT?T�

#34!$ELIVERED%VENT�STRUCTURES

TYPEDEF�%XTENDED$EVICE)$?T�#ALLING$EVICE)$?T�

TYPEDEF�%XTENDED$EVICE)$?T�#ALLED$EVICE)$?T�

TYPEDEF�%XTENDED$EVICE)$?T�2EDIRECTION$EVICE)$?T�

TYPEDEF�STRUCT�#34!$ELIVERED%VENT?T�[��#ONNECTION)$?T��CONNECTION��3UBJECT$EVICE)$?T�ALERTING$EVICE��#ALLING$EVICE)$?T�CALLING$EVICE��#ALLED$EVICE)$?T�CALLED$EVICE��2EDIRECTION$EVICE)$?T�LAST2EDIRECTION$EVICE��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!$ELIVERED%VENT?T�

#34!$IVERTED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!$IVERTED%VENT?T�[��#ONNECTION)$?T��CONNECTION��3UBJECT$EVICE)$?T�DIVERTING$EVICE��#ALLED$EVICE)$?T�NEW$ESTINATION��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!$IVERTED%VENT?T�

#34!%STABLISHED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!%STABLISHED%VENT?T�[��#ONNECTION)$?T��ESTABLISHED#ONNECTION��3UBJECT$EVICE)$?T�ANSWERING$EVICE��#ALLING$EVICE)$?T�CALLING$EVICE��#ALLED$EVICE)$?T�CALLED$EVICE��2EDIRECTION$EVICE)$?T�LAST2EDIRECTION$EVICE��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!%STABLISHED%VENT?T�


#34!&AILED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!&AILED%VENT?T�[��#ONNECTION)$?T��FAILED#ONNECTION��3UBJECT$EVICE)$?T�FAILING$EVICE��#ALLED$EVICE)$?T�CALLED$EVICE��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!&AILED%VENT?T�

#34!(ELD%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!(ELD%VENT?T�[��#ONNECTION)$?T��HELD#ONNECTION��3UBJECT$EVICE)$?T�HOLDING$EVICE��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!(ELD%VENT?T�

#34!.ETWORK2EACHED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!.ETWORK2EACHED%VENT?T�[��#ONNECTION)$?T��CONNECTION��3UBJECT$EVICE)$?T�TRUNK5SED��#ALLED$EVICE)$?T�CALLED$EVICE��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!.ETWORK2EACHED%VENT?T�

#34!/RGINATED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!/RIGINATED%VENT?T�[��#ONNECTION)$?T��ORIGINATED#ONNECTION��3UBJECT$EVICE)$?T�CALLING$EVICE��#ALLED$EVICE)$?T�CALLED$EVICE��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!/RIGINATED%VENT?T�

#34!1UEUED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!1UEUED%VENT?T�[��#ONNECTION)$?T��QUEUED#ONNECTION��3UBJECT$EVICE)$?T�QUEUE��#ALLING$EVICE)$?T�CALLING$EVICE��#ALLED$EVICE)$?T�CALLED$EVICE��2EDIRECTION$EVICE)$?T�LAST2EDIRECTION$EVICE��INT��NUMBER1UEUED��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�


]�#34!1UEUED%VENT?T�

#34!2ETRIEVED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!2ETRIEVED%VENT?T�[��#ONNECTION)$?T��RETRIEVED#ONNECTION��3UBJECT$EVICE)$?T�RETRIEVING$EVICE��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!2ETRIEVED%VENT?T�

#34!3ERVICE)NITIATED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!3ERVICE)NITIATED%VENT?T�[��#ONNECTION)$?T��INITIATED#ONNECTION��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!3ERVICE)NITIATED%VENT?T�

#34!4RANSFERRED%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!4RANSFERRED%VENT?T�[��#ONNECTION)$?T��PRIMARY/LD#ALL��#ONNECTION)$?T��SECONDARY/LD#ALL��3UBJECT$EVICE)$?T�TRANSFERRING$EVICE��3UBJECT$EVICE)$?T�TRANSFERRED$EVICE��#ONNECTION,IST��TRANSFERRED#ONNECTIONS��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION)NFO��#34!%VENT#AUSE?T�CAUSE�]�#34!4RANSFERRED%VENT?T�

&EATURE�%VENT�2EPORTS

#34!#ALL)NFORMATION%VENT�STRUCTURES

TYPEDEF�CHAR��!CCOUNT)NFO?T;��=�

TYPEDEF�CHAR��!UTH#ODE?T;��=�

TYPEDEF�STRUCT�#34!#ALL)NFORMATION%VENT?T�[��#ONNECTION)$?T��CONNECTION��3UBJECT$EVICE)$?T�DEVICE��!CCOUNT)NFO?T��ACCOUNT)NFO��!UTH#ODE?T��AUTHORISATION#ODE�]�#34!#ALL)NFORMATION%VENT?T�


#34!$O.OT$ISTURB%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!$O.OT$ISTURB%VENT?T�[��3UBJECT$EVICE)$?T�DEVICE��"OOLEAN��DO.OT$ISTURB/N�]�#34!$O.OT$ISTURB%VENT?T�

#34!&ORWARDING%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!&ORWARDING%VENT?T�[��3UBJECT$EVICE)$?T�DEVICE��&ORWARDING)NFO?T�FORWARDING)NFORMATION�]�#34!&ORWARDING%VENT?T�

TYPEDEF�STRUCT�#34!-ESSAGE7AITING%VENT?T�[��#ALLED$EVICE)$?T�DEVICE&OR-ESSAGE��3UBJECT$EVICE)$?T�INVOKING$EVICE��"OOLEAN��MESSAGE7AITING/N�]�#34!-ESSAGE7AITING%VENT?T�

!GENT�3TATUS�2EPORT�%VENTS

#34!,OGGED/N%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!,OGGED/N%VENT?T�[��3UBJECT$EVICE)$?T�AGENT$EVICE��!GENT)$?T��AGENT)$��!GENT'ROUP?T��AGENT'ROUP��!GENT0ASSWORD?T�PASSWORD�]�#34!,OGGED/N%VENT?T�

#34!,OGGED/FF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!,OGGED/FF%VENT?T�[��3UBJECT$EVICE)$?T�AGENT$EVICE��!GENT)$?T��AGENT)$��!GENT'ROUP?T��AGENT'ROUP�]�#34!,OGGED/FF%VENT?T�

#34!.OT2EADY%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!.OT2EADY%VENT?T�[��3UBJECT$EVICE)$?T�AGENT$EVICE��!GENT)$?T��AGENT)$�]�#34!.OT2EADY%VENT?T�


#34!2EADY%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!2EADY%VENT?T�[��3UBJECT$EVICE)$?T�AGENT$EVICE��!GENT)$?T��AGENT)$�]�#34!2EADY%VENT?T�

#34!7ORK.OT2EADY%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!7ORK.OT2EADY%VENT?T�[��3UBJECT$EVICE)$?T�AGENT$EVICE��!GENT)$?T��AGENT)$�]�#34!7ORK.OT2EADY%VENT?T�

#34!7ORK2EADY%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!7ORK2EADY%VENT?T�[��3UBJECT$EVICE)$?T�AGENT$EVICE��!GENT)$?T��AGENT)$�]�#34!7ORK2EADY%VENT?T�

3NAPSHOT�3ERVICES

#34!3NAPSHOT$EVICE#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!3NAPSHOT$EVICE$ATA?T�[��INT��COUNT��STRUCT�#34!3NAPSHOT$EVICE2ESPONSE)NFO?T�INFO�]�#34!3NAPSHOT$EVICE$ATA?T�

TYPEDEF�STRUCT�#34!3NAPSHOT$EVICE#ONF%VENT?T�[��#34!3NAPSHOT$EVICE$ATA?T�SNAPSHOT$ATA�]�#34!3NAPSHOT$EVICE#ONF%VENT?T�

#34!3NAPSHOT#ALL#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!3NAPSHOT#ALL$ATA?T�[��INT��COUNT��STRUCT�#34!3NAPSHOT#ALL2ESPONSE)NFO?T�INFO�]�#34!3NAPSHOT#ALL$ATA?T�

TYPEDEF�STRUCT�#34!3NAPSHOT#ALL#ONF%VENT?T�[��#34!3NAPSHOT#ALL$ATA?T�SNAPSHOT$ATA�]�#34!3NAPSHOT#ALL#ONF%VENT?T�


#34!3NAPSHOT$EVICE#ONF%VENT�STRUCTURES

TYPEDEF�ENUM�#34!3IMPLE#ALL3TATE?T�[��#!,,?.5,,��#!,,?0%.$).'��#!,,?/2)').!4%$��#!,,?$%,)6%2%$��#!,,?$%,)6%2%$?(%,$��#!,,?2%#%)6%$��#!,,?%34!",)3(%$��#!,,?%34!",)3(%$?(%,$��#!,,?2%#%)6%$?/.?(/,$��#!,,?%34!",)3(%$?/.?(/,$��#!,,?15%5%$��#!,,?15%5%$?(%,$��#!,,?&!),%$��#!,,?&!),%$?(%,$��]�#34!3IMPLE#ALL3TATE?T�

TYPEDEF�STRUCT�#34!#ALL3TATE?T�[��INT��COUNT��,OCAL#ONNECTION3TATE?T�STATE�]�#34!#ALL3TATE?T�

��5SED�TO�TAKE�A�#34!#ALL3TATE?T�WHICH�CONTAINS�ONLY�TWO��,OCAL#ONNECTION3TATE?T�AND�MATCH�THEM�TO�THE�SET�OF��#34!3IMPLE#ALL3TATE?T�ABOVE��DEFINE�3)-0,%?#!,,?34!4%�CCS �CCS�STAT;�=��CCS�STATE;�=

��

TYPEDEF�STRUCT�#34!3NAPSHOT$EVICE2ESPONSE)NFO?T�[��#ONNECTION)$?T��CALL)DENTIFIER��#34!#ALL3TATE?T�CALL3TATE�]�#34!3NAPSHOT$EVICE2ESPONSE)NFO?T�

TYPEDEF�STRUCT�#34!3NAPSHOT#ALL2ESPONSE)NFO?T�[��3UBJECT$EVICE)$?T�DEVICE/N#ALL��#ONNECTION)$?T��CALL)DENTIFIER��,OCAL#ONNECTION3TATE?T�LOCAL#ONNECTION3TATE�]�#34!3NAPSHOT2ESPONSE)NFO%VENT?T�

#OMPUTING�&UNCTION�3ERVICES

CSTA2OUTE2EGISTER2EQ�STRUCTURES

TYPDEF�STRUCT�#34!2OUTE2EGISTER2EQ?T�[$EVICE)$?T ROUTING$EVICE�

]�#34!2OUTE2EGISTER2EQ?T�


CSTA2OUTE2EGISTER2EQ#ONF%VENT��STRUCTURES

TYPEDEF�LONG��2EGISTER2EQ)$?T�

TYPEDEF�STRUCT�[2EGISTER2EQ)$?T REGISTER2EQ)$�

]�#34!2OUTE2EGISTER2EQ#ONF%VENT?T�

CSTA2OUTE2EGISTER#ANCEL��STRUCTURES

TYPDEF�STRUCT�#34!2OUTE2EGISTER#ANCEL?T�[2EGISTER2EG)$?T ROUTING2EG)$�

]�#34!2OUTE2EGISTER#ANCEL?T�

CSTA2OUTE2EGISTER#ANCEL#ONF%VENT��STRUCTURES

TYPEDEF�STRUCT�[2EGISTER2EG)$?T ROUTING2EG)$�

]�#34!2OUTE2EGISTER#ANCEL#ONF%VENT?T�

CSTA2OUTE2EQUEST%VENT��STRUCTURES

TYPEDEF�ENUM�3ELECT6ALUE?T�[��36?./2-!,��36?,%!34?#/34��36?%-%2'%.#9��36?!#$��36?53%2?$%&).%$��]�3ELECT6ALUE?T�

TYPEDEF�STRUCT�3ET5P6ALUES?T�[��INT��LENGTH��UNSIGNED�CHAR��VALUE�]�3ET5P6ALUES?T�

TYPEDEF�STRUCT�#34!2OUTE2EQUEST%VENT?T�[��2EGISTER2EQ)$?T� REGISTER2EQ)$��2OUTING#ROSS2EF)$?T� ROUTING#ROSS2EF)$��$EVICE)$?T�� CURRENT2OUTE��$EVICE)$?T�� CALLING$EVICE��#ONNECTION)$?T�� ROUTED#ALL��3ELECT6ALUE?T�� ROUTE3EL!LGORITHM��"OOLEAN�� PRIORITY��3ET5P6ALUES?T�� SETUP)NFORMATION�]�#34!2OUTE2EQUEST%VENT?T�

CSTA2OUTE3ELECT��STRUCTURES

TYPEDEF�INT��2ETRY6ALUE?T��DEFINE��NO,IST!VAILABLE� ��DEFINE��NO#OUNT!VAILABLE� �


TYPEDEF�STRUCT�#34!2OUTE3ELECT?T�[��2EGISTER2EQ)$?T REGISTER2EQ)$��2OUTING#ROSS2EF)$?T� ROUTING#ROSS2EF)$��$EVICE)$?T�� ROUTE3ELECTED��2ETRY6ALUE?T�� REMAIN2ETRY��3ET5P6ALUES?T�� SETUP)NFORMATION��"OOLEAN�� ROUTE5SED2EQ�]�#34!2OUTE3ELECT?T�

#34!2E2OUTE2EQUEST%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!2E2OUTE%VENT?T�[��2EGISTER2EQ)$?T REGISTER2EQ)$��2OUTING#ROSS2EF)$?T� ROUTING#ROSS2EF)$�]�#34!2E2OUTE%VENT?T�

CSTA2OUTE5SED%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!2OUTE5SED%VENT?T�[��2EGISTER2EQ)$?T REGISTER2EQ)$��2OUTING#ROSS2EF)$?T� ROUTING#ROSS2EF)$��$EVICE)$?T�� ROUTE5SED��$EVICE)$?T�� CALLING$EVICE��"OOLEAN�� DOMAIN�]�#34!2OUTE5SED%VENT?T�

CSTA2OUTE%ND%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!2OUTE%ND%VENT?T�[��2EGISTER2EQ)$?T REGISTER2EQ)$��2OUTING#ROSS2EF)$?T� ROUTING#ROSS2EF)$��#34!5NIVERSAL&AILURE?T� ERROR6ALUE�]�#34!2OUTE%ND%VENT?T�

CSTA2OUTE%ND��STRUCTURES

TYPEDEF�STRUCT�#34!2OUTE%ND?T�[��2EGISTER2EQ)$?T REGISTER2EQ)$��2OUTING#ROSS2EF)$?T� ROUTING#ROSS2EF)$��#34!5NIVERSAL&AILURE?T� ERROR6ALUE�]�#34!2OUTE%ND?T�


%SCAPE�3ERVICES

CSTA%SCAPE3ERVICE��STRUCTURES

TYPEDEF�STRUCT�#34!%SCAPE3ERVICE?T�[��.ULLTYPE��NULL�]�#34!%SCAPE3ERVICE?T�

#34!%SCAPE3ERVICE#ONF%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!%SCAPE3ERVICE#ONF%VENT?T�[��.ULLTYPE��NULL�]�#34!%SCAPE3ERVICE#ONF%VENT?T�

0RIVATE%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!0RIVATE%VENT?T�[��INT��LENGTH��UNSIGNED�CHAR��DATA�]�#34!0RIVATE%VENT?T�

0RIVATE3TATUS%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!0RIVATE3TATUS%VENT?T�[.ULLTYPE NULL�

]

CSTA0RIVATE3TATUS%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!%SCAPE3ERVICE%VENT#ONF?T[

5NIVERSAL&AILURE?T ERROR�]�

#34!%SCAPE3ERVICE%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!%SCAPE3ERVICE%VENT?T�[.ULLTYPE��NULL�

]�

CSTA%SCAPE3ERVICE#ONF��STRUCTURES

TYPEDEF�STRUCT�CSTA%SCAPE3ERVICE#ONF?T�[#34!5NIVERSAL&AILURE?T ERROR�

]�


CSTA3END0RIVATE%VENT��STRUCTURES

TYPEDEF�STRUCT�CSTA3END0RIVATE%VENT?T�[.ULLTYPE��NULL�

]�

-AINTENANCE�3ERVICES

#34!"ACK)N3ERVICE%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!"ACK)N3ERVICE%VENT?T�[��$EVICE)$?T��DEVICE��#34!%VENT#AUSE?T�CAUSE�]�#34!"ACK)N3ERVICE%VENT?T�

#34!/UT/F3ERVICE%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!/UT/F3ERVICE%VENT?T�[��$EVICE)$?T��DEVICE��#34!%VENT#AUSE?T�CAUSE�]�#34!/UT/F3ERVICE%VENT?T�

CSTA3YS3TAT2EQ�STRUCTURES

TYPEDEF�STRUCT�#34!3YS3TAT2EQ?T��.ULLTYPE� ��NULL�

�#34!3YS3TAT2EQ?T

#34!3YS3TAT2EQ#ONF%VENT�STRUCTURES


TYPEDEF�STRUCT�#34!3YS3TAT2EQ#ONF%VENT?T��3YSTEM3TATUS?T SYSTEM3TATUS�

�#34!3YS3TAT2EQ#ONF%VENT?T


CSTA3YS3TAT3TART�STRUCTURES

TYPEDEF�UNSIGNED�CHAR��3YSTEM3TATUS&ILTER?T��DEFINE�33?)NITIALIZING � �X��DEFINE�33?%NABLED �X��DEFINE�33?.ORMAL �X��DEFINE�33?-ESSAGE,OST �X��DEFINE�33?$ISBALED �X��DEFINE�33?/VERLOAD)MMINENT �X��DEFINE�33?/VERLOAD2EACHED �X��DEFINE�33?/VERLOAD2ELIEVED �X��

TYPEDEF�STRUCT�#34!3YS3TAT3TART?T��3YSTEM3TATUS&ILTER?T STATUS&ILTER�

]�#34!3YS3TAT3TART?T�

#34!3YS3TAT3TART#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!3YS3TAT3TART#ONF%VENT?T��3YSTEM3TATUS&ILTER?T SYSTEM&ILTER�

�#34!3YS3TAT3TART#ONF%VENT?T

CSTA3YS3TAT3TOP�STRUCTURES

TYPEDEF�STRUCT�#34!3YS3TAT3TOP?T��.ULLTYPE NULL�

]�#34!3YS3TAT3TOP?T�

#34!3YS3TAT3TOP#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!3YS3TAT3TOP#ONF%VENT?T��.ULLTYPE NULL�

�#34!3YS3TAT3TOP#ONF%VENT?T

CSTA#HANGE3YS3TAT&ILTER�STRUCTURES

TYPEDEF�STRUCT�#34!#HANGE3YS3TAT&ILTER?T��3YSTEM3TATUS&ILTER?T STATUS&ILTER�

]�#34!#HANGE3YS3TAT&ILTER?T�

#34!#HANGE3YS3TAT&ILTER#ONF%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!#HANGE3YS3TAT&ILER#ONF%VENT?T[

3YSTEM3TATUS&ILTER?T STATUS&ILTER3ELECTED�3YSTEM3TATUS&ILTER?T STATUS&ILTER!CTIVE�

]�#34!#HANGE3YS3TAT&ILTER#ONF%VENT?T�

#34!3YS3TAT%VENT�STRUCTURES


TYPEDEF�STRUCT�#34!3YS3TAT%VENT?T�[[

3YSTEM3TATUS?T SYSTEM3TATUS�]�

#34!3YS3TAT2EQ%VENT�STRUCTURES

TYPEDEF�STRUCT�#34!3YS3TAT2EQ%VENT?T�[.ULLTYPE NULL�

]�#34!3YS3TAT2EQ%VENT?T�

CSTA3YS3TAT2EQ#ONF�STRUCTURES

TYPEDEF�STRUCT�#34!3YS3TAT2EQ#ONF?T�[3YSTEM3TATUS?T SYSTEM3TATUS�

]�#34!3YS3TAT2EQ#ONF?T�

CSTA3YS3TAT%VENT3END�STRUCTURES

TYPEDEF�STRUCT�#34!3YS3TAT%VENT3END?T�[3YSTEM3TATUS?T SYSTEM3TATUS�

]�#34!3YS3TAT%VENT3END?T�

#34!�#ONTROL�3ERVICES

CSTA'ET!0)#APS�STRUCTURES

TYPEDEF�STRUCT #34!'ET!0)#APS?T�[� .ULLTYPE�NULL�

�#34!'ET!0)#APS?T�

#34!'ET!0)#APS#ONF%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!'ET!0)#APS#ONF%VENT?T�[��INT��ALTERNATE#ALL��INT��ANSWER#ALL��INT��CALL#OMPLETION��INT��CLEAR#ALL��INT��CLEAR#ONNECTION��INT��CONFERENCE#ALL��INT��CONSULTATION#ALL��INT��DEFLECT#ALL��INT��PICKUP#ALL��INT��GROUP0ICKUP#ALL��INT��HOLD#ALL��INT��MAKE#ALL��INT��MAKE0REDICTIVE#ALL��INT��QUERY-WI�


��INT��QUERY$ND��INT��QUERY&WD��INT��QUERY!GENT3TATE��INT��QUERY,AST.UMBER��INT��QUERY$EVICE)NFO��INT��RECONNECT#ALL��INT��RETRIEVE#ALL��INT��SET-WI��INT��SET$ND��INT��SET&WD��INT��SET!GENT3TATE��INT��TRANSFER#ALL��INT��EVENT2EPORT��INT��CALL#LEARED%VENT��INT��CONFERENCED%VENT��INT��CONNECTION#LEARED%VENT��INT��DELIVERED%VENT��INT��DIVERTED%VENT��INT��ESTABLISHED%VENT��INT��FAILED%VENT��INT��HELD%VENT��INT��NETWORK2EACHED%VENT��INT��ORIGINATED%VENT��INT��QUEUED%VENT��INT��RETRIEVED%VENT��INT��SERVICE)NITIATED%VENT��INT��TRANSFERRED%VENT��INT��CALL)NFORMATION%VENT��INT��DO.OT$ISTURB%VENT��INT��FORWARDING%VENT��INT��MESSAGE7AITING%VENT��INT��LOGGED/N%VENT��INT��LOGGED/FF%VENT��INT��NOT2EADY%VENT��INT��READY%VENT��INT��WORK.OT2EADY%VENT��INT��WORK2EADY%VENT��INT��BACK)N3ERVICE%VENT��INT��OUT/F3ERVICE%VENT��INT��PRIVATE%VENT��INT��ROUTE2EQUEST%VENT��INT��RE2OUTE��INT��ROUTE3ELECT��INT��ROUTE5SED%VENT��INT��ROUTE%ND%VENT��INT��MONITOR$EVICE��INT��MONITOR#ALL��INT��MONITOR#ALLS6IA$EVICE��INT��CHANGE-ONITOR&ILTER��INT��MONITOR3TOP��INT��MONITOR%NDED��INT��SNAPSHOT$EVICE2EQ��INT��SNAPSHOT#ALL2EQ��INT��ESCAPE3ERVICE��INT��PRIVATE3TATUS%VENT�


��INT��ESCAPE3ERVICE%VENT��INT��ESCAPE3ERVICE#ONF��INT��SEND0RIVATE%VENT��INT��SYS3TAT2EQ��INT��SYS3TAT3TART��INT��SYS3TAT3TOP��INT��CHANGE3YS3TAT&ILTER��INT��SYS3TAT2EQ%VENT��INT��SYS3TAT2EQ#ONF��INT��SYS3TAT%VENT�]�#34!'ET!0)#APS#ONF%VENT?T�

CSTA'ET$EVICE,IST��STRUCTURES

TYPEDEF�ENUM�#34!,EVEL?T�[��#34!?,%6%,��#34!?,%6%,��#34!?,%6%,��#34!?,%6%,��#34!?,%6%,��#34!?,%6%,��]�#34!,EVEL?T�

#34!'ET$EVICE,IST#ONF%VENT��STRUCTURES

TYPEDEF�STRUCT�#34!'ET$EVICE,IST#ONF%VENT?T[

,EVEL?T ACS,EVEL2EQ�INT� TOTAL$EVICES�$EVICE)$?T DEVICE)$S�

]�#34!'ET$EVICE,IST#ONF%VENT?T�

#34!�%VENT�3TRUCTURES

#34!�EVENT�TYPES

�DEFINE #34!2%15%34 ��DEFINE #34!5.3/,)#)4%$ ��DEFINE #34!#/.&)2-!4)/. ��DEFINE� #34!%6%.42%0/24 �

#34!�2EQUEST�%VENT�STRUCTURE

TYPEDEF�STRUCT[


#34!2OUTE2EQUEST%VENT?T ROUTE2EQUEST�


#34!2E2OUTE2EQUEST?T RE2OUTE2EQUEST�#34!%SCAPE3VC2EQ%VENT?T ESCAPE3VC2EQEUST�#34!3YS3TAT2EQ%VENT?T SYS3TAT2EQUEST�

]�U�

]�#34!2EQUEST%VENT�

#34!�%VENT�2EPORT�STRUCTURE

TYPEDEF�STRUCT[

UNION[

#34!2OUTE2EGISTER!BORT%VENT?T��REGISTER!BORT�#34!2OUTE5SED%VENT?T ROUTE5SED�#34!2OUTE%ND%VENT?T ROUTE%ND�#34!0RIVATE%VENT?T PRIVATE%VENT�#34!3YS3TAT%VENT?T SYS3TAT�#34!3YS3TAT%NDED%VENT?T SYS3TAT%NDED�

]U�]�#34!%VENT2EPORT�


#34!�5NSOLICITED�%VENT�STRUCTURE

TYPEDEF�STRUCT[

#34!-ONITOR#ROSS2EF)$?T MONITOR#ROSS2EF)D�UNION[

#34!#ALL#LEARED%VENT?T CALL#LEARED�#34!#ONFERENCED%VENT?T CONFERENCED�#34!#ONNECTION#LEARED%VENT?T CONNECTION#LEARED�#34!$ELIVERED%VENT?T DELIVERED�#34!$IVERTED%VENT?T DIVERTED�#34!%STABLISHED%VENT?T ESTABLISHED�#34!&AILED%VENT?T FAILED�#34!(ELD%VENT?T HELD�#34!.ETWORK2EACHED%VENT?T NETWORK2EACHED�#34!/RIGINATED%VENT?T ORIGINATED�#34!1UEUED%VENT?T QUEUED�#34!2ETRIEVED%VENT?T RETRIEVED�#34!3ERVICE)NITIATED%VENT?T SERVICE)NITIATED�#34!4RANSFERRED%VENT?T TRANSFERRED�#34!#ALL)NFORMATION%VENT?T CALL)NFORMATION�#34!$O.OT$ISTURB%VENT?T DO.OT$ISTURB�#34!&ORWARDING%VENT?T FORWARDING�#34!-ESSAGE7AITING%VENT?T MESSAGE7AITING�#34!,OGGED/N%VENT?T LOGGED/N�#34!,OGGED/FF%VENT?T LOGGED/FF�#34!.OT2EADY%VENT?T NOT2EADY�#34!2EADY%VENT?T READY�#34!7ORK.OT2EADY%VENT?T WORK.OT2EADY�#34!7ORK2EADY%VENT?T WORK2EADY�#34!"ACK)N3ERVICE%VENT?T BACK)N3ERVICE�#34!/UT/F3ERVICE%VENT?T OUT/F3ERVICE�#34!0RIVATE3TATUS%VENT?T PRIVATE3TATUS�#34!-ONITOR%NDED%VENT?T�� MONITOR%NDED�

]�U�

]�#34!5NSOLICITED%VENT�


#34!�#ONFIRMATION�%VENT�STRUCTURE

TYPEDEF�STRUCT�[)NVOKE)$?T INVOKE)$�UNION�[

#34!!LTERNATE#ALL#ONF%VENT?T ALTERNATE#ALL�#34!!NSWER#ALL#ONF%VENT?T ANSWER#ALL�#34!#ALL#OMPLETION#ONF%VENT?T CALL#OMPLETION�#34!#LEAR#ALL#ONF%VENT?T CLEAR#ALL�#34!#LEAR#ONNECTION#ONF%VENT?T�� CLEAR#ONNECTION�#34!#ONFERENCE#ALL#ONF%VENT?T CONFERENCE#ALL�#34!#ONSULTATION#ALL#ONF%VENT?T CONSULTATION#ALL�#34!$EFLECT#ALL#ONF%VENT?T DEFLECT#ALL�#34!0ICKUP#ALL#ONF%VENT?T PICKUP#ALL�#34!'ROUP0ICKUP#ALL#ONF%VENT?T GROUP0ICKUP#ALL�#34!(OLD#ALL#ONF%VENT?T HOLD#ALL�#34!-AKE#ALL#ONF%VENT?T MAKE#ALL�#34!-AKE0REDICTIVE#ALL#ONF%VENT?T� MAKE0REDICTIVE#ALL�#34!1UERY-WI#ONF%VENT?T QUERY-WI�#34!1UERY$ND#ONF%VENT?T QUERY$ND�#34!1UERY&WD#ONF%VENT?T QUERY&WD�#34!1UERY!GENT3TATE#ONF%VENT?T QUERY!GENT3TATE�#34!1UERY,AST.UMBER#ONF%VENT?T QUERY,AST.UMBER�#34!1UERY$EVICE)NFO#ONF%VENT?T QUERY$EVICE)NFO�#34!2ECONNECT#ALL#ONF%VENT?T RECONNECT#ALL�#34!2ETRIEVE#ALL#ONF%VENT?T RETRIEVE#ALL�#34!3ET-WI#ONF%VENT?T SET-WI�#34!3ET$ND#ONF%VENT?T SET$ND�#34!3ET&WD#ONF%VENT?T SET&WD�#34!3ET!GENT3TATE#ONF%VENT?T SET!GENT3TATE�#34!4RANSFER#ALL#ONF%VENT?T TRANSFER#ALL�#34!5NIVERSAL&AILURE#ONF%VENT?T UNIVERSAL&AILURE�#34!-ONITOR#ONF%VENT?T MONITOR3TART�#34!#HANGE-ONITOR&ILTER#ONF%VENT?T CHANGE-ONITOR&ILTER�#34!-ONITOR3TOP#ONF%VENT?T MONITOR3TOP�#34!3NAPSHOT$EVICE#ONF%VENT?T SNAPSHOT$EVICE�#34!3NAPSHOT#ALL#ONF%VENT?T SNAPSHOT#ALL�#34!2OUTE2EGISTER2EQ#ONF%VENT?T ROUTE2EGISTER�#34!2OUTE2EGISTER#ANCEL#ONF%VENT?T ROUTE#ANCEL�#34!%SCAPE3VC#ONF%VENT?T ESCAPE3ERVICE�#34!3YS3TAT2EQ#ONF%VENT?T SYS3TAT2EQ�#34!3YS3TAT3TART#ONF%VENT?T SYS3TAT3TART�#34!3YS3TAT3TOP#ONF%VENT?T SYS3TAT3TOP�#34!#HANGE3YS3TAT&ILTER#ONF%VENT?T CHANGE3YS3TAT&ILTER�

]�U�]�#34!#ONFIRMATION%VENT�


#34!�%VENT?T�STRUCTURE

TYPEDEF�STRUCT[


!#35NSOLICITED%VENT ACS5NSOLICITED�!#3#ONFIRMATION%VENT ACS#ONFIRMATION�#34!2EQUEST%VENT CSTA2EQUEST�#34!5NSOLICITED%VENT CSTA5NSOLICITED�#34!#ONFIRMATION%VENT CSTA#ONFIRMATION�#34!%VENT2EPORT CSTA%VENT2EPORT�

]�EVENT�CHAR HEAP;#34!?-!8?(%!0=�

]�#34!%VENT?T�


C h a p t e r 12 References

;�= %#-!� � 3TANDARD� %#-! �� 3ERVICES� FOR� #OMPUTER 3UPPORTED4ELECOMMUNICATIONS�!PPLICATIONS��#34!� �*UNE��

;�= %#-!� � 3TANDARD� %#-! �� 0ROTOCOL� FOR� #OMPUTER 3UPPORTED4ELECOMMUNICATIONS�!PPLICATIONS��#34!� �*UNE��

;�= !PPLE� #OMPUTER� � )NSIDE� -ACINTOSH�� 0OWER� 0#� 3YSTEM� 3OFTWARE�� !DDISON7ESLEY��

;�= !PPLE� #OMPUTER� � )NSIDE� -ACINTOSH�� )NTERAPPLICATION� #OMMUNICATION�!DDISON�7ESLEY��

;�= !PPLE�#OMPUTER� �)NSIDE�-ACINTOSH��-EMORY��!DDISON�7ESLEY��;�= !PPLE� #OMPUTER� � )NSIDE� -ACINTOSH�� /PERATING� 3YSTEM� 5TILITIES�� !DDISON

7ESLEY��;�= !PPLE� #OMPUTER� � )NSIDE� -ACINTOSH�� 0OWER0#� 3YSTEM� 3OFTWARE�� !DDISON

7ESLEY��

4ELEPHONY�3ERVICES�!0) ) �

Index!!BSTRACT�� !#$��

!GENT�� !#3��

5NSOLICITED�%VENTS�� !#3�$ATA�4YPES��

#OMMON�� %VENT��

!#3�STREAM!BORTING�� !CCESS�� #HECKING�ESTABLISHMENT�OF�� #LOSING�� #34!�SERVICES�AVAILABLE�ON�� &REEING�ASSOCIATED�RESOURCES�� -ULTIPLE�� /PENING�� 0ER�ADVERTISED�SERVICE�� 2ECEIVING�EVENTS�ON�� 2ELEASING�� 3ENDING�REQUESTS�AND�RESPONSES�OVER��

ACS!BORT3TREAM�� ACS!BORT3TREAM�� ACS#LOSE3TREAM�� ACS#LOSE3TREAM�� !#3#LOSE3TREAM#ONF%VENT�� ACS%NUM3ERVER.AMES��

-ACINTOSH�� ACS%VENT.OTIFY��

-ACINTOSH�� 7INDOWS��

ACS%VENT.OTIFY��7INDOWS�/3�� ACS&LUSH%VENT1UEUE�� ACS'ET%VENT"LOCK�� ACS'ET%VENT"LOCK�� ACS'ET%VENT0OLL�� ACS'ET&ILE��5NIX7ARE�� ACS(ANDLE��

&REEING�� ACS/PEN3TREAM�� !#3/PEN3TREAM#ONF%VENT��

ACS1UERY!UTH)NFO�� ACS3ET%32��

-ACINTOSH�� 7INDOWS��

ACS3ET%32��/3�� !#35NIVERSAL&AILURE#ONF%VENT�� !#35NIVERSAL&AILURE%VENT��

$RIVER�ERRORS�� 0OSSIBLE�VALUES�� 3ECURITY�DATABASE�ERRORS�� 4SERVER�OPERATION�ERRORS��

!DMINISTRATION�� ADVERTISED�SERVICE�� !DVERTISED�SERVICES

'ETTING�LIST�OF�AVAILABLE�� !GENT�&EATURE�%VENT�2EPORTS��

3EE�&EATURE�%VENT��!GENT�� !0)�#ONTROL�3ERVICES

3EE�!#3!PPLICATION�#ALL�2OUTING�� !PPLICATION�DOMAIN�� !PPLICATION�0ROGRAMMING�)NTERFACE�#ONTROL3ERVICES

3EE�!#3!PPLICATIONS�� !RCHITECTURE�� !TTENDANT�� !UTOMATIC�#ALL�$ISTRIBUTION

3EE�!#$""ASIC�#ALL�#ONTROL

#ONFIRMATION�%VENTS�� 3ERVICES��

"ASIC�#ALL�#ONTROL�3ERVICES�� ##ALL��

!CTIVE�� !LERTING�� "ASIC�� #OMPLEX�� (ELD�� )DENTIFIER��

-ANAGEMENT��


5NIQUENESS�� -ODEL�� 3TATE��

#OMMON�� #OMPOUND�� 3IMPLE��

#ALL�CONTROL�SERVICE�� #ALL�MONITORING�SERVICE�� #ALL�ORIGINATION�� #ALL�ROUTING�SERVICE

3EE�2OUTING#ALL�3NAPSHOT�3ERVICES�� #ALL�STATUS�EVENT�REPORTS

3EE�%VENT�REPORTS#ALL TYPE�MONITOR�� #AUSE�CODE�DEFINITIONS�� #LIENT��

,IBRARY�� 3UPPORTED��

#LIENT�SERVER�MODEL�� #OMMUNICATIONS�RELATIONSHIP

3EE�#ALL#OMPUTER�4ELEPHONY�)NTEGRATION

3EE�#4)#OMPUTER 3UPPORTED�4ELECOMMUNICATIONS!PPLICATIONS

3EE�#34!#OMPUTING

$OMAIN�� &UNCTION�� 3UB DOMAIN��

#OMPUTING�&UNCTION�3ERVICES�� #ONNECTION��

!TTRIBUTES)DENTIFIER��

)N�EVENT�REPORT�� )NVALID�� 2EUSE�� 5NIQUENESS�� 5PDATE��

3TATE��

!LERTING�� #ONNECTED�� &AILED��

(ELD�� )NITIATED�� ,OCAL�� .ULL�� 1UEUED��

#34!�� #OMPUTING�&UNCTION�3ERVICES�� #ONFIRMATION�%VENT�STRUCTURE�� #ONFIRMATION�%VENTS�� #ONTROL�3ERVICES�� $ATA�TYPES�� %VENT

2EPORT�STRUCTURE�� 3TRUCTURES�� 4YPES��

%VENT�$ATA�4YPES�� %VENT?T�STRUCTURE�� 2EQUEST�%VENT�STRUCTURE�� 3ERVICES��

!VAILABLE�ON�!#3�STREAM�� 5NSOLICITED�%VENT�STRUCTURE��

#34!�5NIVERSAL�&AILURE#ONFERENCE�-EMBER�,IMIT�%XCEEDED�� #34!�$RIVER�)NTERFACE�%RRORS�� $UPLICATE�)NVOCATION�� %XTERNAL�4RUNK�,IMIT�%XCEEDED�� 'ENERIC�/PERATION�� 'ENERIC�/PERATION�2EJECTION�� 'ENERIC�0ERFORMANCE�-ANAGEMENT�%RROR� ��'ENERIC�3TATE�)NCOMPATIBILITY�� 'ENERIC�3UBSCRIBED�2ESOURCE�!VAILABILITY%RROR�� 'ENERIC�3YSTEM�2ESOURCE�!VAILABILITY%RROR�� )NCORRECT�/BJECT�3TATE�� )NVALID�!LLOCATION�3TATE�� )NVALID�#ALLED�$EVICE�� )NVALID�#ALLING�$EVICE�� )NVALID�#ROSS�2EF�)$�� )NVALID�#34!�#ALL�)DENTIFIER�� )NVALID�#34!�#ONNECTION�)DENTIFIER�� )NVALID�#34!�#ONNECTION�)DENTIFIER�&OR!CTIVE�#ALL�� )NVALID�#34!�$EVICE�)DENTIFIER��


)NVALID�$ESTINATION�� )NVALID�&EATURE�� )NVALID�&ORWARDING�$ESTINATION�� )NVALID�/BJECT�4YPE�� .ETWORK�"USY�� .ETWORK�/UT�/F�3ERVICE�� .O�!CTIVE�#ALL�� .O�#ALL�4O�!NSWER�� .O�#ALL�4O�#LEAR�� .O�#ALL�4O�#OMPLETE�� .O�#ONNECTION�4O�#LEAR�� .O�(ELD�#ALL�� /BJECT�-ONITOR�,IMIT�%XCEEDED�� /BJECT�NOT�+NOWN�� /PERATION�ERRORS�� /VERALL�-ONITOR�,IMIT�%XCEEDED�� 0!#�6IOLATED�� 0ERFORMANCE�,IMIT�%XCEEDED�� 0ERFORMANCE�MANAGEMENT�ERRORS�� 0RIVATE�$ATA�ERRORS�� 0RIVILEGE�6IOLATION�ON�#ALLED�$EVICE�� 0RIVILEGE�6IOLATION�ON�#ALLING�$EVICE�� 0RIVILEGE�6IOLATION�ON�3PECIFIED�$EVICE�� 2EQUEST�)NCOMPATIBLE�WITH�/BJECT�� 2ESOURCE�"USY�� 2ESOURCE�/UT�/F�3ERVICE�� 3EAL�6IOLATED�� 3ECURITY�ERRORS�� 3ECURITY�6IOLATION�� 3EQUENCE�.UMBER�6IOLATED�� 3ERVICE�"USY�� 3TATE�INCOMPATIBILITY�ERRORS�� 3UBSCRIBED�RESOURCE�AVAILABILITY�ERRORS�� 3YSTEM�RESOURCE�AVAILABILITY�ERRORS�� 4IME�3TAMP�%RROR�� 43!0)�ERRORS�� 5NRECOGNIZED�/PERATION�� 5NSPECIFIED�ERRORS�� 5NSPECIFIED�3ECURITY�%RROR�� 6ALUE�/UT�/F�2ANGE��

CSTA!LTERNATE#ALL�� #34!!LTERNATE#ALL#ONF%VENT�� #34!!LTERNATE#ALL#ONF%VENT�STRUCTURES�� CSTA!NSWER#ALL��

#34!!NSWER#ALL#ONF%VENT�� #34!"ACK)N3ERVICE%VENT�� #34!"ACK)N3ERVICE%VENT�STRUCTURES�� CSTA#ALL#LEARED%VENT�� #34!#ALL#LEARED%VENT�STRUCTURES�� #34!#ALL#OMPLETETION#ONF%VENT�STRUCTURES�� CSTA#ALL#OMPLETION�� #34!#ALL#OMPLETION#ONF%VENT�� #34!#ALL)NFO%VENT�� #34!#ALL)NFORMATION%VENT�STRUCTURES�� CSTA#HANGE-ONITOR&ILTER�� #34!#HANGE-ONITOR&ILTER#ONF%VENT�� #34!#HANGE-ONITOR&ILTER#ONF%VENT�STRUCTURES�� CSTA#HANGE3YS3TAT&ILTER�STRUCTURES�� CSTA#HANGE3YS3TAT&ILTER�� #34!#HANGE3YS3TAT&ILTER#ONF%VENT�� #34!#HANGE3YS3TAT&ILTER#ONF%VENT�STRUCTURES�� CSTA#LEAR#ALL�� #34!#LEAR#ALL#ONF%VENT�� #34!#LEAR#ALL#ONF%VENT�STRUCTURES�� CSTA#LEAR#ONNECTION�� #34!#LEAR#ONNECTION#ONF%VENT�� #34!#LEAR#ONNECTION#ONF%VENT�STRUCTURES�� CSTA#ONFERENCE#ALL�� #34!#ONFERENCE#ALL#ONF%VENT�� #34!#ONFERENCE#ONF%VENT�STRUCTURES�� CSTA#ONFERENCED%VENT�� #34!#ONFERENCED%VENT�STRUCTURES�� #34!#ONNECTION#LEARED%VENT�� #34!#ONNECTION#LEARED%VENT�STRUCTURES�� CSTA#ONSULTATION#ALL�� #34!#ONSULTATION#ALL#ONF%VENT�� #34!#ONSULTATION#ALL#ONF%VENT�STRUCTURES�� CSTA$EFLECT#ALL�� #34!$EFLECT#ALL#ONF%VENT�� #34!$EFLECT#ALL#ONF%VENT�STRUCTURES�� #34!$ELIVERED%VENT�� #34!$ELIVERED%VENT�STRUCTURES�� #34!$IVERTED%VENT�� #34!$IVERTED%VENT�STRUCTURES�� #34!$O.OT$ISTURB%VENT�� #34!$O.OT$ISTURB%VENT�STRUCTURES��


CSTA%SCAPE3ERVICE��STRUCTURES�� CSTA%SCAPE3ERVICE�� CSTA%SCAPE3ERVICE#ONF��STRUCTURES�� CSTA%SCAPE3ERVICE#ONF�� #34!%SCAPE3ERVICE#ONF%VENT�� #34!%SCAPE3ERVICE#ONF%VENT��STRUCTURES�� #34!%SCAPE3ERVICE%VENT��STRUCTURES�� #34!%SCAPE3ERVICE2EQ�� #34!%STABLISHED%VENT�� #34!%STABLISHED%VENT�STRUCTURES�� #34!%VENT#AUSE?T�� #34!&AILED%VENT�� #34!&AILED%VENT�STRUCTURES�� #34!&ORWARDING%VENT�� #34!&ORWARDING%VENT�STRUCTURES�� CSTA'ET!0)#APS�� CSTA'ET!0)#APS�STRUCTURES�� CSTA'ET!0)#APS�� #34!'ET!0)#APS#ONF%VENT�� #34!'ET!0)#APS#ONF%VENT��STRUCTURES�� CSTA'ET$EVICE,IST��STRUCTURES�� CSTA'ET$EVICE,IST�� #34!'ET$EVICE,IST#ONF%VENT�� #34!'ET$EVICE,IST#ONF%VENT��STRUCTURES�� CSTA'ROUP0ICKUP#ALL�� #34!'ROUP0ICKUP#ALL#ONF%VENT�� #34!'ROUP0ICKUP#ALL#ONF%VENT�STRUCTURES�� #34!(ELD%VENT�� #34!(ELD%VENT�STRUCTURES�� CSTA(OLD#ALL�� #34!(OLD#ALL#ONF%VENT�� #34!(OLD#ALL#ONF%VENT�STRUCTURES�� #34!,OGGED/FF%VENT�� #34!,OGGED/FF%VENT�STRUCTURES�� #34!,OGGED/N%VENT�� #34!,OGGED/N%VENT�STRUCTURES�� CSTA-AKE#ALL�� #34!-AKE#ALL#ONF%VENT�� #34!-AKE#ALL#ONF%VENT�STRUCTURES�� #34!-AKE0REDICITIVE#ALL#ONF%VENT�STRUCTURES�� CSTA-AKE0REDICTIVE#ALL�� #34!-AKE0REDICTIVE#ALL#ONF%VENT�� #34!-ESSAGE7AITING%VENT�� CSTA-ONITOR#ALL�STRUCTURES��

CSTA-ONITOR#ALL�� CSTA-ONITOR#ALLS6IA$EVICE�STRUCTURE�� CSTA-ONITOR#ALLS6IA$EVICE�� #34!-ONITOR#ONF%VENT�� #34!-ONITOR#ONF%VENT�STRUCTURES�� CSTA-ONITOR$EVICE�� #34!-ONITOR%NDED%VENT�� #34!-ONITOR&ILTER?T�� CSTA-ONITOR3TOP�� #34!-ONITOR3TOP#ONF%VENT�� #34!-ONITOR3TOP#ONF%VENT�STRUCTURES�� #34!-ONITOR3TOP%VENT�STRUCTURES�� #34!.ETWORK2EACHED%VENT�� #34!.ETWORK2EACHED%VENT�STRUCTURES�� #34!.OT2EADY%VENT�� #34!.OT2EADY%VENT�STRUCTURES�� #34!/RGINATED%VENT�STRUCTURES�� #34!/RIGINATED%VENT�� #34!/UT/F3ERVICE%VENT�� #34!/UT/F3ERVICE%VENT�STRUCTURES�� CSTA0ICKUP#ALL�� #34!0ICKUP#ALL#ONF%VENT�� #34!0ICKUP#ALL#ONF%VENT�STRUCTURES�� #34!0RIVATE%VENT�� #34!0RIVATE3TATUS%VENT�� CSTA0RIVATE3TATUS%VENT��STRUCTURES�� CSTA1UERY!GENT3TATE�� #34!1UERY!GENT3TATE#ONF%VENT�� #34!1UERY!GENT3TATE#ONF%VENT�STRUCTURE�� CSTA1UERY#ALL-ONITOR�� #34!1UERY#ALL-ONITOR#ONF%VENT�� CSTA1UERY$EVICE)NFO�� #34!1UERY$EVICE)NFO#ONF%VENT�� #34!1UERY$EVICE)NFO#ONF%VENT�STRUCTURES�� #34!1UERY$ND#ONF%VENT�� CSTA1UERY$O.OT$ISTURB�� #34!1UERY$O.OT$ISTURB#ONF%VENT�STRUCTURES�� CSTA1UERY&WD�� #34!1UERY&WD#ONF%VENT�� #34!1UERY&WD#ONF%VENT�STRUCTURES�� CSTA1UERY,AST.UMBER�� #34!1UERY,AST.UMBER#ONF%VENT�� #34!1UERY,AST.UMBER#ONF%VENT�STRUCTURES��


CSTA1UERY-SG7AITING)ND�� #34!1UERY-SG7AITING)ND#ONF%VENT�STRUCTURES�� #34!1UERY-WI#ONF%VENT�� #34!1UEUED%VENT�� #34!1UEUED%VENT�STRUCTURES�� #34!2EADY%VENT�� #34!2EADY%VENT�STRUCTURES�� CSTA2ECONNECT#ALL�� #34!2ECONNECT#ALL#ONF%VENT�� #34!2ECONNECT#ALL#ONF%VENT�STRUCTURES�� #34!2E2OUTE2EQUEST%VENT�� #34!2E2OUTE2EQUEST%VENT��STRUCTURES�� CSTA2ETRIEVE#ALL�� #34!2ETRIEVE#ALL#ONF%VENT�� #34!2ETRIEVE#ALL#ONF%VENT�STRUCTURES�� #34!2ETRIEVED%VENT�� #34!2ETRIEVED%VENT�STRUCTURES�� CSTA2OUTE%ND��STRUCTURES�� CSTA2OUTE%ND�� #34!2OUTE%ND%VENT�� CSTA2OUTE%ND%VENT��STRUCTURES�� CSTA2OUTE%ND)NV�� #34!2OUTE2EGISTER!BORT%VENT�� CSTA2OUTE2EGISTER#ANCEL��STRUCTURES�� CSTA2OUTE2EGISTER#ANCEL�� #34!2OUTE2EGISTER#ANCEL#ONF%VENT�� CSTA2OUTE2EGISTER#ANCEL#ONF%VENT��STRUCTURES�� CSTA2OUTE2EGISTER2EQ�STRUCTURES�� CSTA2OUTE2EGISTER2EQ�� #34!2OUTE2EGISTER2EQ#ONF%VENT�� CSTA2OUTE2EGISTER2EQ#ONF%VENT��STRUCTURES�� #34!2OUTE2EQUEST%VENT�� CSTA2OUTE2EQUEST%VENT��STRUCTURES�� CSTA2OUTE3ELECT��STRUCTURES�� CSTA2OUTE3ELECT�� CSTA2OUTE3ELECT)NV�� #34!2OUTE5SED%VENT�� CSTA2OUTE5SED%VENT��STRUCTURES�� CSTA3END0RIVATE%VENT��STRUCTURES�� CSTA3END0RIVATE%VENT�� #34!3ERVICE)NITIATED%VENT�� #34!3ERVICE)NITIATED%VENT�STRUCTURES�� CSTA3ET!GENT3TATE��

#34!3ET!GENT3TATE#ONF%VENT�� #34!3ET!GENT3TATE#ONF%VENT�STRUCTURES�� #34!3ET$ND#ONF%VENT�� #34!3ET$ND#ONF%VENT�STRUCTURES�� CSTA3ET$O.OT$ISTURB�� CSTA3ET&ORWARDING�� #34!3ET&WD#ONF%VENT�� #34!3ET&WD#ONF%VENT�STRUCTURES�� #34!3ET-SGE7AITING#ONF%VENT�STRUCTURES�� CSTA3ET-SG7AITING)ND�� #34!3ET-WI#ONF%VENT�� #34!3NAPSHOT#ALL#ONF%VENT�� #34!3NAPSHOT#ALL#ONF%VENT�STRUCTURES�� CSTA3NAPSHOT#ALL2EQ�� #34!3NAPSHOT$EVICE#ONF%VENT�� #34!3NAPSHOT$EVICE#ONF%VENT�STRUCTURES�� CSTA3NAPSHOT$EVICE2EQ�� CSTA3YS3TAT%NDED%VENT�� #34!3YS3TAT%VENT�� #34!3YS3TAT%VENT�STRUCTURES�� CSTA3YS3TAT%VENT3END�STRUCTURES�� CSTA3YS3TAT%VENT3END�� CSTA3YS3TAT2EQ�STRUCTURES�� CSTA3YS3TAT2EQ�� CSTA3YS3TAT2EQ#ONF�STRUCTURES�� CSTA3YS3TAT2EQ#ONF�� #34!3YS3TAT2EQ#ONF%VENT�� #34!3YS3TAT2EQ#ONF%VENT�STRUCTURES�� #34!3YS3TAT2EQ%VENT�� #34!3YS3TAT2EQ%VENT�STRUCTURES�� CSTA3YS3TAT3TART�STRUCTURES�� CSTA3YS3TAT3TART�� #34!3YS3TAT3TART#ONF%VENT�� #34!3YS3TAT3TART#ONF%VENT�STRUCTURES�� CSTA3YS3TAT3TOP�STRUCTURES�� CSTA3YS3TAT3TOP�� #34!3YS3TAT3TOP#ONF%VENT�� #34!3YS3TAT3TOP#ONF%VENT�STRUCTURES�� CSTA4RANSFER#ALL�� #34!4RANSFER#ALL#ONF%VENT�� #34!4RANSFERED%VENT�STRUCTURES�� #34!4RANSFERRED%VENT�� #34!5NIVERSAL&AILURE#ONF%VENT�� #34!5NIVERSAL&AILURE%VENT�STRUCTURES��


#34!7ORK.OT2EADY%VENT�� #34!7ORK.OT2EADY%VENT�STRUCTURES�� #34!7ORK2EADY%VENT�� #34!7ORK2EADY%VENT�STRUCTURES�� #4)��

,INK�� ,INK�HARDWARE��

#4)�LINK�� $$ATA�4YPES

!#3�� DEFAULT�ROUTING�SERVER��

3EE�2OUTING��$EFAULT�2OUTING�3ERVER�� $EVICE��

!TTRIBUTE�� #LASS��

$ATA�� )MAGE�� /THER�� 6OICE��

)DENTIFIER�� $YNAMIC�� )NVALID�� -ANAGEMENT�� 2EUSE�� 3TATIC�� 3TATIC�3HORT�&ORM�� 5NIQUENESS�� 5PDATE��

)DENTIFIERS�� -ONITORING�SERVICE�� 1UERY

&OR�CONTROLLABLE�DEVICES�� 3TATE��

3TATE�CHANGE�� 4YPE��

!#$�� !#$�GROUP�� "UTTON�� "UTTON�GROUP�� ,INE�� ,INE�GROUP�� /PERATOR�� /PERATOR�GROUP�� 3TATION��

3TATION�GROUP�� 4RUNK�� 4RUNK�GROUP��

$EVICE�3NAPSHOT�3ERVICE�� $EVICE TYPE�MONITOR�� $IRECTORY�NUMBER�� $ISTRIBUTION�� $OMAIN�� $RIVER�!#3�(ANDLE�2EJECTION�� $RIVER�!#3(ANDLE�4ERMINATION�� $RIVER�ERRORS��

!#3�(ANDLE�2EJECTION�� !#3(ANDLE�4ERMINATION�� $UPLICATE�!#3(ANDLE�� 'ENERIC�2EJECTION�� )NVALID�!#3�2EQUEST�� )NVALID�#LASS�2EJECTION�� ,INK�5NAVAILABLE�� /!-�)N�5SE�� 2ESOURCE�,IMITATION��

%%#-!��

!DDRESS�� %RROR

$RIVER3EE�$RIVER�%RRORS��

4SERVER3EE�43ERVER�%RRORS��

4SERVER�"AD�$EVICE�2ECORD�� 4SERVER�"AD�0ASSWORD�/R�,OGIN�� 4SERVER�"AD�3$"�,EVEL�� 4SERVER�"AD�3ERVER�)$�� 4SERVER�"AD�3TREAM�4YPE�� 4SERVER�$EVICE�.OT�/N�,IST�� 4SERVER�$EVICE�.OT�3UPPORTED�� 4SERVER�%XCEPTION�,IST�� 4SERVER�)NSUFFICIENT�0ERMISSION�� 4SERVER�.O�!WAY�0ERMISSION�� 4SERVER�.O�!WAY�7ORKTOP�� 4SERVER�.O�$EVICE�2ECORD�� 4SERVER�.O�(OME�0ERMISSION�� 4SERVER�.O�3$"�� 4SERVER�.O�3$"�#HECK�.EEDED�� 4SERVER�.O�5SER�2ECORD��


4SERVER�3$"�#HECK�.EEDED�� 4SERVER�5SERS�2ESTRICTED�(OME��

%SCAPE3ERVICE��

%SCAPE�3ERVICE�� !PPLICATION�AS�#LIENT�� $RIVER�3WITCH�AS�THE�#LIENT�� -ODEL��

%UROPEAN�#OMPUTER�-ANUFACTURERS�!SSOCIATION3EE�%#-!

%VENT#AUSE�2ELATIONSHIPS�� $ATA�4YPES��5NSOLICITED�� 3ERVICE�2OUTINE��%32��

!LSO�SEE�ACS3ET%32)NITIALIZING��

5NSOLICITED�� %VENT�REPORT�� %VENTS��

!SYNCHRONOUS�� "LOCKING�FOR�� #HRONOLOGICAL�ORDER�� #ONFIRMATION�� $ATA�STRUCTURES�� &EATURE�� &ROM�ALL�STREAMS�� 0OLLING�FOR�� 0REVENTING�QUEUE�OVERFLOW�� 5NSOLICITED��

&&EATURE

%VENT!GENT�� !GENT�3TATUS�� 5NSOLICITED��

&EATURE�EVENT�� &EATURE�STATE�� ''ENERIC�3TATE�)NCOMPATIBILITY�� ((ANDLE

2EGISTER�2EQUEST�)$�� 2OUTING�#ROSS 2EFERENCE�)$��

(OLD�CALL�REQUEST��

))DENTIFIER

3EE�43!0)�0ROGRAMMING�(ANDLE)INVOKE)$

#ORRELATING�RESPONSES�� )NTEGRATION�� )NTERCONNECTION�3ERVICE�"OUNDARY�� )NTRODUCTION�� )NVOKE)$

!PPLICATION�GENERATED�� #ORRELATING�RESPONSES�� )N�CONFIRMATION�EVENT�� )N�SERVICE�REQUEST�� ,IBRARY�GENERATED�� 4YPE��

)3$.�� ,,OGICAL

!SSOCIATION�� $EVICE�� ,INK��

--AINTENANCE�3ERVICES�� ..ET7ARE�./3�� //BJECT

3EE�43!0)�PROGRAMMING�OBJECT/PERATING�SYSTEM�SPECIFICS��

-ACINTOSH�� /3�� 5NIX7ARE�� 7INDOWS�.4�AND�7INDOWS��

/UTSTANDING�2EQUESTS�,IMIT�%XCEEDED�� 00ARTY�� 0"8�DRIVER�� 0"8�$RIVERS�� 0ERMISSIONS

3EE�!DMINISTRATION0RIVATE%VENT��STRUCTURES�� 0RIVATE3TATUS%VENT��STRUCTURES�� 0ROGRAMMING�HANDLE

3EE�43!0)�PROGRAMMING�HANDLE0ROGRAMMING�.OTES��


11UERY

#ALL�#ALL�-ONITORING�� 1UERY�SERVICE�� 22EFERENCES�� 2EGISTER�2EQUEST�)$�� 2OUTE

)NVALID�� 2EQUEST�� 2E ROUTE�� SUCCESSFUL�ROUTE�� 5SED��

ROUTE2EGISTER2EQ)$$URATION�� 5NIQUENESS��

2OUTING!CTUAL�DESTINATION�� #ANCEL�� #ROSS REFERENCE�IDENTIFIER�� $EFAULT�ROUTING�SERVER�� $EVICE�� %VENTS�� &UNCTIONS�� 3WITCH�DEFAULT�ROUTE�� 4ERMINATING��

2OUTING�#ROSS 2EFERENCE�)$�� 2OUTING�DEVICE�� 2OUTING�0ROCEDURE�� 2OUTING�2EGISTRATION�� 2OUTING�2EGISTRATION�&UNCTIONS�AND�%VENTS�� 2OUTING�SERVICE�� ROUTING#ROSS2EF)$

$URATION�� 5NIQUENESS��

33ECURITY

3EE�!DMINISTRATION3ERVER��

,IBRARY�� 3UPPORTED��

3ERVICE�� "OUNDARY�� $ESCRIPTION��

3ERVICES

,IBRARY�� 3NAPSHOT�3ERVICES�� 3TATE

3EE�#ALL�3TATE3EE�#ONNECTION�3TATE3EE�$EVICE�3TATE

3TATUS�2EPORTING#ONFIRMATION�%VENTS�� &UNCTIONS�� 3ERVICES��

3WITCH$RIVER��

)NTERFACE�� )NDEPENDENT�� 3PECIFIC��

3WITCHING$OMAIN�� &UNCTION�� 3UB DOMAIN��

-ODEL�� 3WITCHING�&UNCTION�3ERVICES��

"ASIC�#ALL�#ONTROL�3ERVICES�� 3WITCHING&UNCTION3ERVICES

4ELEPHONY3UPPLEMENTARY3ERVICES�� 3YSTEM�STATUS

!PPLICATION�AS�THE�CLIENT�� #AUSE�CODES�� $RIVER�SWITCH�AS�THE�CLIENT�� -AINTENANCE�SERVICES��

44ELEPHONY�3UPPLEMENTARY�#ONFIRMATION�%VENTS�� 4ELEPHONY�3UPPLEMENTARY�3ERVICES�� 4RUNK�GROUP�� 43!0)

#ALL�3TATES3EE�#ALL�3TATE

0ROGRAMMING�HANDLE3EE�#ALL�)DENTIFIER3EE�#ONNECTION�)DENTIFIER3EE�$EVICE�)DENTIFIER

0ROGRAMMING�OBJECT��


3EE�#ALL3EE�#ONNECTION3EE�$EVICE

4SERVER�%RRORS"AD�#ONNECTION�� "AD�$EVICE�2ECORD�� "AD�$RIVER�)$�� "AD�$RIVER�0ROTOCOL�� "AD�0ASSWORD�%NCRYPTION�� "AD�0ASSWORD�/R�,OGIN�� "AD�0$5�� "AD�0ROTOCOL�� "AD�0ROTOCOL�&ORMAT�� "AD�3$"�,EVEL�� "AD�3ERVER�)$�� "AD�3TREAM�4YPE�� "AD�4RANSPORT�4YPE�� $EAD�$RIVER�� $ECODE�&AILED�� $EVICE�.OT�/N�,IST�� $EVICE�.OT�3UPPORTED�� %#"�-AX�%XCEEDED�� %#"�/VERDUE�� %NCODE�&AILED�� %XCEPTION�,IST�� &REE�"UFFER�&AILED�� )NSUFFICIENT�0ERMISSION�� )NVALID�-ESSAGE�� -ESSAGE�(IGH�7ATER�-ARK�� .O�!WAY�0ERMISSION�� .O�!WAY�7ORKTOP�� .O�$EVICE�2ECORD�� .O�%#"3�� .O�(OME�0ERMISSION�� .O�-EMORY�� .O�2ESOURCE�4AG�� .O�3$"�� .O�3$"�#HECK�.EEDED�� .O�4HREAD�� .O�5SER�2ECORD�� .O�6ERSION�� /LD�4SLIB�� 0$5�6ERSION�-ISMATCH�� 2ECEIVE�&ROM�$RIVER��

2EGISTRATION�&AILED�� 3$"�#HECK�.EEDED�� 3END�4O�$RIVER�� 3PX�&AILED�� 3TREAM�&AILED�� 4RACE�� 5SERS�2ESTRICTED�(OME��

55NIX7ARE

VERSIONS�SUPPORTED�� 5NSOLICITED�%VENTS�� 5SER�� 77INDOWS�#LIENTS

(IGH�-EMORY�5SE�� %RROR��#ANNOT�OPEN�FILE�REFERENCED�ON�PAGE��

4ELEPHONY�3ERVICES�!0) ) ��

We’d like your opinion ...

Lucent Technologies welcomes your feedback on this document.Your comments can be of great value in helping us improve ourdocumentation.

Telephony ServicesApplication Programming Interface(TSAPI)Version 2Issue 2.3, May 1999

1. Please rate the effectiveness of this document in the following areas:Excellent Good Fair Poor

Ease of Finding Information ..... ❏ ❏ ❏ ❏Clarity ..... ❏ ❏ ❏ ❏

Completeness ..... ❏ ❏ ❏ ❏Accuracy ..... ❏ ❏ ❏ ❏

Organization ..... ❏ ❏ ❏ ❏Appearance ..... ❏ ❏ ❏ ❏

Examples ..... ❏ ❏ ❏ ❏Illustrations ..... ❏ ❏ ❏ ❏

Overall Satisfaction ..... ❏ ❏ ❏ ❏

2. Please check the ways you feel we could improve this document:❏ Improve the overview/introduction ❏ Make it more concise❏ Improve the table of contents ❏ Add more step-by-step procedures/tutorials❏ Improve the organization ❏ Add more troubleshooting information❏ Add more figures ❏ Make it less technical❏ Add more examples ❏ Add more/better quick reference aids❏ Add more details ❏ Improve the index

Please add details about your major concerns.______________________________________________________________________________________________

3. What did you like most about this document? ______________________ __________________________________________________________ __________________________________________________________

4. Feel free to write any comments below or on an attached sheet. ___________________________________________________________________________________________________________________________

If we may contact you concerning your comments, please complete the following:

Name: ______________________________ Telephone Number: (_____) __________

Company/Organization ________________________________ Date: ______________

Address_______________________________________________________________

You may FAX your response to (732) 957-4562. Thank you.

Documents

tsapi