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 29
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_FAX "fax"
00308 #define OPAL_PREFIX_T38 "t38"
00309 #define OPAL_PREFIX_IVR "ivr"
00310 #define OPAL_PREFIX_IM "im"
00311
00312 #define OPAL_PREFIX_ALL OPAL_PREFIX_H323 " " \
00313 OPAL_PREFIX_SIP " " \
00314 OPAL_PREFIX_IAX2 " " \
00315 OPAL_PREFIX_PCSS " " \
00316 OPAL_PREFIX_LOCAL " " \
00317 OPAL_PREFIX_POTS " " \
00318 OPAL_PREFIX_PSTN " " \
00319 OPAL_PREFIX_FAX " " \
00320 OPAL_PREFIX_T38 " " \
00321 OPAL_PREFIX_IVR " " \
00322 OPAL_PREFIX_IM
00323
00324
00327 typedef enum OpalMessageType {
00328 OpalIndCommandError,
00331 OpalCmdSetGeneralParameters,
00333 OpalCmdSetProtocolParameters,
00336 OpalCmdRegistration,
00340 OpalIndRegistration,
00345 OpalCmdSetUpCall,
00349 OpalIndIncomingCall,
00352 OpalCmdAnswerCall,
00356 OpalCmdClearCall,
00361 OpalIndAlerting,
00365 OpalIndEstablished,
00369 OpalIndUserInput,
00372 OpalIndCallCleared,
00375 OpalCmdHoldCall,
00377 OpalCmdRetrieveCall,
00379 OpalCmdTransferCall,
00382 OpalCmdUserInput,
00384 OpalIndMessageWaiting,
00387 OpalIndMediaStream,
00390 OpalCmdMediaStream,
00392 OpalCmdSetUserData,
00393 OpalIndLineAppearance,
00396 OpalCmdStartRecording,
00398 OpalCmdStopRecording,
00400 OpalIndProceeding,
00408 OpalCmdAlerting,
00410 OpalIndOnHold,
00412 OpalIndOffHold,
00414 OpalIndTransferCall,
00417 OpalIndCompletedIVR,
00420 OpalCmdAuthorisePresence,
00423 OpalCmdSubscribePresence,
00425 OpalCmdSetLocalPresence,
00427 OpalIndPresenceChange,
00430 OpalCmdSendIM,
00432 OpalIndReceiveIM,
00435 OpalIndSentIM,
00439
00440 OpalMessageTypeCount
00441 } OpalMessageType;
00442
00443
00447 typedef enum OpalSilenceDetectMode {
00448 OpalSilenceDetectNoChange,
00449 OpalSilenceDetectDisabled,
00450 OpalSilenceDetectFixed,
00451 OpalSilenceDetectAdaptive
00452 } OpalSilenceDetectMode;
00453
00454
00458 typedef enum OpalEchoCancelMode {
00459 OpalEchoCancelNoChange,
00460 OpalEchoCancelDisabled,
00461 OpalEchoCancelEnabled
00462 } OpalEchoCancelMode;
00463
00464
00479 typedef int (*OpalMediaDataFunction)(
00480 const char * token,
00482 const char * stream,
00486 const char * format,
00487 void * userData,
00488 void * data,
00489 int size
00490 );
00491
00492
00509 typedef int (*OpalMessageAvailableFunction)(
00510 const OpalMessage * message
00511 );
00512
00513
00521 typedef enum OpalMediaDataType {
00522 OpalMediaDataNoChange,
00523 OpalMediaDataPayloadOnly,
00525 OpalMediaDataWithHeader
00527 } OpalMediaDataType;
00528
00529
00547 typedef enum OpalMediaTiming {
00548 OpalMediaTimingNoChange,
00549 OpalMediaTimingSynchronous,
00551 OpalMediaTimingAsynchronous,
00553 OpalMediaTimingSimulated
00556 } OpalMediaTiming;
00557
00558
00591 typedef struct OpalParamGeneral {
00592 const char * m_audioRecordDevice;
00593 const char * m_audioPlayerDevice;
00594 const char * m_videoInputDevice;
00595 const char * m_videoOutputDevice;
00596 const char * m_videoPreviewDevice;
00597 const char * m_mediaOrder;
00600 const char * m_mediaMask;
00603 const char * m_autoRxMedia;
00607 const char * m_autoTxMedia;
00611 const char * m_natMethod;
00615 const char * m_natServer;
00617 unsigned m_tcpPortBase;
00619 unsigned m_tcpPortMax;
00621 unsigned m_udpPortBase;
00623 unsigned m_udpPortMax;
00625 unsigned m_rtpPortBase;
00627 unsigned m_rtpPortMax;
00629 unsigned m_rtpTypeOfService;
00631 unsigned m_rtpMaxPayloadSize;
00633 unsigned m_minAudioJitter;
00637 unsigned m_maxAudioJitter;
00641 OpalSilenceDetectMode m_silenceDetectMode;
00644 unsigned m_silenceThreshold;
00646 unsigned m_signalDeadband;
00648 unsigned m_silenceDeadband;
00650 unsigned m_silenceAdaptPeriod;
00653 OpalEchoCancelMode m_echoCancellation;
00655 unsigned m_audioBuffers;
00658 OpalMediaDataFunction m_mediaReadData;
00660 OpalMediaDataFunction m_mediaWriteData;
00662 OpalMediaDataType m_mediaDataHeader;
00665 OpalMessageAvailableFunction m_messageAvailable;
00669 const char * m_mediaOptions;
00678 unsigned m_audioBufferTime;
00681 unsigned m_manualAlerting;
00687 OpalMediaTiming m_mediaTiming;
00691 OpalMediaTiming m_videoSourceTiming;
00694 } OpalParamGeneral;
00695
00696
00699 typedef struct OpalProductDescription {
00700 const char * m_vendor;
00703 const char * m_name;
00706 const char * m_version;
00709 unsigned m_t35CountryCode;
00714 unsigned m_t35Extension;
00719 unsigned m_manufacturerCode;
00725 } OpalProductDescription;
00726
00727
00731 typedef enum OpalUserInputModes {
00732 OpalUserInputDefault,
00733 OpalUserInputAsQ931,
00734 OpalUserInputAsString,
00735 OpalUserInputAsTone,
00736 OpalUserInputAsRFC2833,
00737 OpalUserInputInBand,
00738 } OpalUserInputModes;
00739
00740
00757 typedef struct OpalParamProtocol {
00758 const char * m_prefix;
00761 const char * m_userName;
00764 const char * m_displayName;
00766 OpalProductDescription m_product;
00767 const char * m_interfaceAddresses;
00775 OpalUserInputModes m_userInputMode;
00778 const char * m_defaultOptions;
00780 } OpalParamProtocol;
00781
00782
00784 #define OPAL_MWI_EVENT_PACKAGE "message-summary"
00785
00787 #define OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma"
00788
00861 typedef struct OpalParamRegistration {
00862 const char * m_protocol;
00864 const char * m_identifier;
00870 const char * m_hostName;
00874 const char * m_authUserName;
00875 const char * m_password;
00876 const char * m_adminEntity;
00879 unsigned m_timeToLive;
00881 unsigned m_restoreTime;
00884 const char * m_eventPackage;
00892 const char * m_attributes;
00896 } OpalParamRegistration;
00897
00898
00902 typedef enum OpalRegistrationStates {
00903 OpalRegisterSuccessful,
00904 OpalRegisterRemoved,
00908 OpalRegisterFailed,
00910 OpalRegisterRetrying,
00912 OpalRegisterRestored,
00913 } OpalRegistrationStates;
00914
00915
00919 typedef struct OpalStatusRegistration {
00920 const char * m_protocol;
00922 const char * m_serverName;
00925 const char * m_error;
00929 OpalRegistrationStates m_status;
00930 OpalProductDescription m_product;
00931 } OpalStatusRegistration;
00932
00933
00970 typedef struct OpalParamSetUpCall {
00971 const char * m_partyA;
00985 const char * m_partyB;
00997 const char * m_callToken;
01002 const char * m_alertingType;
01021 const char * m_protocolCallId;
01023 OpalParamProtocol m_overrides;
01026 } OpalParamSetUpCall;
01027
01028
01032 typedef struct OpalStatusIncomingCall {
01033 const char * m_callToken;
01034 const char * m_localAddress;
01035 const char * m_remoteAddress;
01036 const char * m_remotePartyNumber;
01037 const char * m_remoteDisplayName;
01038 const char * m_calledAddress;
01039 const char * m_calledPartyNumber;
01040 OpalProductDescription m_product;
01041 const char * m_alertingType;
01053 const char * m_protocolCallId;
01055 const char * m_referredByAddress;
01056 const char * m_redirectingNumber;
01057 } OpalStatusIncomingCall;
01058
01059
01068 typedef struct OpalParamAnswerCall {
01069 const char * m_callToken;
01070 OpalParamProtocol m_overrides;
01073 unsigned m_withMedia;
01075 } OpalParamAnswerCall;
01076
01081 typedef enum OpalMediaStates {
01082 OpalMediaStateNoChange,
01083 OpalMediaStateOpen,
01085 OpalMediaStateClose,
01087 OpalMediaStatePause,
01089 OpalMediaStateResume
01091 } OpalMediaStates;
01092
01093
01100 typedef struct OpalStatusMediaStream {
01101 const char * m_callToken;
01102 const char * m_identifier;
01105 const char * m_type;
01110 const char * m_format;
01114 OpalMediaStates m_state;
01117 int m_volume;
01121 } OpalStatusMediaStream;
01122
01123
01126 typedef struct OpalParamSetUserData {
01127 const char * m_callToken;
01128 void * m_userData;
01129 } OpalParamSetUserData;
01130
01131
01137 typedef struct OpalStatusUserInput {
01138 const char * m_callToken;
01139 const char * m_userInput;
01140 unsigned m_duration;
01145 } OpalStatusUserInput, OpalParamUserInput;
01146
01147
01151 typedef struct OpalStatusMessageWaiting {
01152 const char * m_party;
01153 const char * m_type;
01154 const char * m_extraInfo;
01157 } OpalStatusMessageWaiting;
01158
01159
01164 typedef enum OpalLineAppearanceStates {
01165 OpalLineTerminated,
01166 OpalLineTrying,
01167 OpalLineProceeding,
01168 OpalLineRinging,
01169 OpalLineConnected,
01170 OpalLineSubcribed,
01171 OpalLineUnsubcribed,
01173 OpalLineIdle = OpalLineTerminated
01174 } OpalLineAppearanceStates;
01175
01176
01180 typedef struct OpalStatusLineAppearance {
01181 const char * m_line;
01182 OpalLineAppearanceStates m_state;
01183 int m_appearance;
01186 const char * m_callId;
01190 const char * m_partyA;
01191 const char * m_partyB;
01192 } OpalStatusLineAppearance;
01193
01194
01198 typedef enum OpalPresenceStates {
01199 OpalPresenceAuthRequest = -100,
01200 OpalUnknownPresentity = -4,
01201 OpalPresenceError,
01202 OpalPresenceForbidden,
01203 OpalPresenceNone,
01204 OpalPresenceUnchanged,
01205 OpalPresenceAvailable,
01206 OpalPresenceUnavailable
01207 } OpalPresenceStates;
01208
01209
01238 typedef struct OpalPresenceStatus {
01239 const char * m_entity;
01242 const char * m_target;
01244 const char * m_service;
01246 const char * m_contact;
01247 const char * m_capabilities;
01249 OpalPresenceStates m_state;
01250 const char * m_activities;
01254 const char * m_note;
01258 const char * m_infoType;
01259 const char * m_infoData;
01260 } OpalPresenceStatus;
01261
01262
01271 typedef struct OpalInstantMessage {
01272 const char * m_from;
01273 const char * m_to;
01274 const char * m_host;
01276 const char * m_conversationId;
01280 const char * m_textBody;
01282 unsigned m_bodyCount;
01283 const char ** m_mimeType;
01284 const char ** m_bodies;
01285 unsigned m_messageId;
01289 } OpalInstantMessage;
01290
01291
01295 typedef enum OpalVideoRecordMixMode {
01296 OpalSideBySideLetterbox,
01300 OpalSideBySideScaled,
01304 OpalStackedPillarbox,
01308 OpalStackedScaled,
01312 } OpalVideoRecordMixMode;
01313
01314
01317 typedef struct OpalParamRecording {
01318 const char * m_callToken;
01319 const char * m_file;
01321 unsigned m_channels;
01324 const char * m_audioFormat;
01328 const char * m_videoFormat;
01332 unsigned m_videoWidth;
01333 unsigned m_videoHeight;
01334 unsigned m_videoRate;
01335 OpalVideoRecordMixMode m_videoMixing;
01336 } OpalParamRecording;
01337
01338
01342 typedef struct OpalStatusTransferCall {
01343 const char * m_callToken;
01344 const char * m_protocolCallId;
01346 const char * m_result;
01361 const char * m_info;
01365 } OpalStatusTransferCall;
01366
01367
01371 typedef struct OpalStatusIVR {
01372 const char * m_callToken;
01373 const char * m_variables;
01378 } OpalStatusIVR;
01379
01380
01384 typedef struct OpalStatusCallCleared {
01385 const char * m_callToken;
01386 const char * m_reason;
01391 } OpalStatusCallCleared;
01392
01393
01398 typedef enum OpalCallEndReason {
01399 OpalCallEndedByLocalUser,
01400 OpalCallEndedByNoAccept,
01401 OpalCallEndedByAnswerDenied,
01402 OpalCallEndedByRemoteUser,
01403 OpalCallEndedByRefusal,
01404 OpalCallEndedByNoAnswer,
01405 OpalCallEndedByCallerAbort,
01406 OpalCallEndedByTransportFail,
01407 OpalCallEndedByConnectFail,
01408 OpalCallEndedByGatekeeper,
01409 OpalCallEndedByNoUser,
01410 OpalCallEndedByNoBandwidth,
01411 OpalCallEndedByCapabilityExchange,
01412 OpalCallEndedByCallForwarded,
01413 OpalCallEndedBySecurityDenial,
01414 OpalCallEndedByLocalBusy,
01415 OpalCallEndedByLocalCongestion,
01416 OpalCallEndedByRemoteBusy,
01417 OpalCallEndedByRemoteCongestion,
01418 OpalCallEndedByUnreachable,
01419 OpalCallEndedByNoEndPoint,
01420 OpalCallEndedByHostOffline,
01421 OpalCallEndedByTemporaryFailure,
01422 OpalCallEndedByQ931Cause,
01423 OpalCallEndedByDurationLimit,
01424 OpalCallEndedByInvalidConferenceID,
01425 OpalCallEndedByNoDialTone,
01426 OpalCallEndedByNoRingBackTone,
01427 OpalCallEndedByOutOfService,
01428 OpalCallEndedByAcceptingCallWaiting,
01429 OpalCallEndedWithQ931Code = 0x100
01430 } OpalCallEndReason;
01431
01432
01435 typedef struct OpalParamCallCleared {
01436 const char * m_callToken;
01437 OpalCallEndReason m_reason;
01439 } OpalParamCallCleared;
01440
01441
01445 struct OpalMessage {
01446 OpalMessageType m_type;
01447 union {
01448 const char * m_commandError;
01449 OpalParamGeneral m_general;
01450 OpalParamProtocol m_protocol;
01451 OpalParamRegistration m_registrationInfo;
01452 OpalStatusRegistration m_registrationStatus;
01453 OpalParamSetUpCall m_callSetUp;
01454 const char * m_callToken;
01455 OpalStatusIncomingCall m_incomingCall;
01456 OpalParamAnswerCall m_answerCall;
01457 OpalStatusUserInput m_userInput;
01458 OpalStatusMessageWaiting m_messageWaiting;
01459 OpalStatusLineAppearance m_lineAppearance;
01460 OpalStatusCallCleared m_callCleared;
01461 OpalParamCallCleared m_clearCall;
01462 OpalStatusMediaStream m_mediaStream;
01463 OpalParamSetUserData m_setUserData;
01464 OpalParamRecording m_recording;
01465 OpalStatusTransferCall m_transferStatus;
01466 OpalStatusIVR m_ivrStatus;
01467 OpalPresenceStatus m_presenceStatus;
01468 OpalInstantMessage m_instantMessage;
01469
01470 } m_param;
01471 };
01472
01473
01474 #ifdef __cplusplus
01475 };
01476 #endif
01477
01478 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS)
01479
01481 class OpalMessagePtr
01482 {
01483 public:
01484 OpalMessagePtr(OpalMessageType type = OpalIndCommandError);
01485 ~OpalMessagePtr();
01486
01487 OpalMessageType GetType() const;
01488 void SetType(OpalMessageType type);
01489
01490 const char * GetCallToken() const;
01491 void SetCallToken(const char * token);
01492
01493 const char * GetCommandError() const;
01494
01495 OpalParamGeneral * GetGeneralParams() const;
01496 OpalParamProtocol * GetProtocolParams() const;
01497 OpalParamRegistration * GetRegistrationInfo() const;
01498 OpalStatusRegistration * GetRegistrationStatus() const;
01499 OpalParamSetUpCall * GetCallSetUp() const;
01500 OpalStatusIncomingCall * GetIncomingCall() const;
01501 OpalParamAnswerCall * GetAnswerCall() const;
01502 OpalStatusUserInput * GetUserInput() const;
01503 OpalStatusMessageWaiting * GetMessageWaiting() const;
01504 OpalStatusLineAppearance * GetLineAppearance() const;
01505 OpalStatusCallCleared * GetCallCleared() const;
01506 OpalParamCallCleared * GetClearCall() const;
01507 OpalStatusMediaStream * GetMediaStream() const;
01508 OpalParamSetUserData * GetSetUserData() const;
01509 OpalParamRecording * GetRecording() const;
01510 OpalStatusTransferCall * GetTransferStatus() const;
01511 OpalPresenceStatus * GetPresenceStatus() const;
01512 OpalInstantMessage * GetInstantMessage() const;
01513
01514 protected:
01515 OpalMessage * m_message;
01516
01517 private:
01518 OpalMessagePtr(const OpalMessagePtr &) { }
01519 void operator=(const OpalMessagePtr &) { }
01520
01521 friend class OpalContext;
01522 };
01523
01524
01525 #ifdef GetMessage
01526 #undef GetMessage
01527 #endif
01528 #ifdef SendMessage
01529 #undef SendMessage
01530 #endif
01531
01532
01540 class OpalContext
01541 {
01542 public:
01544 OpalContext();
01545
01547 virtual ~OpalContext();
01548
01551 unsigned Initialise(
01552 const char * options,
01553 unsigned version = OPAL_C_API_VERSION
01554 );
01555
01557 bool IsInitialised() const { return m_handle != NULL; }
01558
01560 void ShutDown();
01561
01563 bool GetMessage(
01564 OpalMessagePtr & message,
01565 unsigned timeout = 0
01566 );
01567
01569 bool SendMessage(
01570 const OpalMessagePtr & message,
01571 OpalMessagePtr & response
01572 );
01573
01574
01576 bool SetUpCall(
01577 OpalMessagePtr & response,
01578 const char * partyB,
01579 const char * partyA = NULL,
01580 const char * alertingType = NULL
01581 );
01582
01584 bool AnswerCall(
01585 const char * callToken
01586 );
01587
01589 bool ClearCall(
01590 const char * callToken,
01591 OpalCallEndReason reason = OpalCallEndedByLocalUser
01592 );
01593
01595 bool SendUserInput(
01596 const char * callToken,
01597 const char * userInput,
01598 unsigned duration = 0
01599 );
01600
01601 protected:
01602 OpalHandle m_handle;
01603 };
01604
01605 #endif
01606
01607 #endif // OPAL_OPAL_H
01608
01609