00001
00002
00003
00004
00005
00006
00007
00008
00009
00010
00011
00012
00013
00014
00015
00016
00017
00018
00019
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
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 27
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"
00301 #define OPAL_PREFIX_SIP "sip"
00302 #define OPAL_PREFIX_IAX2 "iax2"
00303 #define OPAL_PREFIX_PCSS "pc"
00304 #define OPAL_PREFIX_LOCAL "local"
00305 #define OPAL_PREFIX_POTS "pots"
00306 #define OPAL_PREFIX_PSTN "pstn"
00307 #define OPAL_PREFIX_IVR "ivr"
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
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 OpalMediaTimingSimulated
00532 } OpalMediaTiming;
00533
00534
00567 typedef struct OpalParamGeneral {
00568 const char * m_audioRecordDevice;
00569 const char * m_audioPlayerDevice;
00570 const char * m_videoInputDevice;
00571 const char * m_videoOutputDevice;
00572 const char * m_videoPreviewDevice;
00573 const char * m_mediaOrder;
00576 const char * m_mediaMask;
00579 const char * m_autoRxMedia;
00583 const char * m_autoTxMedia;
00587 const char * m_natRouter;
00589 const char * m_stunServer;
00591 unsigned m_tcpPortBase;
00593 unsigned m_tcpPortMax;
00595 unsigned m_udpPortBase;
00597 unsigned m_udpPortMax;
00599 unsigned m_rtpPortBase;
00601 unsigned m_rtpPortMax;
00603 unsigned m_rtpTypeOfService;
00605 unsigned m_rtpMaxPayloadSize;
00607 unsigned m_minAudioJitter;
00611 unsigned m_maxAudioJitter;
00615 OpalSilenceDetectMode m_silenceDetectMode;
00618 unsigned m_silenceThreshold;
00620 unsigned m_signalDeadband;
00622 unsigned m_silenceDeadband;
00624 unsigned m_silenceAdaptPeriod;
00627 OpalEchoCancelMode m_echoCancellation;
00629 unsigned m_audioBuffers;
00632 OpalMediaDataFunction m_mediaReadData;
00634 OpalMediaDataFunction m_mediaWriteData;
00636 OpalMediaDataType m_mediaDataHeader;
00639 OpalMessageAvailableFunction m_messageAvailable;
00643 const char * m_mediaOptions;
00652 unsigned m_audioBufferTime;
00655 unsigned m_manualAlerting;
00661 OpalMediaTiming m_mediaTiming;
00665 OpalMediaTiming m_videoSourceTiming;
00668 } OpalParamGeneral;
00669
00670
00673 typedef struct OpalProductDescription {
00674 const char * m_vendor;
00677 const char * m_name;
00680 const char * m_version;
00683 unsigned m_t35CountryCode;
00688 unsigned m_t35Extension;
00693 unsigned m_manufacturerCode;
00699 } OpalProductDescription;
00700
00701
00705 typedef enum OpalUserInputModes {
00706 OpalUserInputDefault,
00707 OpalUserInputAsQ931,
00708 OpalUserInputAsString,
00709 OpalUserInputAsTone,
00710 OpalUserInputAsRFC2833,
00711 OpalUserInputInBand,
00712 } OpalUserInputModes;
00713
00714
00731 typedef struct OpalParamProtocol {
00732 const char * m_prefix;
00735 const char * m_userName;
00738 const char * m_displayName;
00740 OpalProductDescription m_product;
00741 const char * m_interfaceAddresses;
00749 OpalUserInputModes m_userInputMode;
00752 const char * m_defaultOptions;
00754 } OpalParamProtocol;
00755
00756
00758 #define OPAL_MWI_EVENT_PACKAGE "message-summary"
00759
00761 #define OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma"
00762
00824 typedef struct OpalParamRegistration {
00825 const char * m_protocol;
00827 const char * m_identifier;
00833 const char * m_hostName;
00837 const char * m_authUserName;
00838 const char * m_password;
00839 const char * m_adminEntity;
00842 unsigned m_timeToLive;
00844 unsigned m_restoreTime;
00847 const char * m_eventPackage;
00855 } OpalParamRegistration;
00856
00857
00861 typedef enum OpalRegistrationStates {
00862 OpalRegisterSuccessful,
00863 OpalRegisterRemoved,
00867 OpalRegisterFailed,
00869 OpalRegisterRetrying,
00871 OpalRegisterRestored,
00872 } OpalRegistrationStates;
00873
00874
00878 typedef struct OpalStatusRegistration {
00879 const char * m_protocol;
00881 const char * m_serverName;
00884 const char * m_error;
00888 OpalRegistrationStates m_status;
00889 OpalProductDescription m_product;
00890 } OpalStatusRegistration;
00891
00892
00929 typedef struct OpalParamSetUpCall {
00930 const char * m_partyA;
00944 const char * m_partyB;
00956 const char * m_callToken;
00961 const char * m_alertingType;
00980 const char * m_protocolCallId;
00982 OpalParamProtocol m_overrides;
00985 } OpalParamSetUpCall;
00986
00987
00991 typedef struct OpalStatusIncomingCall {
00992 const char * m_callToken;
00993 const char * m_localAddress;
00994 const char * m_remoteAddress;
00995 const char * m_remotePartyNumber;
00996 const char * m_remoteDisplayName;
00997 const char * m_calledAddress;
00998 const char * m_calledPartyNumber;
00999 OpalProductDescription m_product;
01000 const char * m_alertingType;
01012 const char * m_protocolCallId;
01014 const char * m_referredByAddress;
01015 const char * m_redirectingNumber;
01016 } OpalStatusIncomingCall;
01017
01018
01027 typedef struct OpalParamAnswerCall {
01028 const char * m_callToken;
01029 OpalParamProtocol m_overrides;
01032 } OpalParamAnswerCall;
01033
01038 typedef enum OpalMediaStates {
01039 OpalMediaStateNoChange,
01040 OpalMediaStateOpen,
01042 OpalMediaStateClose,
01044 OpalMediaStatePause,
01046 OpalMediaStateResume
01048 } OpalMediaStates;
01049
01050
01057 typedef struct OpalStatusMediaStream {
01058 const char * m_callToken;
01059 const char * m_identifier;
01062 const char * m_type;
01067 const char * m_format;
01071 OpalMediaStates m_state;
01074 int m_volume;
01078 } OpalStatusMediaStream;
01079
01080
01083 typedef struct OpalParamSetUserData {
01084 const char * m_callToken;
01085 void * m_userData;
01086 } OpalParamSetUserData;
01087
01088
01094 typedef struct OpalStatusUserInput {
01095 const char * m_callToken;
01096 const char * m_userInput;
01097 unsigned m_duration;
01102 } OpalStatusUserInput, OpalParamUserInput;
01103
01104
01108 typedef struct OpalStatusMessageWaiting {
01109 const char * m_party;
01110 const char * m_type;
01111 const char * m_extraInfo;
01114 } OpalStatusMessageWaiting;
01115
01116
01121 typedef enum OpalLineAppearanceStates {
01122 OpalLineTerminated,
01123 OpalLineTrying,
01124 OpalLineProceeding,
01125 OpalLineRinging,
01126 OpalLineConnected,
01127 OpalLineSubcribed,
01128 OpalLineUnsubcribed,
01130 OpalLineIdle = OpalLineTerminated
01131 } OpalLineAppearanceStates;
01132
01133
01137 typedef struct OpalStatusLineAppearance {
01138 const char * m_line;
01139 OpalLineAppearanceStates m_state;
01140 int m_appearance;
01143 const char * m_callId;
01147 const char * m_partyA;
01148 const char * m_partyB;
01149 } OpalStatusLineAppearance;
01150
01151
01155 typedef enum OpalVideoRecordMixMode {
01156 OpalSideBySideLetterbox,
01160 OpalSideBySideScaled,
01164 OpalStackedPillarbox,
01168 OpalStackedScaled,
01172 } OpalVideoRecordMixMode;
01173
01174
01177 typedef struct OpalParamRecording {
01178 const char * m_callToken;
01179 const char * m_file;
01181 unsigned m_channels;
01184 const char * m_audioFormat;
01188 const char * m_videoFormat;
01192 unsigned m_videoWidth;
01193 unsigned m_videoHeight;
01194 unsigned m_videoRate;
01195 OpalVideoRecordMixMode m_videoMixing;
01196 } OpalParamRecording;
01197
01198
01202 typedef struct OpalStatusTransferCall {
01203 const char * m_callToken;
01204 const char * m_protocolCallId;
01206 const char * m_result;
01221 const char * m_info;
01225 } OpalStatusTransferCall;
01226
01227
01231 typedef struct OpalStatusIVR {
01232 const char * m_callToken;
01233 const char * m_variables;
01238 } OpalStatusIVR;
01239
01240
01244 typedef struct OpalStatusCallCleared {
01245 const char * m_callToken;
01246 const char * m_reason;
01251 } OpalStatusCallCleared;
01252
01253
01258 typedef enum OpalCallEndReason {
01259 OpalCallEndedByLocalUser,
01260 OpalCallEndedByNoAccept,
01261 OpalCallEndedByAnswerDenied,
01262 OpalCallEndedByRemoteUser,
01263 OpalCallEndedByRefusal,
01264 OpalCallEndedByNoAnswer,
01265 OpalCallEndedByCallerAbort,
01266 OpalCallEndedByTransportFail,
01267 OpalCallEndedByConnectFail,
01268 OpalCallEndedByGatekeeper,
01269 OpalCallEndedByNoUser,
01270 OpalCallEndedByNoBandwidth,
01271 OpalCallEndedByCapabilityExchange,
01272 OpalCallEndedByCallForwarded,
01273 OpalCallEndedBySecurityDenial,
01274 OpalCallEndedByLocalBusy,
01275 OpalCallEndedByLocalCongestion,
01276 OpalCallEndedByRemoteBusy,
01277 OpalCallEndedByRemoteCongestion,
01278 OpalCallEndedByUnreachable,
01279 OpalCallEndedByNoEndPoint,
01280 OpalCallEndedByHostOffline,
01281 OpalCallEndedByTemporaryFailure,
01282 OpalCallEndedByQ931Cause,
01283 OpalCallEndedByDurationLimit,
01284 OpalCallEndedByInvalidConferenceID,
01285 OpalCallEndedByNoDialTone,
01286 OpalCallEndedByNoRingBackTone,
01287 OpalCallEndedByOutOfService,
01288 OpalCallEndedByAcceptingCallWaiting,
01289 OpalCallEndedWithQ931Code = 0x100
01290 } OpalCallEndReason;
01291
01292
01295 typedef struct OpalParamCallCleared {
01296 const char * m_callToken;
01297 OpalCallEndReason m_reason;
01299 } OpalParamCallCleared;
01300
01301
01305 struct OpalMessage {
01306 OpalMessageType m_type;
01307 union {
01308 const char * m_commandError;
01309 OpalParamGeneral m_general;
01310 OpalParamProtocol m_protocol;
01311 OpalParamRegistration m_registrationInfo;
01312 OpalStatusRegistration m_registrationStatus;
01313 OpalParamSetUpCall m_callSetUp;
01314 const char * m_callToken;
01315 OpalStatusIncomingCall m_incomingCall;
01316 OpalParamAnswerCall m_answerCall;
01317 OpalStatusUserInput m_userInput;
01318 OpalStatusMessageWaiting m_messageWaiting;
01319 OpalStatusLineAppearance m_lineAppearance;
01320 OpalStatusCallCleared m_callCleared;
01321 OpalParamCallCleared m_clearCall;
01322 OpalStatusMediaStream m_mediaStream;
01323 OpalParamSetUserData m_setUserData;
01324 OpalParamRecording m_recording;
01325 OpalStatusTransferCall m_transferStatus;
01326 OpalStatusIVR m_ivrStatus;
01327 } m_param;
01328 };
01329
01330
01331 #ifdef __cplusplus
01332 };
01333 #endif
01334
01335 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS)
01336
01338 class OpalMessagePtr
01339 {
01340 public:
01341 OpalMessagePtr(OpalMessageType type = OpalIndCommandError);
01342 ~OpalMessagePtr();
01343
01344 OpalMessageType GetType() const;
01345 void SetType(OpalMessageType type);
01346
01347 const char * GetCallToken() const;
01348 void SetCallToken(const char * token);
01349
01350 const char * GetCommandError() const;
01351
01352 OpalParamGeneral * GetGeneralParams() const;
01353 OpalParamProtocol * GetProtocolParams() const;
01354 OpalParamRegistration * GetRegistrationInfo() const;
01355 OpalStatusRegistration * GetRegistrationStatus() const;
01356 OpalParamSetUpCall * GetCallSetUp() const;
01357 OpalStatusIncomingCall * GetIncomingCall() const;
01358 OpalParamAnswerCall * GetAnswerCall() const;
01359 OpalStatusUserInput * GetUserInput() const;
01360 OpalStatusMessageWaiting * GetMessageWaiting() const;
01361 OpalStatusLineAppearance * GetLineAppearance() const;
01362 OpalStatusCallCleared * GetCallCleared() const;
01363 OpalParamCallCleared * GetClearCall() const;
01364 OpalStatusMediaStream * GetMediaStream() const;
01365 OpalParamSetUserData * GetSetUserData() const;
01366 OpalParamRecording * GetRecording() const;
01367 OpalStatusTransferCall * GetTransferStatus() const;
01368
01369 protected:
01370 OpalMessage * m_message;
01371
01372 private:
01373 OpalMessagePtr(const OpalMessagePtr &) { }
01374 void operator=(const OpalMessagePtr &) { }
01375
01376 friend class OpalContext;
01377 };
01378
01379
01380 #ifdef GetMessage
01381 #undef GetMessage
01382 #endif
01383 #ifdef SendMessage
01384 #undef SendMessage
01385 #endif
01386
01387
01395 class OpalContext
01396 {
01397 public:
01399 OpalContext();
01400
01402 virtual ~OpalContext();
01403
01406 unsigned Initialise(
01407 const char * options,
01408 unsigned version = OPAL_C_API_VERSION
01409 );
01410
01412 bool IsInitialised() const { return m_handle != NULL; }
01413
01415 void ShutDown();
01416
01418 bool GetMessage(
01419 OpalMessagePtr & message,
01420 unsigned timeout = 0
01421 );
01422
01424 bool SendMessage(
01425 const OpalMessagePtr & message,
01426 OpalMessagePtr & response
01427 );
01428
01429
01431 bool SetUpCall(
01432 OpalMessagePtr & response,
01433 const char * partyB,
01434 const char * partyA = NULL,
01435 const char * alertingType = NULL
01436 );
01437
01439 bool AnswerCall(
01440 const char * callToken
01441 );
01442
01444 bool ClearCall(
01445 const char * callToken,
01446 OpalCallEndReason reason = OpalCallEndedByLocalUser
01447 );
01448
01450 bool SendUserInput(
01451 const char * callToken,
01452 const char * userInput,
01453 unsigned duration = 0
01454 );
01455
01456 protected:
01457 OpalHandle m_handle;
01458 };
01459
01460 #endif
01461
01462 #endif // OPAL_OPAL_H
01463
01464