ue-softphone-sdk 2.2.3 → 2.2.4

package/src/api/session-bye-options.ts

@@ -0,0 +1,12 @@
+import { OutgoingRequestDelegate, RequestOptions } from "../core";
+
+/**
+ * Options for {@link Session.bye}.
+ * @public
+ */
+export interface SessionByeOptions {
+  /** See `core` API. */
+  requestDelegate?: OutgoingRequestDelegate;
+  /** See `core` API. */
+  requestOptions?: RequestOptions;
+}

package/src/api/session-delegate.ts

@@ -0,0 +1,80 @@
+import { IncomingRequestMessage } from "../core";
+import { Bye } from "./bye";
+import { Info } from "./info";
+import { Message } from "./message";
+import { Notification } from "./notification";
+import { Referral } from "./referral";
+import { SessionDescriptionHandler } from "./session-description-handler";
+
+/**
+ * Delegate for {@link Session}.
+ * @public
+ */
+export interface SessionDelegate {
+  /**
+   * Called upon receiving an incoming in dialog BYE request.
+   * @param bye - The bye.
+   */
+  onBye?(bye: Bye): void;
+
+  /**
+   * Called upon receiving an incoming in dialog INFO request.
+   * @param info - The info.
+   */
+  onInfo?(info: Info): void;
+
+  /**
+   * Called upon receiving an incoming in dialog INVITE request.
+   * @param invite - The invite.
+   */
+  onInvite?(request: IncomingRequestMessage, response: string, statusCode: number): void;
+
+  /**
+   * Called upon receiving an incoming in dialog MESSAGE request.
+   * @param message - The message.
+   */
+  onMessage?(message: Message): void;
+
+  /**
+   * Called upon receiving an incoming in dialog NOTIFY request.
+   *
+   * @remarks
+   * If a refer is in progress notifications are delivered to the referrers delegate.
+   *
+   * @param notification - The notification.
+   */
+  onNotify?(notification: Notification): void;
+
+  /**
+   * Called upon receiving an incoming in dialog REFER request.
+   * @param referral - The referral.
+   */
+  onRefer?(referral: Referral): void;
+
+  /**
+   * Called upon creating a SessionDescriptionHandler.
+   *
+   * @remarks
+   * It's recommended that the SessionDescriptionHandler be accessed via the `Session.sessionDescriptionHandler` property.
+   * However there are use cases where one needs access immediately after it is constructed and before it is utilized.
+   * Thus this callback.
+   *
+   * In most scenarios a single SessionDescriptionHandler will be created per Session
+   * in which case this callback will be called at most once and `provisional` will be `false`.
+   *
+   * However if reliable provisional responses are being supported and an INVITE is sent without SDP,
+   * one or more session description handlers will be created if remote offers are received in reliable provisional responses.
+   * When remote offers are received in reliable provisional responses, the `provisional` parameter will be `true`.
+   * When the `provisional` paramter is `true`, this callback may (or may not) be called again.
+   * If the session is ultimately established using a SessionDescriptionHandler which was not created provisionally,
+   * this callback will be called again and the `provisional` parameter will be `false`.
+   * If the session is ultimately established using a SessionDescriptionHandler which was created provisionally,
+   * this callback will not be called again.
+   * Note that if the session is ultimately established using a SessionDescriptionHandler which was created provisionally,
+   * the provisional SessionDescriptionHandler being utilized will be available via the `Session.sessionDescriptionHandler` property.
+   *
+   * @param sessionDescriptionHandler - The handler.
+   * @param provisional - True if created provisionally.
+   */
+  onSessionDescriptionHandler?(sessionDescriptionHandler: SessionDescriptionHandler, provisional: boolean): void;
+}

package/src/api/session-description-handler-factory.ts

@@ -0,0 +1,16 @@
+import { Session } from "./session";
+import { SessionDescriptionHandler } from "./session-description-handler";
+
+/**
+ * Factory for {@link SessionDescriptionHandler}.
+ * @public
+ */
+export interface SessionDescriptionHandlerFactory {
+  /**
+   * SessionDescriptionHandler factory function.
+   * @remarks
+   * The `options` are provided as part of the UserAgent configuration
+   * and passed through on every call to SessionDescriptionHandlerFactory's constructor.
+   */
+  (session: Session, options?: object): SessionDescriptionHandler;
+}

