ue-softphone-sdk 2.2.3 → 2.2.5

package/src/core/messages/methods/invite.ts

@@ -0,0 +1,104 @@
+import { Session } from "../../session";
+import { IncomingRequest } from "../incoming-request";
+import { IncomingResponse } from "../incoming-response";
+import { OutgoingRequest, OutgoingRequestDelegate, RequestOptions } from "../outgoing-request";
+import { OutgoingResponse, ResponseOptions } from "../outgoing-response";
+import { OutgoingAckRequest } from "./ack";
+import { OutgoingPrackRequest } from "./prack";
+
+////////////////////
+// Incoming INVITE
+//
+
+/**
+ * Incoming INVITE request.
+ * @public
+ */
+export interface IncomingInviteRequest extends IncomingRequest {
+  /**
+   * Send a 2xx positive final response to this request. Defaults to 200.
+   * @param options - Response options bucket.
+   * @returns Outgoing response and a confirmed Session.
+   */
+  accept(options?: ResponseOptions): OutgoingResponseWithSession;
+
+  /**
+   * Send a 1xx provisional response to this request. Defaults to 180. Excludes 100.
+   * @param options - Response options bucket.
+   * @returns Outgoing response and an early Session.
+   */
+  progress(options?: ResponseOptions): OutgoingResponseWithSession;
+}
+
+/**
+ * Outgoing INVITE response with the associated {@link Session}.
+ * @public
+ */
+export interface OutgoingResponseWithSession extends OutgoingResponse {
+  /**
+   * Session associated with incoming request acceptance, or
+   * Session associated with incoming request progress (if an out of dialog request, an early dialog).
+   */
+  readonly session: Session;
+}
+
+////////////////////
+// Outgoing INVITE
+//
+
+/**
+ * Outgoing INVITE request.
+ * @public
+ */
+export interface OutgoingInviteRequest extends OutgoingRequest {
+  /** Delegate providing custom handling of this outgoing INVITE request. */
+  delegate?: OutgoingInviteRequestDelegate;
+}
+
+/**
+ * Delegate providing custom handling of outgoing INVITE requests.
+ * @public
+ */
+export interface OutgoingInviteRequestDelegate extends OutgoingRequestDelegate {
+  /**
+   * Received a 2xx positive final response to this request.
+   * @param response - Incoming response (including a confirmed Session).
+   */
+  onAccept?(response: AckableIncomingResponseWithSession): void;
+
+  /**
+   * Received a 1xx provisional response to this request. Excluding 100 responses.
+   * @param response - Incoming response (including an early Session).
+   */
+  onProgress?(response: PrackableIncomingResponseWithSession): void;
+}
+
+/**
+ * Incoming INVITE response received when request is accepted.
+ * @public
+ */
+export interface AckableIncomingResponseWithSession extends IncomingResponse {
+  /** Session associated with outgoing request acceptance. */
+  readonly session: Session;
+
+  /**
+   * Send an ACK to acknowledge this response.
+   * @param options - Request options bucket.
+   */
+  ack(options?: RequestOptions): OutgoingAckRequest;
+}
+
+/**
+ * Incoming INVITE response received when request is progressed.
+ * @public
+ */
+export interface PrackableIncomingResponseWithSession extends IncomingResponse {
+  /** Session associated with outgoing request progress. If out of dialog request, an early dialog. */
+  readonly session: Session;
+
+  /**
+   * Send an PRACK to acknowledge this response.
+   * @param options - Request options bucket.
+   */
+  prack(options?: RequestOptions): OutgoingPrackRequest;
+}

package/src/core/messages/methods/message.ts

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-empty-interface */
+import { IncomingRequest } from "../incoming-request";
+import { IncomingResponse } from "../incoming-response";
+import { OutgoingRequest } from "../outgoing-request";
+
+/**
+ * Incoming MESSAGE request.
+ * @public
+ */
+export interface IncomingMessageRequest extends IncomingRequest {}
+
+/**
+ * Incoming MESSAGE response.
+ * @public
+ */
+export interface IncomingMessageResponse extends IncomingResponse {}
+
+/**
+ * Outgoing MESSAGE request.
+ * @public
+ */
+export interface OutgoingMessageRequest extends OutgoingRequest {}

