ue-softphone-sdk 2.2.3 → 2.2.5

package/src/api/referral.ts

@@ -0,0 +1,89 @@
+import { IncomingReferRequest, IncomingRequestMessage, NameAddrHeader, ResponseOptions } from "../core";
+import { Inviter } from "./inviter";
+import { InviterOptions } from "./inviter-options";
+import { Session } from "./session";
+
+/**
+ * A request to establish a {@link Session} elsewhere (incoming REFER).
+ * @public
+ */
+export class Referral {
+  private inviter: Inviter | undefined;
+
+  /** @internal */
+  public constructor(private incomingReferRequest: IncomingReferRequest, private session: Session) {}
+
+  public get referTo(): NameAddrHeader {
+    const referTo = this.incomingReferRequest.message.parseHeader("refer-to");
+    if (!(referTo instanceof NameAddrHeader)) {
+      throw new Error("Failed to parse Refer-To header.");
+    }
+    return referTo;
+  }
+
+  public get referredBy(): string | undefined {
+    return this.incomingReferRequest.message.getHeader("referred-by");
+  }
+
+  public get replaces(): string | undefined {
+    const value = this.referTo.uri.getHeader("replaces");
+    if (value instanceof Array) {
+      return value[0];
+    }
+    return value;
+  }
+
+  /** Incoming REFER request message. */
+  public get request(): IncomingRequestMessage {
+    return this.incomingReferRequest.message;
+  }
+
+  /** Accept the request. */
+  public accept(options: ResponseOptions = { statusCode: 202 }): Promise<void> {
+    this.incomingReferRequest.accept(options);
+    return Promise.resolve();
+  }
+
+  /** Reject the request. */
+  public reject(options?: ResponseOptions): Promise<void> {
+    this.incomingReferRequest.reject(options);
+    return Promise.resolve();
+  }
+
+  /**
+   * Creates an inviter which may be used to send an out of dialog INVITE request.
+   *
+   * @remarks
+   * This a helper method to create an Inviter which will execute the referral
+   * of the `Session` which was referred. The appropriate headers are set and
+   * the referred `Session` is linked to the new `Session`. Note that only a
+   * single instance of the `Inviter` will be created and returned (if called
+   * more than once a reference to the same `Inviter` will be returned every time).
+   *
+   * @param options - Options bucket.
+   * @param modifiers - Session description handler modifiers.
+   */
+  public makeInviter(options?: InviterOptions): Inviter {
+    if (this.inviter) {
+      return this.inviter;
+    }
+    const targetURI = this.referTo.uri.clone();
+    targetURI.clearHeaders();
+    options = options || {};
+    const extraHeaders = (options.extraHeaders || []).slice();
+    const replaces = this.replaces;
+    if (replaces) {
+      // decodeURIComponent is a holdover from 2c086eb4. Not sure that it is actually necessary
+      extraHeaders.push("Replaces: " + decodeURIComponent(replaces));
+    }
+    const referredBy = this.referredBy;
+    if (referredBy) {
+      extraHeaders.push("Referred-By: " + referredBy);
+    }
+    options.extraHeaders = extraHeaders;
+    this.inviter = this.session.userAgent._makeInviter(targetURI, options);
+    this.inviter._referred = this.session;
+    this.session._referral = this.inviter;
+    return this.inviter;
+  }
+}

package/src/api/registerer-options.ts

@@ -0,0 +1,55 @@
+import { URI } from "../core";
+
+/**
+ * Options for {@link Registerer} constructor.
+ * @public
+ */
+export interface RegistererOptions {
+  /** Registration expiration time in seconds. */
+  expires?: number;
+
+  /** Array of extra Contact header parameters. */
+  extraContactHeaderParams?: Array<string>;
+
+  /** Array of extra headers added to the REGISTER. */
+  extraHeaders?: Array<string>;
+
+  /**
+   * UUID to provide with "+sip.instance" Contact parameter.
+   * @defaultValue a randomly generated uuid
+   */
+  instanceId?: string;
+
+  /**
+   * If true, constructor logs the registerer configuration.
+   * @defaultValue `true`
+   */
+  logConfiguration?: boolean;
+
+  /** @deprecated TODO: provide alternative. */
+  params?: {
+    fromDisplayName?: string;
+    fromTag?: string;
+    fromUri?: URI;
+    toDisplayName?: string;
+    toUri?: URI;
+  };
+
+  /**
+   * Value to provide with "reg-id" Contact parameter.
+   * @defaultValue 1
+   */
+  regId?: number;
+
+  /**
+   * The URI of the registrar to send the REGISTER requests.
+   * @defaultValue domain portion of the user agent's uri
+   */
+  registrar?: URI;
+
+  /**
+   * Determines when a re-REGISTER request is sent. The value should be specified as a percentage of the expiration time (between 50 and 99).
+   * @defaultValue 99
+   */
+  refreshFrequency?: number;
+}

package/src/api/registerer-register-options.ts

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

package/src/api/registerer-state.ts

@@ -0,0 +1,21 @@
+/**
+ * {@link Registerer} state.
+ * @remarks
+ * The {@link Registerer} behaves in a deterministic manner according to the following
+ * Finite State Machine (FSM).
+ * ```txt
+ *                   __________________________________________
+ *                  |  __________________________              |
+ * Registerer       | |                          v             v
+ * Constructed -> Initial -> Registered -> Unregistered -> Terminated
+ *                              |   ^____________|             ^
+ *                              |______________________________|
+ * ```
+ * @public
+ */
+export enum RegistererState {
+  Initial = "Initial",
+  Registered = "Registered",
+  Unregistered = "Unregistered",
+  Terminated = "Terminated"
+}

package/src/api/registerer-unregister-options.ts

@@ -0,0 +1,17 @@
+import { OutgoingRequestDelegate, RequestOptions } from "../core";
+
+/**
+ * Options for {@link Registerer.unregister}.
+ * @public
+ */
+export interface RegistererUnregisterOptions {
+  /**
+   * If true, unregister all contacts.
+   * @defaultValue false
+   */
+  all?: boolean;
+  /** See `core` API. */
+  requestDelegate?: OutgoingRequestDelegate;
+  /** See `core` API. */
+  requestOptions?: RequestOptions;
+}