OPAL Version 3.10.2
|
00001 /* 00002 * opal.h 00003 * 00004 * "C" language interface for OPAL 00005 * 00006 * Open Phone Abstraction Library (OPAL) 00007 * 00008 * Copyright (c) 2008 Vox Lucida 00009 * 00010 * The contents of this file are subject to the Mozilla Public License 00011 * Version 1.0 (the "License"); you may not use this file except in 00012 * compliance with the License. You may obtain a copy of the License at 00013 * http://www.mozilla.org/MPL/ 00014 * 00015 * Software distributed under the License is distributed on an "AS IS" 00016 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 00017 * the License for the specific language governing rights and limitations 00018 * under the License. 00019 * 00020 * The Original Code is Open Phone Abstraction Library. 00021 * 00022 * The Initial Developer of the Original Code is Vox Lucida (Robert Jongbloed) 00023 * 00024 * This code was initially written with the assisance of funding from 00025 * Stonevoice. http://www.stonevoice.com. 00026 * 00027 * Contributor(s): ______________________________________. 00028 * 00029 * $Revision: 26246 $ 00030 * $Author: rjongbloed $ 00031 * $Date: 2011-07-25 22:42:23 -0500 (Mon, 25 Jul 2011) $ 00032 */ 00033 00034 #ifndef OPAL_OPAL_H 00035 #define OPAL_OPAL_H 00036 00037 #include <stdlib.h> 00038 00039 00040 #ifdef __cplusplus 00041 extern "C" { 00042 #endif 00043 00070 #ifdef _WIN32 00071 #define OPAL_EXPORT __stdcall 00072 #else 00073 #define OPAL_EXPORT 00074 #endif 00075 00077 typedef struct OpalHandleStruct * OpalHandle; 00078 00079 00080 typedef struct OpalMessage OpalMessage; 00081 00083 #define OPAL_C_API_VERSION 25 00084 00085 00087 00138 OpalHandle OPAL_EXPORT OpalInitialise(unsigned * version, const char * options); 00139 00143 #define OPAL_INITIALISE_FUNCTION "OpalInitialise" 00144 00148 typedef OpalHandle (OPAL_EXPORT *OpalInitialiseFunction)(unsigned * version, const char * options); 00149 00150 00152 00161 void OPAL_EXPORT OpalShutDown(OpalHandle opal); 00162 00166 #define OPAL_SHUTDOWN_FUNCTION "OpalShutDown" 00167 00171 typedef void (OPAL_EXPORT *OpalShutDownFunction)(OpalHandle opal); 00172 00173 00175 00212 OpalMessage * OPAL_EXPORT OpalGetMessage(OpalHandle opal, unsigned timeout); 00213 00217 #define OPAL_GET_MESSAGE_FUNCTION "OpalGetMessage" 00218 00222 typedef OpalMessage * (OPAL_EXPORT *OpalGetMessageFunction)(OpalHandle opal, unsigned timeout); 00223 00224 00226 00267 OpalMessage * OPAL_EXPORT OpalSendMessage(OpalHandle opal, const OpalMessage * message); 00268 00272 typedef OpalMessage * (OPAL_EXPORT *OpalSendMessageFunction)(OpalHandle opal, const OpalMessage * message); 00273 00277 #define OPAL_SEND_MESSAGE_FUNCTION "OpalSendMessage" 00278 00279 00281 00285 void OPAL_EXPORT OpalFreeMessage(OpalMessage * message); 00286 00290 #define OPAL_FREE_MESSAGE_FUNCTION "OpalFreeMessage" 00291 00295 typedef void (OPAL_EXPORT *OpalFreeMessageFunction)(OpalMessage * message); 00296 00297 00299 00300 #define OPAL_PREFIX_H323 "h323" ///< H.323 Protocol supported string for OpalInitialise() 00301 #define OPAL_PREFIX_SIP "sip" ///< SIP Protocol supported string for OpalInitialise() 00302 #define OPAL_PREFIX_IAX2 "iax2" ///< IAX2 Protocol supported string for OpalInitialise() 00303 #define OPAL_PREFIX_PCSS "pc" ///< PC sound system supported string for OpalInitialise() 00304 #define OPAL_PREFIX_LOCAL "local" ///< Local endpoint supported string for OpalInitialise() 00305 #define OPAL_PREFIX_POTS "pots" ///< Plain Old Telephone System supported string for OpalInitialise() 00306 #define OPAL_PREFIX_PSTN "pstn" ///< Public Switched Network supported string for OpalInitialise() 00307 #define OPAL_PREFIX_IVR "ivr" ///< Interactive Voice Response supported string for OpalInitialise() 00308 00309 #define OPAL_PREFIX_ALL OPAL_PREFIX_H323 " " \ 00310 OPAL_PREFIX_SIP " " \ 00311 OPAL_PREFIX_IAX2 " " \ 00312 OPAL_PREFIX_PCSS " " \ 00313 OPAL_PREFIX_LOCAL " " \ 00314 OPAL_PREFIX_POTS " " \ 00315 OPAL_PREFIX_PSTN " " \ 00316 OPAL_PREFIX_IVR 00317 00318 00321 typedef enum OpalMessageType { 00322 OpalIndCommandError, 00325 OpalCmdSetGeneralParameters, 00327 OpalCmdSetProtocolParameters, 00330 OpalCmdRegistration, 00334 OpalIndRegistration, 00339 OpalCmdSetUpCall, 00343 OpalIndIncomingCall, 00346 OpalCmdAnswerCall, 00350 OpalCmdClearCall, 00355 OpalIndAlerting, 00359 OpalIndEstablished, 00363 OpalIndUserInput, 00366 OpalIndCallCleared, 00369 OpalCmdHoldCall, 00371 OpalCmdRetrieveCall, 00373 OpalCmdTransferCall, 00376 OpalCmdUserInput, 00378 OpalIndMessageWaiting, 00381 OpalIndMediaStream, 00384 OpalCmdMediaStream, 00386 OpalCmdSetUserData, 00387 OpalIndLineAppearance, 00390 OpalCmdStartRecording, 00392 OpalCmdStopRecording, 00394 OpalIndProceeding, 00402 OpalCmdAlerting, 00404 OpalIndOnHold, 00406 OpalIndOffHold, 00408 OpalIndTransferCall, 00411 OpalIndCompletedIVR, 00415 // Always add new messages to ethe end to maintain backward compatibility 00416 OpalMessageTypeCount 00417 } OpalMessageType; 00418 00419 00423 typedef enum OpalSilenceDetectMode { 00424 OpalSilenceDetectNoChange, 00425 OpalSilenceDetectDisabled, 00426 OpalSilenceDetectFixed, 00427 OpalSilenceDetectAdaptive 00428 } OpalSilenceDetectMode; 00429 00430 00434 typedef enum OpalEchoCancelMode { 00435 OpalEchoCancelNoChange, 00436 OpalEchoCancelDisabled, 00437 OpalEchoCancelEnabled 00438 } OpalEchoCancelMode; 00439 00440 00455 typedef int (*OpalMediaDataFunction)( 00456 const char * token, 00458 const char * stream, 00462 const char * format, 00463 void * userData, 00464 void * data, 00465 int size 00466 ); 00467 00468 00485 typedef int (*OpalMessageAvailableFunction)( 00486 const OpalMessage * message 00487 ); 00488 00489 00497 typedef enum OpalMediaDataType { 00498 OpalMediaDataNoChange, 00499 OpalMediaDataPayloadOnly, 00501 OpalMediaDataWithHeader 00503 } OpalMediaDataType; 00504 00505 00523 typedef enum OpalMediaTiming { 00524 OpalMediaTimingNoChange, 00525 OpalMediaTimingSynchronous, 00527 OpalMediaTimingAsynchronous 00529 } OpalMediaTiming; 00530 00531 00564 typedef struct OpalParamGeneral { 00565 const char * m_audioRecordDevice; 00566 const char * m_audioPlayerDevice; 00567 const char * m_videoInputDevice; 00568 const char * m_videoOutputDevice; 00569 const char * m_videoPreviewDevice; 00570 const char * m_mediaOrder; 00573 const char * m_mediaMask; 00576 const char * m_autoRxMedia; 00580 const char * m_autoTxMedia; 00584 const char * m_natRouter; 00586 const char * m_stunServer; 00588 unsigned m_tcpPortBase; 00590 unsigned m_tcpPortMax; 00592 unsigned m_udpPortBase; 00594 unsigned m_udpPortMax; 00596 unsigned m_rtpPortBase; 00598 unsigned m_rtpPortMax; 00600 unsigned m_rtpTypeOfService; 00602 unsigned m_rtpMaxPayloadSize; 00604 unsigned m_minAudioJitter; 00608 unsigned m_maxAudioJitter; 00612 OpalSilenceDetectMode m_silenceDetectMode; 00615 unsigned m_silenceThreshold; 00617 unsigned m_signalDeadband; 00619 unsigned m_silenceDeadband; 00621 unsigned m_silenceAdaptPeriod; 00624 OpalEchoCancelMode m_echoCancellation; 00626 unsigned m_audioBuffers; 00629 OpalMediaDataFunction m_mediaReadData; 00631 OpalMediaDataFunction m_mediaWriteData; 00633 OpalMediaDataType m_mediaDataHeader; 00636 OpalMessageAvailableFunction m_messageAvailable; 00640 const char * m_mediaOptions; 00649 unsigned m_audioBufferTime; 00652 unsigned m_manualAlerting; 00658 OpalMediaTiming m_mediaTiming; 00661 } OpalParamGeneral; 00662 00663 00666 typedef struct OpalProductDescription { 00667 const char * m_vendor; 00670 const char * m_name; 00673 const char * m_version; 00676 unsigned m_t35CountryCode; 00681 unsigned m_t35Extension; 00686 unsigned m_manufacturerCode; 00692 } OpalProductDescription; 00693 00694 00698 typedef enum OpalUserInputModes { 00699 OpalUserInputDefault, 00700 OpalUserInputAsQ931, 00701 OpalUserInputAsString, 00702 OpalUserInputAsTone, 00703 OpalUserInputAsRFC2833, 00704 OpalUserInputInBand, 00705 } OpalUserInputModes; 00706 00707 00724 typedef struct OpalParamProtocol { 00725 const char * m_prefix; 00728 const char * m_userName; 00731 const char * m_displayName; 00733 OpalProductDescription m_product; 00734 const char * m_interfaceAddresses; 00742 OpalUserInputModes m_userInputMode; 00745 const char * m_defaultOptions; 00747 } OpalParamProtocol; 00748 00749 00751 #define OPAL_MWI_EVENT_PACKAGE "message-summary" 00752 00754 #define OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma" 00755 00817 typedef struct OpalParamRegistration { 00818 const char * m_protocol; 00820 const char * m_identifier; 00826 const char * m_hostName; 00830 const char * m_authUserName; 00831 const char * m_password; 00832 const char * m_adminEntity; 00835 unsigned m_timeToLive; 00837 unsigned m_restoreTime; 00840 const char * m_eventPackage; 00848 } OpalParamRegistration; 00849 00850 00854 typedef enum OpalRegistrationStates { 00855 OpalRegisterSuccessful, 00856 OpalRegisterRemoved, 00860 OpalRegisterFailed, 00862 OpalRegisterRetrying, 00864 OpalRegisterRestored, 00865 } OpalRegistrationStates; 00866 00867 00871 typedef struct OpalStatusRegistration { 00872 const char * m_protocol; 00874 const char * m_serverName; 00877 const char * m_error; 00881 OpalRegistrationStates m_status; 00882 OpalProductDescription m_product; 00883 } OpalStatusRegistration; 00884 00885 00922 typedef struct OpalParamSetUpCall { 00923 const char * m_partyA; 00937 const char * m_partyB; 00949 const char * m_callToken; 00954 const char * m_alertingType; 00973 const char * m_protocolCallId; 00976 } OpalParamSetUpCall; 00977 00978 00982 typedef struct OpalStatusIncomingCall { 00983 const char * m_callToken; 00984 const char * m_localAddress; 00985 const char * m_remoteAddress; 00986 const char * m_remotePartyNumber; 00987 const char * m_remoteDisplayName; 00988 const char * m_calledAddress; 00989 const char * m_calledPartyNumber; 00990 OpalProductDescription m_product; 00991 const char * m_alertingType; 01003 const char * m_protocolCallId; 01005 const char * m_referredByAddress; 01006 const char * m_redirectingNumber; 01007 } OpalStatusIncomingCall; 01008 01009 01014 typedef enum OpalMediaStates { 01015 OpalMediaStateNoChange, 01016 OpalMediaStateOpen, 01018 OpalMediaStateClose, 01020 OpalMediaStatePause, 01022 OpalMediaStateResume 01024 } OpalMediaStates; 01025 01026 01033 typedef struct OpalStatusMediaStream { 01034 const char * m_callToken; 01035 const char * m_identifier; 01038 const char * m_type; 01043 const char * m_format; 01047 OpalMediaStates m_state; 01050 int m_volume; 01054 } OpalStatusMediaStream; 01055 01056 01059 typedef struct OpalParamSetUserData { 01060 const char * m_callToken; 01061 void * m_userData; 01062 } OpalParamSetUserData; 01063 01064 01070 typedef struct OpalStatusUserInput { 01071 const char * m_callToken; 01072 const char * m_userInput; 01073 unsigned m_duration; 01078 } OpalStatusUserInput, OpalParamUserInput; 01079 01080 01084 typedef struct OpalStatusMessageWaiting { 01085 const char * m_party; 01086 const char * m_type; 01087 const char * m_extraInfo; 01090 } OpalStatusMessageWaiting; 01091 01092 01097 typedef enum OpalLineAppearanceStates { 01098 OpalLineTerminated, 01099 OpalLineTrying, 01100 OpalLineProceeding, 01101 OpalLineRinging, 01102 OpalLineConnected, 01103 OpalLineSubcribed, 01104 OpalLineUnsubcribed, 01106 OpalLineIdle = OpalLineTerminated // Kept for backward compatibility 01107 } OpalLineAppearanceStates; 01108 01109 01113 typedef struct OpalStatusLineAppearance { 01114 const char * m_line; 01115 OpalLineAppearanceStates m_state; 01116 int m_appearance; 01119 const char * m_callId; 01123 const char * m_partyA; 01124 const char * m_partyB; 01125 } OpalStatusLineAppearance; 01126 01127 01131 typedef enum OpalVideoRecordMixMode { 01132 OpalSideBySideLetterbox, 01136 OpalSideBySideScaled, 01140 OpalStackedPillarbox, 01144 OpalStackedScaled, 01148 } OpalVideoRecordMixMode; 01149 01150 01153 typedef struct OpalParamRecording { 01154 const char * m_callToken; 01155 const char * m_file; 01157 unsigned m_channels; 01160 const char * m_audioFormat; 01164 const char * m_videoFormat; 01168 unsigned m_videoWidth; 01169 unsigned m_videoHeight; 01170 unsigned m_videoRate; 01171 OpalVideoRecordMixMode m_videoMixing; 01172 } OpalParamRecording; 01173 01174 01178 typedef struct OpalStatusTransferCall { 01179 const char * m_callToken; 01180 const char * m_protocolCallId; 01182 const char * m_result; 01197 const char * m_info; 01201 } OpalStatusTransferCall; 01202 01203 01207 typedef struct OpalStatusIVR { 01208 const char * m_callToken; 01209 const char * m_variables; 01214 } OpalStatusIVR; 01215 01216 01220 typedef struct OpalStatusCallCleared { 01221 const char * m_callToken; 01222 const char * m_reason; 01227 } OpalStatusCallCleared; 01228 01229 01234 typedef enum OpalCallEndReason { 01235 OpalCallEndedByLocalUser, 01236 OpalCallEndedByNoAccept, 01237 OpalCallEndedByAnswerDenied, 01238 OpalCallEndedByRemoteUser, 01239 OpalCallEndedByRefusal, 01240 OpalCallEndedByNoAnswer, 01241 OpalCallEndedByCallerAbort, 01242 OpalCallEndedByTransportFail, 01243 OpalCallEndedByConnectFail, 01244 OpalCallEndedByGatekeeper, 01245 OpalCallEndedByNoUser, 01246 OpalCallEndedByNoBandwidth, 01247 OpalCallEndedByCapabilityExchange, 01248 OpalCallEndedByCallForwarded, 01249 OpalCallEndedBySecurityDenial, 01250 OpalCallEndedByLocalBusy, 01251 OpalCallEndedByLocalCongestion, 01252 OpalCallEndedByRemoteBusy, 01253 OpalCallEndedByRemoteCongestion, 01254 OpalCallEndedByUnreachable, 01255 OpalCallEndedByNoEndPoint, 01256 OpalCallEndedByHostOffline, 01257 OpalCallEndedByTemporaryFailure, 01258 OpalCallEndedByQ931Cause, 01259 OpalCallEndedByDurationLimit, 01260 OpalCallEndedByInvalidConferenceID, 01261 OpalCallEndedByNoDialTone, 01262 OpalCallEndedByNoRingBackTone, 01263 OpalCallEndedByOutOfService, 01264 OpalCallEndedByAcceptingCallWaiting, 01265 OpalCallEndedWithQ931Code = 0x100 01266 } OpalCallEndReason; 01267 01268 01271 typedef struct OpalParamCallCleared { 01272 const char * m_callToken; 01273 OpalCallEndReason m_reason; 01275 } OpalParamCallCleared; 01276 01277 01281 struct OpalMessage { 01282 OpalMessageType m_type; 01283 union { 01284 const char * m_commandError; 01285 OpalParamGeneral m_general; 01286 OpalParamProtocol m_protocol; 01287 OpalParamRegistration m_registrationInfo; 01288 OpalStatusRegistration m_registrationStatus; 01289 OpalParamSetUpCall m_callSetUp; 01290 const char * m_callToken; 01291 OpalStatusIncomingCall m_incomingCall; 01292 OpalStatusUserInput m_userInput; 01293 OpalStatusMessageWaiting m_messageWaiting; 01294 OpalStatusLineAppearance m_lineAppearance; 01295 OpalStatusCallCleared m_callCleared; 01296 OpalParamCallCleared m_clearCall; 01297 OpalStatusMediaStream m_mediaStream; 01298 OpalParamSetUserData m_setUserData; 01299 OpalParamRecording m_recording; 01300 OpalStatusTransferCall m_transferStatus; 01301 OpalStatusIVR m_ivrStatus; 01302 } m_param; 01303 }; 01304 01305 01306 #ifdef __cplusplus 01307 }; 01308 #endif 01309 01310 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS) 01311 01313 class OpalMessagePtr 01314 { 01315 public: 01316 OpalMessagePtr(OpalMessageType type = OpalIndCommandError); 01317 ~OpalMessagePtr(); 01318 01319 OpalMessageType GetType() const; 01320 void SetType(OpalMessageType type); 01321 01322 const char * GetCallToken() const; 01323 void SetCallToken(const char * token); 01324 01325 const char * GetCommandError() const; 01326 01327 OpalParamGeneral * GetGeneralParams() const; 01328 OpalParamProtocol * GetProtocolParams() const; 01329 OpalParamRegistration * GetRegistrationInfo() const; 01330 OpalStatusRegistration * GetRegistrationStatus() const; 01331 OpalParamSetUpCall * GetCallSetUp() const; 01332 OpalStatusIncomingCall * GetIncomingCall() const; 01333 OpalStatusUserInput * GetUserInput() const; 01334 OpalStatusMessageWaiting * GetMessageWaiting() const; 01335 OpalStatusLineAppearance * GetLineAppearance() const; 01336 OpalStatusCallCleared * GetCallCleared() const; 01337 OpalParamCallCleared * GetClearCall() const; 01338 OpalStatusMediaStream * GetMediaStream() const; 01339 OpalParamSetUserData * GetSetUserData() const; 01340 OpalParamRecording * GetRecording() const; 01341 OpalStatusTransferCall * GetTransferStatus() const; 01342 01343 protected: 01344 OpalMessage * m_message; 01345 01346 private: 01347 OpalMessagePtr(const OpalMessagePtr &) { } 01348 void operator=(const OpalMessagePtr &) { } 01349 01350 friend class OpalContext; 01351 }; 01352 01353 01354 #ifdef GetMessage 01355 #undef GetMessage 01356 #endif 01357 #ifdef SendMessage 01358 #undef SendMessage 01359 #endif 01360 01361 01369 class OpalContext 01370 { 01371 public: 01373 OpalContext(); 01374 01376 virtual ~OpalContext(); 01377 01380 unsigned Initialise( 01381 const char * options, 01382 unsigned version = OPAL_C_API_VERSION 01383 ); 01384 01386 bool IsInitialised() const { return m_handle != NULL; } 01387 01389 void ShutDown(); 01390 01392 bool GetMessage( 01393 OpalMessagePtr & message, 01394 unsigned timeout = 0 01395 ); 01396 01398 bool SendMessage( 01399 const OpalMessagePtr & message, 01400 OpalMessagePtr & response 01401 ); 01402 01403 01405 bool SetUpCall( 01406 OpalMessagePtr & response, 01407 const char * partyB, 01408 const char * partyA = NULL, 01409 const char * alertingType = NULL 01410 ); 01411 01413 bool AnswerCall( 01414 const char * callToken 01415 ); 01416 01418 bool ClearCall( 01419 const char * callToken, 01420 OpalCallEndReason reason = OpalCallEndedByLocalUser 01421 ); 01422 01424 bool SendUserInput( 01425 const char * callToken, 01426 const char * userInput, 01427 unsigned duration = 0 01428 ); 01429 01430 protected: 01431 OpalHandle m_handle; 01432 }; 01433 01434 #endif 01435 01436 #endif // OPAL_OPAL_H 01437 01438