package/src/api/session-description-handler.ts

@@ -0,0 +1,89 @@
+/**
+ * Delegate for {@link Session} offer/answer exchange.
+ * @public
+ */
+export interface SessionDescriptionHandler {
+  /**
+   * Destructor.
+   */
+  close(): void;
+
+  /**
+   * Gets the local description from the underlying media implementation.
+   * @param options - Options object to be used by getDescription.
+   * @param modifiers - Array with one time use description modifiers.
+   * @returns Promise that resolves with the local description to be used for the session.
+   * Rejects with `ClosedSessionDescriptionHandlerError` when this method
+   * is called after close or when close occurs before complete.
+   */
+  getDescription(
+    options?: SessionDescriptionHandlerOptions,
+    modifiers?: Array<SessionDescriptionHandlerModifier>
+  ): Promise<BodyAndContentType>;
+
+  /**
+   * Returns true if the Session Description Handler can handle the Content-Type described by a SIP message.
+   * @param contentType - The content type that is in the SIP Message.
+   * @returns True if the content type is  handled by this session description handler. False otherwise.
+   */
+  hasDescription(contentType: string): boolean;
+
+  /**
+   * Rolls back the current local/remote offer to the prior stable state.
+   */
+  rollbackDescription?(): Promise<void>;
+
+  /**
+   * Sets the remote description to the underlying media implementation.
+   * @param  sessionDescription - The description provided by a SIP message to be set on the media implementation.
+   * @param options - Options object to be used by setDescription.
+   * @param modifiers - Array with one time use description modifiers.
+   * @returns Promise that resolves once the description is set.
+   * Rejects with `ClosedSessionDescriptionHandlerError` when this method
+   * is called after close or when close occurs before complete.
+   */
+  setDescription(
+    sdp: string,
+    options?: SessionDescriptionHandlerOptions,
+    modifiers?: Array<SessionDescriptionHandlerModifier>
+  ): Promise<void>;
+
+  /**
+   * Send DTMF via RTP (RFC 4733).
+   * Returns true if DTMF send is successful, false otherwise.
+   * @param tones - A string containing DTMF digits.
+   * @param options - Options object to be used by sendDtmf.
+   * @returns True if DTMF send is successful, false otherwise.
+   */
+  sendDtmf(tones: string, options?: unknown): boolean;
+}
+
+/**
+ * Modifier for {@link SessionDescriptionHandler} offer/answer.
+ * @public
+ */
+export interface SessionDescriptionHandlerModifier {
+  (sessionDescription: RTCSessionDescriptionInit): Promise<RTCSessionDescriptionInit>;
+}
+
+/**
+ * Options for {@link SessionDescriptionHandler} methods.
+ * @remarks
+ * These options are provided to various UserAgent methods (invite() for example)
+ * and passed through on calls to getDescription() and setDescription().
+ * @public
+ */
+export interface SessionDescriptionHandlerOptions {
+  constraints?: object;
+}
+
+/**
+ * Message body content and type.
+ * @public
+ */
+export interface BodyAndContentType {
+  /** Message body content. */
+  body: string;
+  /** Message body content type. */
+  contentType: string;
+}

package/src/api/session-info-options.ts

@@ -0,0 +1,12 @@
+import { OutgoingRequestDelegate, RequestOptions } from "../core";
+
+/**
+ * Options for {@link Session.info}.
+ * @public
+ */
+export interface SessionInfoOptions {
+  /** See `core` API. */
+  requestDelegate?: OutgoingRequestDelegate;
+  /** See `core` API. */
+  requestOptions?: RequestOptions;
+}

package/src/api/session-invite-options.ts

