OPAL
Version 3.10.4
|
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: 26939 $ 00030 * $Author: rjongbloed $ 00031 * $Date: 2012-02-07 01:17:49 -0600 (Tue, 07 Feb 2012) $ 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 26 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; 00975 OpalParamProtocol m_overrides; 00978 } OpalParamSetUpCall; 00979 00980 00984 typedef struct OpalStatusIncomingCall { 00985 const char * m_callToken; 00986 const char * m_localAddress; 00987 const char * m_remoteAddress; 00988 const char * m_remotePartyNumber; 00989 const char * m_remoteDisplayName; 00990 const char * m_calledAddress; 00991 const char * m_calledPartyNumber; 00992 OpalProductDescription m_product; 00993 const char * m_alertingType; 01005 const char * m_protocolCallId; 01007 const char * m_referredByAddress; 01008 const char * m_redirectingNumber; 01009 } OpalStatusIncomingCall; 01010 01011 01020 typedef struct OpalParamAnswerCall { 01021 const char * m_callToken; 01022 OpalParamProtocol m_overrides; 01025 } OpalParamAnswerCall; 01026 01031 typedef enum OpalMediaStates { 01032 OpalMediaStateNoChange, 01033 OpalMediaStateOpen, 01035 OpalMediaStateClose, 01037 OpalMediaStatePause, 01039 OpalMediaStateResume 01041 } OpalMediaStates; 01042 01043 01050 typedef struct OpalStatusMediaStream { 01051 const char * m_callToken; 01052 const char * m_identifier; 01055 const char * m_type; 01060 const char * m_format; 01064 OpalMediaStates m_state; 01067 int m_volume; 01071 } OpalStatusMediaStream; 01072 01073 01076 typedef struct OpalParamSetUserData { 01077 const char * m_callToken; 01078 void * m_userData; 01079 } OpalParamSetUserData; 01080 01081 01087 typedef struct OpalStatusUserInput { 01088 const char * m_callToken; 01089 const char * m_userInput; 01090 unsigned m_duration; 01095 } OpalStatusUserInput, OpalParamUserInput; 01096 01097 01101 typedef struct OpalStatusMessageWaiting { 01102 const char * m_party; 01103 const char * m_type; 01104 const char * m_extraInfo; 01107 } OpalStatusMessageWaiting; 01108 01109 01114 typedef enum OpalLineAppearanceStates { 01115 OpalLineTerminated, 01116 OpalLineTrying, 01117 OpalLineProceeding, 01118 OpalLineRinging, 01119 OpalLineConnected, 01120 OpalLineSubcribed, 01121 OpalLineUnsubcribed, 01123 OpalLineIdle = OpalLineTerminated // Kept for backward compatibility 01124 } OpalLineAppearanceStates; 01125 01126 01130 typedef struct OpalStatusLineAppearance { 01131 const char * m_line; 01132 OpalLineAppearanceStates m_state; 01133 int m_appearance; 01136 const char * m_callId; 01140 const char * m_partyA; 01141 const char * m_partyB; 01142 } OpalStatusLineAppearance; 01143 01144 01148 typedef enum OpalVideoRecordMixMode { 01149 OpalSideBySideLetterbox, 01153 OpalSideBySideScaled, 01157 OpalStackedPillarbox, 01161 OpalStackedScaled, 01165 } OpalVideoRecordMixMode; 01166 01167 01170 typedef struct OpalParamRecording { 01171 const char * m_callToken; 01172 const char * m_file; 01174 unsigned m_channels; 01177 const char * m_audioFormat; 01181 const char * m_videoFormat; 01185 unsigned m_videoWidth; 01186 unsigned m_videoHeight; 01187 unsigned m_videoRate; 01188 OpalVideoRecordMixMode m_videoMixing; 01189 } OpalParamRecording; 01190 01191 01195 typedef struct OpalStatusTransferCall { 01196 const char * m_callToken; 01197 const char * m_protocolCallId; 01199 const char * m_result; 01214 const char * m_info; 01218 } OpalStatusTransferCall; 01219 01220 01224 typedef struct OpalStatusIVR { 01225 const char * m_callToken; 01226 const char * m_variables; 01231 } OpalStatusIVR; 01232 01233 01237 typedef struct OpalStatusCallCleared { 01238 const char * m_callToken; 01239 const char * m_reason; 01244 } OpalStatusCallCleared; 01245 01246 01251 typedef enum OpalCallEndReason { 01252 OpalCallEndedByLocalUser, 01253 OpalCallEndedByNoAccept, 01254 OpalCallEndedByAnswerDenied, 01255 OpalCallEndedByRemoteUser, 01256 OpalCallEndedByRefusal, 01257 OpalCallEndedByNoAnswer, 01258 OpalCallEndedByCallerAbort, 01259 OpalCallEndedByTransportFail, 01260 OpalCallEndedByConnectFail, 01261 OpalCallEndedByGatekeeper, 01262 OpalCallEndedByNoUser, 01263 OpalCallEndedByNoBandwidth, 01264 OpalCallEndedByCapabilityExchange, 01265 OpalCallEndedByCallForwarded, 01266 OpalCallEndedBySecurityDenial, 01267 OpalCallEndedByLocalBusy, 01268 OpalCallEndedByLocalCongestion, 01269 OpalCallEndedByRemoteBusy, 01270 OpalCallEndedByRemoteCongestion, 01271 OpalCallEndedByUnreachable, 01272 OpalCallEndedByNoEndPoint, 01273 OpalCallEndedByHostOffline, 01274 OpalCallEndedByTemporaryFailure, 01275 OpalCallEndedByQ931Cause, 01276 OpalCallEndedByDurationLimit, 01277 OpalCallEndedByInvalidConferenceID, 01278 OpalCallEndedByNoDialTone, 01279 OpalCallEndedByNoRingBackTone, 01280 OpalCallEndedByOutOfService, 01281 OpalCallEndedByAcceptingCallWaiting, 01282 OpalCallEndedWithQ931Code = 0x100 01283 } OpalCallEndReason; 01284 01285 01288 typedef struct OpalParamCallCleared { 01289 const char * m_callToken; 01290 OpalCallEndReason m_reason; 01292 } OpalParamCallCleared; 01293 01294 01298 struct OpalMessage { 01299 OpalMessageType m_type; 01300 union { 01301 const char * m_commandError; 01302 OpalParamGeneral m_general; 01303 OpalParamProtocol m_protocol; 01304 OpalParamRegistration m_registrationInfo; 01305 OpalStatusRegistration m_registrationStatus; 01306 OpalParamSetUpCall m_callSetUp; 01307 const char * m_callToken; 01308 OpalStatusIncomingCall m_incomingCall; 01309 OpalParamAnswerCall m_answerCall; 01310 OpalStatusUserInput m_userInput; 01311 OpalStatusMessageWaiting m_messageWaiting; 01312 OpalStatusLineAppearance m_lineAppearance; 01313 OpalStatusCallCleared m_callCleared; 01314 OpalParamCallCleared m_clearCall; 01315 OpalStatusMediaStream m_mediaStream; 01316 OpalParamSetUserData m_setUserData; 01317 OpalParamRecording m_recording; 01318 OpalStatusTransferCall m_transferStatus; 01319 OpalStatusIVR m_ivrStatus; 01320 } m_param; 01321 }; 01322 01323 01324 #ifdef __cplusplus 01325 }; 01326 #endif 01327 01328 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS) 01329 01331 class OpalMessagePtr 01332 { 01333 public: 01334 OpalMessagePtr(OpalMessageType type = OpalIndCommandError); 01335 ~OpalMessagePtr(); 01336 01337 OpalMessageType GetType() const; 01338 void SetType(OpalMessageType type); 01339 01340 const char * GetCallToken() const; 01341 void SetCallToken(const char * token); 01342 01343 const char * GetCommandError() const; 01344 01345 OpalParamGeneral * GetGeneralParams() const; 01346 OpalParamProtocol * GetProtocolParams() const; 01347 OpalParamRegistration * GetRegistrationInfo() const; 01348 OpalStatusRegistration * GetRegistrationStatus() const; 01349 OpalParamSetUpCall * GetCallSetUp() const; 01350 OpalStatusIncomingCall * GetIncomingCall() const; 01351 OpalParamAnswerCall * GetAnswerCall() const; 01352 OpalStatusUserInput * GetUserInput() const; 01353 OpalStatusMessageWaiting * GetMessageWaiting() const; 01354 OpalStatusLineAppearance * GetLineAppearance() const; 01355 OpalStatusCallCleared * GetCallCleared() const; 01356 OpalParamCallCleared * GetClearCall() const; 01357 OpalStatusMediaStream * GetMediaStream() const; 01358 OpalParamSetUserData * GetSetUserData() const; 01359 OpalParamRecording * GetRecording() const; 01360 OpalStatusTransferCall * GetTransferStatus() const; 01361 01362 protected: 01363 OpalMessage * m_message; 01364 01365 private: 01366 OpalMessagePtr(const OpalMessagePtr &) { } 01367 void operator=(const OpalMessagePtr &) { } 01368 01369 friend class OpalContext; 01370 }; 01371 01372 01373 #ifdef GetMessage 01374 #undef GetMessage 01375 #endif 01376 #ifdef SendMessage 01377 #undef SendMessage 01378 #endif 01379 01380 01388 class OpalContext 01389 { 01390 public: 01392 OpalContext(); 01393 01395 virtual ~OpalContext(); 01396 01399 unsigned Initialise( 01400 const char * options, 01401 unsigned version = OPAL_C_API_VERSION 01402 ); 01403 01405 bool IsInitialised() const { return m_handle != NULL; } 01406 01408 void ShutDown(); 01409 01411 bool GetMessage( 01412 OpalMessagePtr & message, 01413 unsigned timeout = 0 01414 ); 01415 01417 bool SendMessage( 01418 const OpalMessagePtr & message, 01419 OpalMessagePtr & response 01420 ); 01421 01422 01424 bool SetUpCall( 01425 OpalMessagePtr & response, 01426 const char * partyB, 01427 const char * partyA = NULL, 01428 const char * alertingType = NULL 01429 ); 01430 01432 bool AnswerCall( 01433 const char * callToken 01434 ); 01435 01437 bool ClearCall( 01438 const char * callToken, 01439 OpalCallEndReason reason = OpalCallEndedByLocalUser 01440 ); 01441 01443 bool SendUserInput( 01444 const char * callToken, 01445 const char * userInput, 01446 unsigned duration = 0 01447 ); 01448 01449 protected: 01450 OpalHandle m_handle; 01451 }; 01452 01453 #endif 01454 01455 #endif // OPAL_OPAL_H 01456 01457