package/src/core/messages/methods/notify.ts

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-empty-interface */
+import { IncomingRequest } from "../incoming-request";
+import { IncomingResponse } from "../incoming-response";
+import { OutgoingRequest } from "../outgoing-request";
+
+/**
+ * Incoming NOTIFY request.
+ * @public
+ */
+export interface IncomingNotifyRequest extends IncomingRequest {}
+
+/**
+ * Incoming NOTIFY response.
+ * @public
+ */
+export interface IncomingNotifyResponse extends IncomingResponse {}
+
+/**
+ * Outgoing NOTIFY request.
+ * @public
+ */
+export interface OutgoingNotifyRequest extends OutgoingRequest {}

package/src/core/messages/methods/prack.ts

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-empty-interface */
+import { IncomingRequest } from "../incoming-request";
+import { IncomingResponse } from "../incoming-response";
+import { OutgoingRequest } from "../outgoing-request";
+
+/**
+ * Incoming PRACK request.
+ * @public
+ */
+export interface IncomingPrackRequest extends IncomingRequest {}
+
+/**
+ * Incoming PRACK response.
+ * @public
+ */
+export interface IncomingPrackResponse extends IncomingResponse {}
+
+/**
+ * Outgoing PRACK request.
+ * @public
+ */
+export interface OutgoingPrackRequest extends OutgoingRequest {}

package/src/core/messages/methods/publish.ts

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-empty-interface */
+import { IncomingRequest } from "../incoming-request";
+import { IncomingResponse } from "../incoming-response";
+import { OutgoingRequest } from "../outgoing-request";
+
+/**
+ * Incoming PUBLISH request.
+ * @public
+ */
+export interface IncomingPublishRequest extends IncomingRequest {}
+
+/**
+ * Incoming PUBLISH response.
+ * @public
+ */
+export interface IncomingPublishResponse extends IncomingResponse {}
+
+/**
+ * Outgoing PUBLISH request.
+ * @public
+ */
+export interface OutgoingPublishRequest extends OutgoingRequest {}

package/src/core/messages/methods/refer.ts

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-empty-interface */
+import { IncomingRequest } from "../incoming-request";
+import { IncomingResponse } from "../incoming-response";
+import { OutgoingRequest } from "../outgoing-request";
+
+/**
+ * Incoming REFER request.
+ * @public
+ */
+export interface IncomingReferRequest extends IncomingRequest {}
+
+/**
+ * Incoming REFER response.
+ * @public
+ */
+export interface IncomingReferResponse extends IncomingResponse {}
+
+/**
+ * Outgoing REFER request.
+ * @public
+ */
+export interface OutgoingReferRequest extends OutgoingRequest {}

package/src/core/messages/methods/register.ts

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-empty-interface */
+import { IncomingRequest } from "../incoming-request";
+import { IncomingResponse } from "../incoming-response";
+import { OutgoingRequest } from "../outgoing-request";
+
+/**
+ * Incoming REGISTER request.
+ * @public
+ */
+export interface IncomingRegisterRequest extends IncomingRequest {}
+
+/**
+ * Incoming REGISTER response.
+ * @public
+ */
+export interface IncomingRegisterResponse extends IncomingResponse {}
+
+/**
+ * Outgoing REGISTER request.
+ * @public
+ */
+export interface OutgoingRegisterRequest extends OutgoingRequest {}

package/src/core/messages/methods/subscribe.ts