@@ -0,0 +1,29 @@
+import { OutgoingRequestDelegate, RequestOptions } from "../core";
+import { SessionDescriptionHandlerModifier, SessionDescriptionHandlerOptions } from "./session-description-handler";
+
+/**
+ * Options for {@link Session.invite}.
+ * @public
+ */
+export interface SessionInviteOptions {
+  /**
+   * See `core` API.
+   */
+  requestDelegate?: OutgoingRequestDelegate;
+  /**
+   * See `core` API.
+   */
+  requestOptions?: RequestOptions;
+  /**
+   * Modifiers to pass to SessionDescriptionHandler during re-INVITE transaction.
+   */
+  sessionDescriptionHandlerModifiers?: Array<SessionDescriptionHandlerModifier>;
+  /**
+   * Options to pass to SessionDescriptionHandler during re-INVITE transaction.
+   */
+  sessionDescriptionHandlerOptions?: SessionDescriptionHandlerOptions;
+  /**
+   * If true, send INVITE without SDP. Default is false.
+   */
+  withoutSdp?: boolean;
+}

package/src/api/session-message-options.ts

@@ -0,0 +1,12 @@
+import { OutgoingRequestDelegate, RequestOptions } from "../core";
+
+/**
+ * Options for {@link Session.message}.
+ * @public
+ */
+export interface SessionMessageOptions {
+  /** See `core` API. */
+  requestDelegate?: OutgoingRequestDelegate;
+  /** See `core` API. */
+  requestOptions?: RequestOptions;
+}

package/src/api/session-options.ts

@@ -0,0 +1,8 @@
+import { SessionDelegate } from "./session-delegate";
+/**
+ * Options for {@link Session} constructor.
+ * @public
+ */
+export interface SessionOptions {
+  delegate?: SessionDelegate;
+}

package/src/api/session-refer-options.ts

@@ -0,0 +1,15 @@
+import { OutgoingRequestDelegate, RequestOptions } from "../core";
+import { Notification } from "./notification";
+
+/**
+ * Options for {@link Session.refer}.
+ * @public
+ */
+export interface SessionReferOptions {
+  /** Called upon receiving an incoming NOTIFY associated with a REFER. */
+  onNotify?: (notification: Notification) => void;
+  /** See `core` API. */
+  requestDelegate?: OutgoingRequestDelegate;
+  /** See `core` API. */
+  requestOptions?: RequestOptions;
+}

package/src/api/session-state.ts

@@ -0,0 +1,45 @@
+/**
+ * {@link Session} state.
+ *
+ * @remarks
+ * The {@link Session} behaves in a deterministic manner according to the following
+ * Finite State Machine (FSM).
+ * ```txt
+ *                   ___________________________________________________________
+ *                  |  ____________________________________________             |
+ *                  | |            ____________________________    |            |
+ * Session          | |           |                            v   v            v
+ * Constructed -> Initial -> Establishing -> Established -> Terminating -> Terminated
+ *                                |               |___________________________^   ^
+ *                                |_______________________________________________|
+ * ```
+ * @public
+ */
+export enum SessionState {
+  /**
+   * If `Inviter`, INVITE not sent yet.
+   * If `Invitation`, received INVITE (but no final response sent yet).
+   */
+  Initial = "Initial",
+  /**
+   * If `Inviter`, sent INVITE and waiting for a final response.
+   * If `Invitation`, received INVITE and attempting to send 200 final response (but has not sent it yet).
+   */
+  Establishing = "Establishing",
+  /**
+   * If `Inviter`, sent INVITE and received 200 final response and sent ACK.
+   * If `Invitation`, received INVITE and sent 200 final response.
+   */
+  Established = "Established",
+  /**
+   * If `Inviter`, sent INVITE, sent CANCEL and now waiting for 487 final response to ACK (or 200 to ACK & BYE).
+   * If `Invitation`, received INVITE, sent 200 final response and now waiting on ACK and upon receipt will attempt BYE
+   * (as the protocol specification requires, before sending a BYE we must receive the ACK - so we are waiting).
+   */
+  Terminating = "Terminating",
+  /**
+   * If `Inviter`, sent INVITE and received non-200 final response (or sent/received BYE after receiving 200).
+   * If `Invitation`, received INVITE and sent non-200 final response (or sent/received BYE after sending 200).
+   */
+  Terminated = "Terminated"
+}