@@ -0,0 +1,59 @@
+/* eslint-disable @typescript-eslint/no-empty-interface */
+import { Subscription } from "../../subscription";
+import { IncomingRequest } from "../incoming-request";
+import { IncomingResponse } from "../incoming-response";
+import { OutgoingRequest, OutgoingRequestDelegate } from "../outgoing-request";
+import { IncomingNotifyRequest } from "./notify";
+
+/**
+ * Incoming SUBSCRIBE request.
+ * @public
+ */
+export interface IncomingSubscribeRequest extends IncomingRequest {}
+
+/**
+ * Incoming SUBSCRIBE response.
+ * @public
+ */
+export interface IncomingSubscribeResponse extends IncomingResponse {}
+
+/**
+ * Outgoing SUBSCRIBE request.
+ * @public
+ */
+export interface OutgoingSubscribeRequest extends OutgoingRequest {
+  /** Delegate providing custom handling of this outgoing SUBSCRIBE request. */
+  delegate?: OutgoingSubscribeRequestDelegate;
+  /** Stop waiting for an inital subscription creating NOTIFY. */
+  waitNotifyStop(): void;
+}
+
+/**
+ * Delegate providing custom handling of outgoing SUBSCRIBE requests.
+ * @public
+ */
+export interface OutgoingSubscribeRequestDelegate extends OutgoingRequestDelegate {
+  /**
+   * Received the initial subscription creating NOTIFY in response to this request.
+   * Called for out of dialog SUBSCRIBE requests only (not called for re-SUBSCRIBE requests).
+   * @param request - Incoming NOTIFY request (including a Subscription).
+   */
+  onNotify?(request: IncomingRequestWithSubscription): void;
+
+  /**
+   * Timed out waiting to receive the initial subscription creating NOTIFY in response to this request.
+   * Called for out of dialog SUBSCRIBE requests only (not called for re-SUBSCRIBE requests).
+   */
+  onNotifyTimeout?(): void;
+}
+
+/**
+ * Incoming NOTIFY request with associated {@link Subscription}.
+ * @public
+ */
+export interface IncomingRequestWithSubscription {
+  /** The NOTIFY request which established the subscription. */
+  readonly request: IncomingNotifyRequest;
+  /** If subscription state is not "terminated", then the subscription. Otherwise undefined. */
+  readonly subscription?: Subscription;
+}

package/src/core/messages/outgoing-request-message.ts

@@ -0,0 +1,299 @@
+import { NameAddrHeader, URI } from "../../grammar";
+import { Body } from "./body";
+import { createRandomToken, headerize, newTag, utf8Length } from "./utils";
+
+/**
+ * Outgoing request message options.
+ * @public
+ */
+export interface OutgoingRequestMessageOptions {
+  callId?: string;
+  callIdPrefix?: string;
+  cseq?: number;
+  toDisplayName?: string;
+  toTag?: string;
+  fromDisplayName?: string;
+  fromTag?: string;
+  forceRport?: boolean;
+  hackViaTcp?: boolean;
+  optionTags?: Array<string>;
+  routeSet?: Array<string>;
+  userAgentString?: string;
+  viaHost?: string;
+}
+
+/**
+ * Outgoing SIP request message.
+ * @public
+ */
+export class OutgoingRequestMessage {
+  public readonly headers: { [name: string]: Array<string> } = {};
+
+  public readonly method: string;
+  public readonly ruri: URI;
+  public readonly from: NameAddrHeader;
+  public readonly fromTag: string;
+  public readonly fromURI: URI;
+  public readonly to: NameAddrHeader;
+  public readonly toTag: string | undefined;
+  public readonly toURI: URI;
+  public branch: string | undefined;
+  public readonly callId: string;
+  public cseq: number;
+  public extraHeaders: Array<string> = [];
+  public body: { body: string; contentType: string } | undefined;
+
+  private options: Required<OutgoingRequestMessageOptions>;
+
+  constructor(
+    method: string,
+    ruri: URI,
+    fromURI: URI,
+    toURI: URI,
+    options?: OutgoingRequestMessageOptions,
+    extraHeaders?: Array<string>,
+    body?: Body
+  ) {
+    // Initialize default options
+    this.options = OutgoingRequestMessage.getDefaultOptions();
+
+    // Options - merge a deep copy
+    if (options) {
+      this.options = {
+        ...this.options,
+        ...options
+      };
+      if (this.options.optionTags && this.options.optionTags.length) {
+        this.options.optionTags = this.options.optionTags.slice();
+      }
+      if (this.options.routeSet && this.options.routeSet.length) {
+        this.options.routeSet = this.options.routeSet.slice();
+      }
+    }
+
+    // Extra headers - deep copy
+    if (extraHeaders && extraHeaders.length) {
+      this.extraHeaders = extraHeaders.slice();
+    }
+
+    // Body - deep copy
+    if (body) {
+      // TODO: internal representation should be Body
+      // this.body = { ...body };
+      this.body = {
+        body: body.content,
+        contentType: body.contentType
+      };
+    }
+
+    // Method
+    this.method = method;
+
+    // RURI
+    this.ruri = ruri.clone();
+
+    // From
+    this.fromURI = fromURI.clone();
+    this.fromTag = this.options.fromTag ? this.options.fromTag : newTag();
+    this.from = OutgoingRequestMessage.makeNameAddrHeader(this.fromURI, this.options.fromDisplayName, this.fromTag);
+
+    // To
+    this.toURI = toURI.clone();
+    this.toTag = this.options.toTag;
+    this.to = OutgoingRequestMessage.makeNameAddrHeader(this.toURI, this.options.toDisplayName, this.toTag);
+
+    // Call-ID
+    this.callId = this.options.callId ? this.options.callId : this.options.callIdPrefix + createRandomToken(15);
+
+    // CSeq
+    this.cseq = this.options.cseq;
+
+    // The relative order of header fields with different field names is not
+    // significant.  However, it is RECOMMENDED that header fields which are
+    // needed for proxy processing (Via, Route, Record-Route, Proxy-Require,
+    // Max-Forwards, and Proxy-Authorization, for example) appear towards
+    // the top of the message to facilitate rapid parsing.
+    // https://tools.ietf.org/html/rfc3261#section-7.3.1
+    this.setHeader("route", this.options.routeSet);
+    this.setHeader("via", "");
+    this.setHeader("to", this.to.toString());
+    this.setHeader("from", this.from.toString());
+    this.setHeader("cseq", this.cseq + " " + this.method);
+    this.setHeader("call-id", this.callId);
+    this.setHeader("max-forwards", "70");
+  }
+
+  /** Get a copy of the default options. */
+  private static getDefaultOptions(): Required<OutgoingRequestMessageOptions> {
+    return {
+      callId: "",
+      callIdPrefix: "",
+      cseq: 1,
+      toDisplayName: "",
+      toTag: "",
+      fromDisplayName: "",
+      fromTag: "",
+      forceRport: false,
+      hackViaTcp: false,
+      optionTags: ["outbound"],
+      routeSet: [],
+      userAgentString: "sip.js",
+      viaHost: ""
+    };
+  }
+
+  private static makeNameAddrHeader(uri: URI, displayName: string, tag: string): NameAddrHeader {
+    const parameters: { [name: string]: string } = {};
+    if (tag) {
+      parameters.tag = tag;
+    }
+    return new NameAddrHeader(uri, displayName, parameters);
+  }
+
+  /**
+   * Get the value of the given header name at the given position.
+   * @param name - header name
+   * @returns Returns the specified header, undefined if header doesn't exist.
+   */
+  public getHeader(name: string): string | undefined {
+    const header: Array<string> = this.headers[headerize(name)];
+    if (header) {
+      if (header[0]) {
+        return header[0];
+      }
+    } else {
+      const regexp = new RegExp("^\\s*" + name + "\\s*:", "i");
+      for (const exHeader of this.extraHeaders) {
+        if (regexp.test(exHeader)) {
+          return exHeader.substring(exHeader.indexOf(":") + 1).trim();
+        }
+      }
+    }
+
+    return;
+  }
+
+  /**
+   * Get the header/s of the given name.
+   * @param name - header name
+   * @returns Array with all the headers of the specified name.
+   */
+  public getHeaders(name: string): Array<string> {
+    const result: Array<string> = [];
+    const headerArray: Array<string> = this.headers[headerize(name)];
+
+    if (headerArray) {
+      for (const headerPart of headerArray) {
+        result.push(headerPart);
+      }
+    } else {
+      const regexp = new RegExp("^\\s*" + name + "\\s*:", "i");
+      for (const exHeader of this.extraHeaders) {
+        if (regexp.test(exHeader)) {
+          result.push(exHeader.substring(exHeader.indexOf(":") + 1).trim());
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Verify the existence of the given header.
+   * @param name - header name
+   * @returns true if header with given name exists, false otherwise
+   */
+  public hasHeader(name: string): boolean {
+    if (this.headers[headerize(name)]) {
+      return true;
+    } else {
+      const regexp = new RegExp("^\\s*" + name + "\\s*:", "i");
+      for (const extraHeader of this.extraHeaders) {
+        if (regexp.test(extraHeader)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Replace the the given header by the given value.
+   * @param name - header name
+   * @param value - header value
+   */
+  public setHeader(name: string, value: string | Array<string>): void {
+    this.headers[headerize(name)] = value instanceof Array ? value : [value];
+  }
+
+  /**
+   * The Via header field indicates the transport used for the transaction
+   * and identifies the location where the response is to be sent.  A Via
+   * header field value is added only after the transport that will be
+   * used to reach the next hop has been selected (which may involve the
+   * usage of the procedures in [4]).
+   *
+   * When the UAC creates a request, it MUST insert a Via into that
+   * request.  The protocol name and protocol version in the header field
+   * MUST be SIP and 2.0, respectively.  The Via header field value MUST
+   * contain a branch parameter.  This parameter is used to identify the
+   * transaction created by that request.  This parameter is used by both
+   * the client and the server.
+   * https://tools.ietf.org/html/rfc3261#section-8.1.1.7
+   * @param branchParameter - The branch parameter.
+   * @param transport - The sent protocol transport.
+   */
+  public setViaHeader(branch: string, transport: string): void {
+    // FIXME: Hack
+    if (this.options.hackViaTcp) {
+      transport = "TCP";
+    }
+    let via = "SIP/2.0/" + transport;
+    via += " " + this.options.viaHost + ";branch=" + branch;
+    if (this.options.forceRport) {
+      via += ";rport";
+    }
+    this.setHeader("via", via);
+    this.branch = branch;
+  }
+
+  public toString(): string {
+    let msg = "";
+
+    msg += this.method + " " + this.ruri.toRaw() + " SIP/2.0\r\n";
+
+    for (const header in this.headers) {
+      if (this.headers[header]) {
+        for (const headerPart of this.headers[header]) {
+          msg += header + ": " + headerPart + "\r\n";
+        }
+      }
+    }
+
+    for (const header of this.extraHeaders) {
+      msg += header.trim() + "\r\n";
+    }
+
+    msg += "Supported: " + this.options.optionTags.join(", ") + "\r\n";
+    msg += "User-Agent: " + this.options.userAgentString + "\r\n";
+
+    if (this.body) {
+      if (typeof this.body === "string") {
+        msg += "Content-Length: " + utf8Length(this.body) + "\r\n\r\n";
+        msg += this.body;
+      } else {
+        if (this.body.body && this.body.contentType) {
+          msg += "Content-Type: " + this.body.contentType + "\r\n";
+          msg += "Content-Length: " + utf8Length(this.body.body) + "\r\n\r\n";
+          msg += this.body.body;
+        } else {
+          msg += "Content-Length: " + 0 + "\r\n\r\n";
+        }
+      }
+    } else {
+      msg += "Content-Length: " + 0 + "\r\n\r\n";
+    }
+
+    return msg;
+  }
+}

package/src/core/messages/outgoing-request.ts

@@ -0,0 +1,77 @@
+import { Body } from "./body";
+import { IncomingResponse } from "./incoming-response";
+import { OutgoingRequestMessage } from "./outgoing-request-message";
+
+/**
+ * A SIP message sent from a local client to a remote server.
+ * @remarks
+ * For the purpose of invoking a particular operation.
+ * https://tools.ietf.org/html/rfc3261#section-7.1
+ * @public
+ */
+export interface OutgoingRequest {
+  /** Delegate providing custom handling of this outgoing request. */
+  delegate?: OutgoingRequestDelegate;
+
+  /** The outgoing message. */
+  readonly message: OutgoingRequestMessage;
+
+  /**
+   * Destroy request.
+   */
+  dispose(): void;
+
+  /**
+   * Sends a CANCEL message targeting this request to the UAS.
+   * @param reason - Reason for canceling request.
+   * @param options - Request options bucket.
+   */
+  cancel(reason?: string, options?: RequestOptions): void;
+}
+
+/**
+ * Delegate providing custom handling of outgoing requests.
+ * @public
+ */
+export interface OutgoingRequestDelegate {
+  /**
+   * Received a 2xx positive final response to this request.
+   * @param response - Incoming response.
+   */
+  onAccept?(response: IncomingResponse): void;
+
+  /**
+   * Received a 1xx provisional response to this request. Excluding 100 responses.
+   * @param response - Incoming response.
+   */
+  onProgress?(response: IncomingResponse): void;
+
+  /**
+   * Received a 3xx negative final response to this request.
+   * @param response - Incoming response.
+   */
+  onRedirect?(response: IncomingResponse): void;
+
+  /**
+   * Received a 4xx, 5xx, or 6xx negative final response to this request.
+   * @param response - Incoming response.
+   */
+  onReject?(response: IncomingResponse): void;
+
+  /**
+   * Received a 100 provisional response.
+   * @param response - Incoming response.
+   */
+  onTrying?(response: IncomingResponse): void;
+}
+
+/**
+ * Request options bucket.
+ * @public
+ */
+export interface RequestOptions {
+  /** Extra headers to include in the message. */
+  extraHeaders?: Array<string>;
+  /** Body to include in the message. */
+  body?: Body;
+}