diff --git a/RELEASE.md b/RELEASE.md index cde59a70b..3a9b3cdd0 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -28,7 +28,7 @@ All the demos must work. ## Documentation -Make sure the documentation is up to date and review any changes to the API. Commit any new documentation and consider the version number bump based on the changes to the API. +Make sure the documentation is up to date and review any changes to the API. Commit any new documentation and consider the version number bump based on the changes to the API. If you commit any changes, go back to the Clean, Build and Test step. * `npm run build-docs` @@ -53,8 +53,7 @@ This approach will leverage the `npm pack` command to package up and zip your np 1. From within your npm package directory, run `npm pack` in your terminal. Note the .tgz file it produces and the location of it. 2. Change directories to the project directory where you want to use the npm package. Example: `cd /path/to/project` 3. From within the client project directory, run `npm install /path/to/package.tgz` but replace it with the proper path to the location of the .tgz file from step 1. -4. Then you can start using the package in that client project to test things out -This will give you the closest to production experience for using your npm package. +4. Then you can start using the package in that client project to test things out. This will give you the closest to production experience for using your npm package. 5. Delete the .tgz file created in step 1. ## Tag, Push and Publish diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 0d9dbfd03..abcc60c4c 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -2,6 +2,10 @@ * From [Simple to SimpleUser](./migration-simple.md) is relatively simple. +* From [0.20 to 0.21](./migration-0.20-0.21.md) + * 0.21 has two minor breaking changes with 0.20 + * ECMAScript module support and SessionManager introduction + * From 0.19 to 0.20 * 0.20 is backwards compatible with 0.19 diff --git a/docs/README.md b/docs/README.md index ae21fd55d..a877f83d3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,12 +18,15 @@ Bundle? Download UMD [here](https://sipjs.com/download). ## What is here? -Herein lies software enabling Session Initiation Protocol (SIP) internet endpoints (called user agents) to carry various forms of real-time multimedia session data such as voice, video, or text messages. Said software is organized into three (3) divisions - each of which provides a different integration point for development... +Herein lies software enabling Session Initiation Protocol (SIP) internet endpoints (called user agents) to carry various forms of real-time multimedia session data such as voice, video, or text messages. Said software is organized into four (4) divisions - each of which provides a different integration point for development... * SimpleUser class * [Demo](../demo/README.md) * [Overview](./simple-user.md) * [Reference](./simple-user/sip.js.md) +* SessionManager class + * [Overview](./session-manager.md) + * [Reference](./session-manager/sip.js.md) * API framework * [Overview](./api.md) * [Reference](./api/sip.js.md) @@ -42,11 +45,15 @@ Additional supporting implementations of classes for use with web browser enviro ### SimpleUser class -The [SimpleUser](./simple-user.md) class provides a representation of a simple internet endpoint (a simple user agent). It requires an understanding of what a phone call is, but minimal knowledge of SIP. There are working [Demonstrations](../demo/README.md) provided to help get started. It is the recommended interface for many applications. It has its limitations. The [SimpleUser](./simple-user.md) class is implemented utilizing the [API](./api.md) framework and as such provides a working example of how one might utilize the [API](./api.md) framework. +The [SimpleUser](./simple-user.md) class provides a representation of a simple internet endpoint (a simple user agent). It requires an understanding of what a phone call is, but minimal knowledge of SIP. There are working [Demonstrations](../demo/README.md) provided to help get started. It is the recommended interface for many applications. It has its limitations. The [SimpleUser](./simple-user.md) class is implemented utilizing the [SessionManager](./session-manager.md) class and as such provides a working example of how one might utilize the [SessionManager](./session-manager.md) class. + +### SessionManager class + +The [SessionManager](./session-manager.md) class provides a representation of a simple internet endpoint which can handle multiple concurrent calls (a user agent). It requires an understanding of what a phone call is, but minimal knowledge of SIP. It is the recommended interface for many applications which require managing multiple concurrent calls. It has its limitations. The [SessionManager](./session-manager.md) class is implemented utilizing the [API](./api.md) framework and as such provides a working example of how one might utilize the [API](./api.md) framework. ### API framework -The [API](./api.md) framework is intended to provide a complete and suitable framework on which to build most end user applications - business phones, video conferencing endpoints, smart doorbells. A working knowledge of the SIP protocol is a prerequisite for using it. The framework provides infrastructure to connect with a SIP server as well as establish and maintain SIP registrations, sessions and subscriptions. There are no user interface components in it. The source code of the [SimpleUser](./simple-user.md) class is well documented and provides a good example of how to get started using the [API](./api.md) framework. The framework is implemented on top of the [Core](./core.md) library and as such provides a working example of how one might utilize the [Core](./core.md) library. +The [API](./api.md) framework is intended to provide a complete and suitable framework on which to build most end user applications - business phones, video conferencing endpoints, smart doorbells. A working knowledge of the SIP protocol is a prerequisite for using it. The framework provides infrastructure to connect with a SIP server as well as establish and maintain SIP registrations, sessions and subscriptions. There are no user interface components in it. The source code of the [SessionManager](./session-manager.md) class is well documented and provides a good example of how to get started using the [API](./api.md) framework. The framework is implemented on top of the [Core](./core.md) library and as such provides a working example of how one might utilize the [Core](./core.md) library. ### Core library diff --git a/docs/api/sip.js.cancel.md b/docs/api/sip.js.cancel.md new file mode 100644 index 000000000..9b8bde9a6 --- /dev/null +++ b/docs/api/sip.js.cancel.md @@ -0,0 +1,24 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [Cancel](./sip.js.cancel.md) + +## Cancel class + +A request to reject an [Invitation](./sip.js.invitation.md) (incoming CANCEL). + +Signature: + +```typescript +export declare class Cancel +``` + +## Remarks + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Cancel` class. + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [request](./sip.js.cancel.request.md) | | IncomingRequestMessage | Incoming CANCEL request message. | + diff --git a/docs/api/sip.js.cancel.request.md b/docs/api/sip.js.cancel.request.md new file mode 100644 index 000000000..aee696113 --- /dev/null +++ b/docs/api/sip.js.cancel.request.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [Cancel](./sip.js.cancel.md) > [request](./sip.js.cancel.request.md) + +## Cancel.request property + +Incoming CANCEL request message. + +Signature: + +```typescript +get request(): IncomingRequestMessage; +``` diff --git a/docs/api/sip.js.md b/docs/api/sip.js.md index 15bcdfd24..5561c3ac7 100644 --- a/docs/api/sip.js.md +++ b/docs/api/sip.js.md @@ -12,6 +12,7 @@ A simple yet powerful API which takes care of SIP signaling and WebRTC media ses | --- | --- | | [Ack](./sip.js.ack.md) | A request to confirm a [Session](./sip.js.session.md) (incoming ACK). | | [Bye](./sip.js.bye.md) | A request to end a [Session](./sip.js.session.md) (incoming BYE). | +| [Cancel](./sip.js.cancel.md) | A request to reject an [Invitation](./sip.js.invitation.md) (incoming CANCEL). | | [ContentTypeUnsupportedError](./sip.js.contenttypeunsupportederror.md) | An exception indicating an unsupported content type prevented execution. | | [Info](./sip.js.info.md) | An exchange of information (incoming INFO). | | [Invitation](./sip.js.invitation.md) | An invitation is an offer to establish a [Session](./sip.js.session.md) (incoming INVITE). | diff --git a/docs/api/sip.js.registereroptions.instanceid.md b/docs/api/sip.js.registereroptions.instanceid.md index 9f41f6af5..0f07a3b0d 100644 --- a/docs/api/sip.js.registereroptions.instanceid.md +++ b/docs/api/sip.js.registereroptions.instanceid.md @@ -4,6 +4,11 @@ ## RegistererOptions.instanceId property +> Warning: This API is now obsolete. +> +> Use UserAgentOptions.instanceId +> + UUID to provide with "+sip.instance" Contact parameter. Signature: diff --git a/docs/api/sip.js.sessiondelegate.md b/docs/api/sip.js.sessiondelegate.md index f8f5eef8e..712a95302 100644 --- a/docs/api/sip.js.sessiondelegate.md +++ b/docs/api/sip.js.sessiondelegate.md @@ -18,6 +18,7 @@ export interface SessionDelegate | --- | --- | | [onAck(ack)](./sip.js.sessiondelegate.onack.md) | Called upon receiving an incoming in dialog ACK request. | | [onBye(bye)](./sip.js.sessiondelegate.onbye.md) | Called upon receiving an incoming in dialog BYE request. | +| [onCancel(cancel)](./sip.js.sessiondelegate.oncancel.md) | Called upon receiving an incoming CANCEL request. | | [onInfo(info)](./sip.js.sessiondelegate.oninfo.md) | Called upon receiving an incoming in dialog INFO request. | | [onInvite(request, response, statusCode)](./sip.js.sessiondelegate.oninvite.md) | Called upon receiving an incoming in dialog INVITE request. | | [onMessage(message)](./sip.js.sessiondelegate.onmessage.md) | Called upon receiving an incoming in dialog MESSAGE request. | diff --git a/docs/api/sip.js.sessiondelegate.onack.md b/docs/api/sip.js.sessiondelegate.onack.md index 4de32d3f5..c3e92dec2 100644 --- a/docs/api/sip.js.sessiondelegate.onack.md +++ b/docs/api/sip.js.sessiondelegate.onack.md @@ -22,3 +22,7 @@ onAck?(ack: Ack): void; void +## Remarks + +Includes the ACK confirming an accepted initial Invite as well as ACKs associated with in dialog INVITE requests. + diff --git a/docs/api/sip.js.sessiondelegate.oncancel.md b/docs/api/sip.js.sessiondelegate.oncancel.md new file mode 100644 index 000000000..6214f748d --- /dev/null +++ b/docs/api/sip.js.sessiondelegate.oncancel.md @@ -0,0 +1,28 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [SessionDelegate](./sip.js.sessiondelegate.md) > [onCancel](./sip.js.sessiondelegate.oncancel.md) + +## SessionDelegate.onCancel() method + +Called upon receiving an incoming CANCEL request. + +Signature: + +```typescript +onCancel?(cancel: Cancel): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| cancel | [Cancel](./sip.js.cancel.md) | The cancel. | + +Returns: + +void + +## Remarks + +Relevant to an Invitation only. CANCEL reqeusts are being handled as a special case and there is currently no way to externally impact the response to the a CANCEL request. See core implementation for details. + diff --git a/docs/api/sip.js.subscriber.md b/docs/api/sip.js.subscriber.md index 7e1cb3ecd..d74d98fe6 100644 --- a/docs/api/sip.js.subscriber.md +++ b/docs/api/sip.js.subscriber.md @@ -29,6 +29,8 @@ const subscriber = new Subscriber(userAgent, targetURI, eventType); // Add delegate to handle event notifications. subscriber.delegate = { onNotify: (notification: Notification) => { + // send a response + notification.accept(); // handle notification here } }; diff --git a/docs/api/sip.js.useragent.instanceid.md b/docs/api/sip.js.useragent.instanceid.md new file mode 100644 index 000000000..a676180d8 --- /dev/null +++ b/docs/api/sip.js.useragent.instanceid.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [UserAgent](./sip.js.useragent.md) > [instanceId](./sip.js.useragent.instanceid.md) + +## UserAgent.instanceId property + +User agent instance id. + +Signature: + +```typescript +get instanceId(): string; +``` diff --git a/docs/api/sip.js.useragent.makeuri.md b/docs/api/sip.js.useragent.makeuri.md index bc7e78fa6..a9ac2d8c4 100644 --- a/docs/api/sip.js.useragent.makeuri.md +++ b/docs/api/sip.js.useragent.makeuri.md @@ -22,6 +22,10 @@ static makeURI(uri: string): URI | undefined; URI \| undefined +## Remarks + +Returns undefined if the syntax of the URI is invalid. The syntax must conform to a SIP URI as defined in the RFC. 25 Augmented BNF for the SIP Protocol https://tools.ietf.org/html/rfc3261\#section-25 + ## Example diff --git a/docs/api/sip.js.useragent.md b/docs/api/sip.js.useragent.md index f95a29483..251d14a66 100644 --- a/docs/api/sip.js.useragent.md +++ b/docs/api/sip.js.useragent.md @@ -30,6 +30,7 @@ A user agent (UA) is associated with a user via the user's SIP address of record | [contact](./sip.js.useragent.contact.md) | | Contact | User agent contact. | | [data](./sip.js.useragent.data.md) | | unknown | Property reserved for use by instance owner. | | [delegate](./sip.js.useragent.delegate.md) | | [UserAgentDelegate](./sip.js.useragentdelegate.md) \| undefined | Delegate. | +| [instanceId](./sip.js.useragent.instanceid.md) | | string | User agent instance id. | | [state](./sip.js.useragent.state.md) | | [UserAgentState](./sip.js.useragentstate.md) | User agent state. | | [stateChange](./sip.js.useragent.statechange.md) | | [Emitter](./sip.js.emitter.md)<[UserAgentState](./sip.js.useragentstate.md)> | User agent state change emitter. | | [transport](./sip.js.useragent.transport.md) | | [Transport](./sip.js.transport.md) | User agent transport. | diff --git a/docs/api/sip.js.useragent.start.md b/docs/api/sip.js.useragent.start.md index ccf8b22c4..fa1be0750 100644 --- a/docs/api/sip.js.useragent.start.md +++ b/docs/api/sip.js.useragent.start.md @@ -17,7 +17,7 @@ Promise<void> ## Remarks -Resolves if transport connects, otherwise rejects. +Resolves if transport connects, otherwise rejects. Calling `start()` after calling `stop()` will fail if `stop()` has yet to resolve. ## Example diff --git a/docs/api/sip.js.useragent.stop.md b/docs/api/sip.js.useragent.stop.md index e4c56b6a0..dccbad02b 100644 --- a/docs/api/sip.js.useragent.stop.md +++ b/docs/api/sip.js.useragent.stop.md @@ -27,6 +27,8 @@ Resolves when the user agent has completed a graceful shutdown. 5) Transport disconnects. 6) User Agent Core resets. ``` +The user agent state transistions to stopped once these steps have been completed. Calling `start()` after calling `stop()` will fail if `stop()` has yet to resolve. + NOTE: While this is a "graceful shutdown", it can also be very slow one if you are waiting for the returned Promise to resolve. The disposal of the clients and dialogs is done serially - waiting on one to finish before moving on to the next. This can be slow if there are lot of subscriptions to unsubscribe for example. THE SLOW PACE IS INTENTIONAL! While one could spin them all down in parallel, this could slam the remote server. It is bad practice to denial of service attack (DoS attack) servers!!! Moreover, production servers will automatically blacklist clients which send too many requests in too short a period of time - dropping any additional requests. diff --git a/docs/api/sip.js.useragentoptions.autostart.md b/docs/api/sip.js.useragentoptions.autostart.md deleted file mode 100644 index 0c601a7bb..000000000 --- a/docs/api/sip.js.useragentoptions.autostart.md +++ /dev/null @@ -1,21 +0,0 @@ - - -[Home](./index.md) > [sip.js](./sip.js.md) > [UserAgentOptions](./sip.js.useragentoptions.md) > [autoStart](./sip.js.useragentoptions.autostart.md) - -## UserAgentOptions.autoStart property - -> Warning: This API is now obsolete. -> -> If `true`, the user agent calls the `start()` method in the constructor. -> - -Signature: - -```typescript -autoStart?: boolean; -``` - -## Remarks - -The call to start() resolves when the user agent connects, so if this option is set to `true` an alternative method of connection detection must be used. - diff --git a/docs/api/sip.js.useragentoptions.autostop.md b/docs/api/sip.js.useragentoptions.autostop.md deleted file mode 100644 index e598371a9..000000000 --- a/docs/api/sip.js.useragentoptions.autostop.md +++ /dev/null @@ -1,13 +0,0 @@ - - -[Home](./index.md) > [sip.js](./sip.js.md) > [UserAgentOptions](./sip.js.useragentoptions.md) > [autoStop](./sip.js.useragentoptions.autostop.md) - -## UserAgentOptions.autoStop property - -If `true`, the user agent calls the `stop()` method on unload (if running in browser window). - -Signature: - -```typescript -autoStop?: boolean; -``` diff --git a/docs/api/sip.js.useragentoptions.gracefulshutdown.md b/docs/api/sip.js.useragentoptions.gracefulshutdown.md new file mode 100644 index 000000000..97cea4717 --- /dev/null +++ b/docs/api/sip.js.useragentoptions.gracefulshutdown.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [UserAgentOptions](./sip.js.useragentoptions.md) > [gracefulShutdown](./sip.js.useragentoptions.gracefulshutdown.md) + +## UserAgentOptions.gracefulShutdown property + +If `true`, the `stop()` method will attempt to gracefully end all dialogs and registrations before disconnecting. Otherwise `stop()` will transition immediately abandoning all dialogs and registrations. + +Signature: + +```typescript +gracefulShutdown?: boolean; +``` diff --git a/docs/api/sip.js.useragentoptions.instanceid.md b/docs/api/sip.js.useragentoptions.instanceid.md new file mode 100644 index 000000000..4956caad3 --- /dev/null +++ b/docs/api/sip.js.useragentoptions.instanceid.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [UserAgentOptions](./sip.js.useragentoptions.md) > [instanceId](./sip.js.useragentoptions.instanceid.md) + +## UserAgentOptions.instanceId property + +UUID to provide with "+sip.instance" Contact header parameter. + +Signature: + +```typescript +instanceId?: string; +``` diff --git a/docs/api/sip.js.useragentoptions.instanceidalwaysadded.md b/docs/api/sip.js.useragentoptions.instanceidalwaysadded.md new file mode 100644 index 000000000..8c896d110 --- /dev/null +++ b/docs/api/sip.js.useragentoptions.instanceidalwaysadded.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [UserAgentOptions](./sip.js.useragentoptions.md) > [instanceIdAlwaysAdded](./sip.js.useragentoptions.instanceidalwaysadded.md) + +## UserAgentOptions.instanceIdAlwaysAdded property + +Add "+sip.instance" Contact header parameter to all requests. + +Signature: + +```typescript +instanceIdAlwaysAdded?: boolean; +``` diff --git a/docs/api/sip.js.useragentoptions.md b/docs/api/sip.js.useragentoptions.md index faa94fff7..0de05f4a4 100644 --- a/docs/api/sip.js.useragentoptions.md +++ b/docs/api/sip.js.useragentoptions.md @@ -20,16 +20,17 @@ export interface UserAgentOptions | [authorizationHa1](./sip.js.useragentoptions.authorizationha1.md) | | string | Authorization ha1. | | [authorizationPassword](./sip.js.useragentoptions.authorizationpassword.md) | | string | Authorization password. | | [authorizationUsername](./sip.js.useragentoptions.authorizationusername.md) | | string | Authorization username. | -| [autoStart](./sip.js.useragentoptions.autostart.md) | | boolean | | -| [autoStop](./sip.js.useragentoptions.autostop.md) | | boolean | If true, the user agent calls the stop() method on unload (if running in browser window). | | [contactName](./sip.js.useragentoptions.contactname.md) | | string | The user portion of user agent's contact URI. | | [contactParams](./sip.js.useragentoptions.contactparams.md) | | { \[name: string\]: string; } | The URI parameters of the user agent's contact URI. | | [delegate](./sip.js.useragentoptions.delegate.md) | | [UserAgentDelegate](./sip.js.useragentdelegate.md) | Delegate for [UserAgent](./sip.js.useragent.md). | | [displayName](./sip.js.useragentoptions.displayname.md) | | string | The display name associated with the user agent. | | [forceRport](./sip.js.useragentoptions.forcerport.md) | | boolean | Force adding rport to Via header. | +| [gracefulShutdown](./sip.js.useragentoptions.gracefulshutdown.md) | | boolean | If true, the stop() method will attempt to gracefully end all dialogs and registrations before disconnecting. Otherwise stop() will transition immediately abandoning all dialogs and registrations. | | [hackAllowUnregisteredOptionTags](./sip.js.useragentoptions.hackallowunregisteredoptiontags.md) | | boolean | Hack | | [hackIpInContact](./sip.js.useragentoptions.hackipincontact.md) | | boolean \| string | Hack | | [hackViaTcp](./sip.js.useragentoptions.hackviatcp.md) | | boolean | Hack | +| [instanceId](./sip.js.useragentoptions.instanceid.md) | | string | UUID to provide with "+sip.instance" Contact header parameter. | +| [instanceIdAlwaysAdded](./sip.js.useragentoptions.instanceidalwaysadded.md) | | boolean | Add "+sip.instance" Contact header parameter to all requests. | | [logBuiltinEnabled](./sip.js.useragentoptions.logbuiltinenabled.md) | | boolean | Indicates whether log messages should be written to the browser console. | | [logConfiguration](./sip.js.useragentoptions.logconfiguration.md) | | boolean | If true, constructor logs the user agent configuration. | | [logConnector](./sip.js.useragentoptions.logconnector.md) | | [LogConnector](./sip.js.logconnector.md) | A function which will be called every time a log is generated. | diff --git a/docs/compatibility.md b/docs/compatibility.md index 1e77810ea..0ed708a30 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -1,16 +1,16 @@ # Compatibility -SimpleUser, the API framework and core libraries are published... -- as standard ES2017 using standard modules (ES2015) +SimpleUser, SessionManager, the API framework and core libraries are published... +- as standard ES2017 using standard ECMAScript modules - with support for tree shaking and without side effects - but not bundled, not minified, not using .mjs file extensions ## Can you provide an ES5 UMD minified bundle? No. There are a number of build tools available which can transform what's published to whatever single format is needed - for example, Babel and Webpack. -## Is IE11 supported (it's an old web browser)? -No. If you need to make it work in IE, you might try changing the compile target to ES5 and using an ES2017 shim. However only WebRTC based media is currently supported and as IE11 does not support WebRTC you would need to provide a custom `SessionDescriptionHandler`. - ## If I download the source can I change the TypeScript build target? Yes. But note that TypeScript [does not auto-polyfill](https://github.com/microsoft/TypeScript/issues/3101). For example, if the compiled target output is ES5 (the `target` compiler setting) but the libraries require and utilize ES2017 features (as constrained by the `lib` compiler setting), an ES2017 polyfill would be needed to run in an environment which supports ES5 but not ES2017. + +## Is IE11 supported? +No. If you need to make it work in IE, you might try changing the compile target to ES5 and using an ES2017 shim. However only WebRTC based media is currently supported and as IE11 does not support WebRTC you would need to provide a custom `SessionDescriptionHandler`. diff --git a/docs/core/sip.js.contact.md b/docs/core/sip.js.contact.md index 598f38dbb..056448632 100644 --- a/docs/core/sip.js.contact.md +++ b/docs/core/sip.js.contact.md @@ -22,6 +22,6 @@ https://tools.ietf.org/html/rfc3261\#section-8.1.1.8 This is ported from UA.cont | --- | --- | --- | --- | | [pubGruu](./sip.js.contact.pubgruu.md) | | [URI](./sip.js.uri.md) \| undefined | | | [tempGruu](./sip.js.contact.tempgruu.md) | | [URI](./sip.js.uri.md) \| undefined | | -| [toString](./sip.js.contact.tostring.md) | | (options?: { anonymous?: boolean; outbound?: boolean; }) => string | | +| [toString](./sip.js.contact.tostring.md) | | (options?: { anonymous?: boolean; outbound?: boolean; register?: boolean; }) => string | | | [uri](./sip.js.contact.uri.md) | | [URI](./sip.js.uri.md) | | diff --git a/docs/core/sip.js.contact.tostring.md b/docs/core/sip.js.contact.tostring.md index d3047a586..952e7ed6f 100644 --- a/docs/core/sip.js.contact.tostring.md +++ b/docs/core/sip.js.contact.tostring.md @@ -10,5 +10,6 @@ toString: (options?: { anonymous?: boolean; outbound?: boolean; + register?: boolean; }) => string; ``` diff --git a/docs/migration-0.20-0.21.md b/docs/migration-0.20-0.21.md new file mode 100644 index 000000000..868dab7e5 --- /dev/null +++ b/docs/migration-0.20-0.21.md @@ -0,0 +1,67 @@ +# Migration from 0.20.x to 0.21.x + +## General + +First off, the entire project was updated for ECMAScript module (ESM) support. Overall this makes the library more compatible and standard usages of the built library are backwards compatible (for example, if installing it via npm has been working for you it will continue to work). However if you are using a custom build or development process then this change may impact those processes... + + - added .js extensions to all imports + - changed compiler options to NodeNext + - tweaked webpack configs (removed fullySpecified: false) + + +Secondly, the [SimpleUser](./simple-user.md) class has been ported from utilizing the API directly to using the [SessionManager](./session-manager.md) class (which is in turn is utilizing the API directly). The interface and usage of `SimpleUser` is completely identical (well, see below for the one breaking change), but if you were utilizing private methods, private properties, or otherwise depending on the internals of SimpleUser you may have issues. + +Other changes: + - new class `SessionManager` introduced (it's `SimpleUser` for multiple sessions) + - exposed `iceGatheringComplete` method to support strategies other than the built in timeout + - two minor breaking changes (see below) + - minor bug fixes + +## Two minor breaking changes + +### 1. SimpleUser + +The call signature for the `SimpleUser` `register` method has changed. It was... +``` +register(registererOptions?: RegistererOptions, registererRegisterOptions?: RegistererRegisterOptions): Promise; +``` +and is now... +``` +register(registererRegisterOptions?: RegistererRegisterOptions): Promise; +``` +Any `RegistererOptions` which were being passed as the first parameter to the `register` must now be provided to the constructor of `SimpleUser` along with any other options. For example... +``` +const simpleUser = new SimpleUser(myServer, { + registererOptions: { + expires: 1800 + } +}); +``` +This change was made to fix the obviously incorrect call signature so that we did not further extend support for the problematic interface into the newly introduced `SessionManager`. + +### 2. UserAgentOptions + +The `autoStart` and `autoStop` options have been removed. + +- `autoStart` was deprecated a long time ago and was removed to eliminate the side effect in the constructor. +- `autoStop` was removed to eliminate the `UserAgent` dependency a web browser. + +If you want the `autoStart` behavior going forward, you can implement it by calling `start` in your code immediately after construction as follows... + +``` +// Construct the UserAgent +userAgent = new UserAgent(/* options */); + +// Call start +userAgent.start(); +``` + +If you want the `autoStop` behavior going forward, you can implement it by adding a listener to your code as follows... + +``` +// Construct the UserAgent +userAgent = new UserAgent(/* options */); + +// Add a listener to "auto stop" on page unload +window.addEventListener("unload", () => userAgent.stop()); +``` diff --git a/docs/session-description-handler/sip.js.md b/docs/session-description-handler/sip.js.md index e2971213b..e0ffa7581 100644 --- a/docs/session-description-handler/sip.js.md +++ b/docs/session-description-handler/sip.js.md @@ -11,6 +11,7 @@ A SessionDescriptionHandler for web browsers. | Class | Description | | --- | --- | | [SessionDescriptionHandler](./sip.js.sessiondescriptionhandler.md) | A base class implementing a WebRTC session description handler for sip.js. | +| [WebAudioSessionDescriptionHandler](./sip.js.webaudiosessiondescriptionhandler.md) | (BETA) A WebAudioSessionDescriptionHandler uses the Web Audio API to enable local conferencing of audio streams. | ## Functions @@ -19,6 +20,7 @@ A SessionDescriptionHandler for web browsers. | [defaultMediaStreamFactory()](./sip.js.defaultmediastreamfactory.md) | Function which returns a MediaStreamFactory. | | [defaultPeerConnectionConfiguration()](./sip.js.defaultpeerconnectionconfiguration.md) | Function which returns an RTCConfiguration. | | [defaultSessionDescriptionHandlerFactory(mediaStreamFactory)](./sip.js.defaultsessiondescriptionhandlerfactory.md) | Function which returns a SessionDescriptionHandlerFactory. | +| [startLocalConference(conferenceSessions)](./sip.js.startlocalconference.md) | (BETA) Start a conference. | ## Interfaces diff --git a/docs/session-description-handler/sip.js.mediastreamfactory.md b/docs/session-description-handler/sip.js.mediastreamfactory.md index 09ead0fd3..cd898ca7d 100644 --- a/docs/session-description-handler/sip.js.mediastreamfactory.md +++ b/docs/session-description-handler/sip.js.mediastreamfactory.md @@ -9,7 +9,7 @@ Interface of factory function which produces a MediaStream. Signature: ```typescript -export declare type MediaStreamFactory = (constraints: MediaStreamConstraints, sessionDescriptionHandler: SessionDescriptionHandler) => Promise; +export declare type MediaStreamFactory = (constraints: MediaStreamConstraints, sessionDescriptionHandler: SessionDescriptionHandler, options?: SessionDescriptionHandlerOptions) => Promise; ``` -References: [SessionDescriptionHandler](./sip.js.sessiondescriptionhandler.md) +References: [SessionDescriptionHandler](./sip.js.sessiondescriptionhandler.md), [SessionDescriptionHandlerOptions](./sip.js.sessiondescriptionhandleroptions.md) diff --git a/docs/session-description-handler/sip.js.sessiondescriptionhandler.enablereceivertracks.md b/docs/session-description-handler/sip.js.sessiondescriptionhandler.enablereceivertracks.md new file mode 100644 index 000000000..c8643bc22 --- /dev/null +++ b/docs/session-description-handler/sip.js.sessiondescriptionhandler.enablereceivertracks.md @@ -0,0 +1,24 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [SessionDescriptionHandler](./sip.js.sessiondescriptionhandler.md) > [enableReceiverTracks](./sip.js.sessiondescriptionhandler.enablereceivertracks.md) + +## SessionDescriptionHandler.enableReceiverTracks() method + +Helper function to enable/disable media tracks. + +Signature: + +```typescript +enableReceiverTracks(enable: boolean): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| enable | boolean | If true enable tracks, otherwise disable tracks. | + +Returns: + +void + diff --git a/docs/session-description-handler/sip.js.sessiondescriptionhandler.enablesendertracks.md b/docs/session-description-handler/sip.js.sessiondescriptionhandler.enablesendertracks.md new file mode 100644 index 000000000..74127f6d9 --- /dev/null +++ b/docs/session-description-handler/sip.js.sessiondescriptionhandler.enablesendertracks.md @@ -0,0 +1,24 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [SessionDescriptionHandler](./sip.js.sessiondescriptionhandler.md) > [enableSenderTracks](./sip.js.sessiondescriptionhandler.enablesendertracks.md) + +## SessionDescriptionHandler.enableSenderTracks() method + +Helper function to enable/disable media tracks. + +Signature: + +```typescript +enableSenderTracks(enable: boolean): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| enable | boolean | If true enable tracks, otherwise disable tracks. | + +Returns: + +void + diff --git a/docs/session-description-handler/sip.js.sessiondescriptionhandler.icegatheringcomplete.md b/docs/session-description-handler/sip.js.sessiondescriptionhandler.icegatheringcomplete.md index c1f15ff04..63c47f974 100644 --- a/docs/session-description-handler/sip.js.sessiondescriptionhandler.icegatheringcomplete.md +++ b/docs/session-description-handler/sip.js.sessiondescriptionhandler.icegatheringcomplete.md @@ -9,9 +9,13 @@ Called when ICE gathering completes and resolves any waiting promise. Signature: ```typescript -protected iceGatheringComplete(): void; +iceGatheringComplete(): void; ``` Returns: void +## Remarks + +May be called prior to ICE gathering actually completing to allow the session descirption handler proceed with whatever candidates have been gathered up to this point in time. Use this to stop waiting on ICE to complete if you are implementing your own ICE gathering completion strategy. + diff --git a/docs/session-description-handler/sip.js.sessiondescriptionhandler.md b/docs/session-description-handler/sip.js.sessiondescriptionhandler.md index c82251867..9259d36b5 100644 --- a/docs/session-description-handler/sip.js.sessiondescriptionhandler.md +++ b/docs/session-description-handler/sip.js.sessiondescriptionhandler.md @@ -49,6 +49,8 @@ It is expected/intended to be extended by specific WebRTC based applications. | [close()](./sip.js.sessiondescriptionhandler.close.md) | | Stop tracks and close peer connection. | | [createDataChannel(options)](./sip.js.sessiondescriptionhandler.createdatachannel.md) | | Create a data channel. | | [createLocalOfferOrAnswer(options)](./sip.js.sessiondescriptionhandler.createlocalofferoranswer.md) | | Depending on current signaling state, create a local offer or answer. | +| [enableReceiverTracks(enable)](./sip.js.sessiondescriptionhandler.enablereceivertracks.md) | | Helper function to enable/disable media tracks. | +| [enableSenderTracks(enable)](./sip.js.sessiondescriptionhandler.enablesendertracks.md) | | Helper function to enable/disable media tracks. | | [getDescription(options, modifiers)](./sip.js.sessiondescriptionhandler.getdescription.md) | | Creates an offer or answer. | | [getLocalMediaStream(options)](./sip.js.sessiondescriptionhandler.getlocalmediastream.md) | | Get a media stream from the media stream factory and set the local media stream. | | [getLocalSessionDescription()](./sip.js.sessiondescriptionhandler.getlocalsessiondescription.md) | | Gets the peer connection's local session description. | diff --git a/docs/session-description-handler/sip.js.sessiondescriptionhandler.peerconnection.md b/docs/session-description-handler/sip.js.sessiondescriptionhandler.peerconnection.md index d1353e59b..95a91b99a 100644 --- a/docs/session-description-handler/sip.js.sessiondescriptionhandler.peerconnection.md +++ b/docs/session-description-handler/sip.js.sessiondescriptionhandler.peerconnection.md @@ -14,5 +14,23 @@ get peerConnection(): RTCPeerConnection | undefined; ## Remarks -While access to the underlying `RTCPeerConnection` is provided, note that using methods with modify it may break the operation of this class. In particular, this class depends on exclusive access to the event handler properties. If you need access to the peer connection events, either register for events using `addEventListener()` on the `RTCPeerConnection` or set the `peerConnectionDelegate` on this `SessionDescriptionHandler`. +Use the peerConnectionDelegate to get access to the events associated with the RTCPeerConnection. For example... + +Do NOT do this... + +```ts +peerConnection.onicecandidate = (event) => { + // do something +}; +``` +Instead, do this... + +```ts +peerConnection.peerConnectionDelegate = { + onicecandidate: (event) => { + // do something + } +}; +``` +While access to the underlying `RTCPeerConnection` is provided, note that using methods which modify it may break the operation of this class. In particular, this class depends on exclusive access to the event handler properties. If you need access to the peer connection events, either register for events using `addEventListener()` on the `RTCPeerConnection` or set the `peerConnectionDelegate` on this `SessionDescriptionHandler`. diff --git a/docs/session-description-handler/sip.js.sessiondescriptionhandler.peerconnectiondelegate.md b/docs/session-description-handler/sip.js.sessiondescriptionhandler.peerconnectiondelegate.md index 61f0be308..6c0b6a8d7 100644 --- a/docs/session-description-handler/sip.js.sessiondescriptionhandler.peerconnectiondelegate.md +++ b/docs/session-description-handler/sip.js.sessiondescriptionhandler.peerconnectiondelegate.md @@ -16,5 +16,23 @@ set peerConnectionDelegate(delegate: PeerConnectionDelegate | undefined); ## Remarks -Setting the peer connection event handlers directly is not supported and may break this class. As this class depends on exclusive access to them, a delegate may be set which provides alternative access to the event handlers in a fashion which is supported. +Use the peerConnectionDelegate to get access to the events associated with the RTCPeerConnection. For example... + +Do NOT do this... + +```ts +peerConnection.onicecandidate = (event) => { + // do something +}; +``` +Instead, do this... + +``` +peerConnection.peerConnectionDelegate = { + onicecandidate: (event) => { + // do something + } +}; +``` +Setting the peer connection event handlers directly is not supported and may break this class. As this class depends on exclusive access to them. This delegate is intended to provide access to the RTCPeerConnection events in a fashion which is supported. diff --git a/docs/session-description-handler/sip.js.startlocalconference.md b/docs/session-description-handler/sip.js.startlocalconference.md new file mode 100644 index 000000000..4ef25227c --- /dev/null +++ b/docs/session-description-handler/sip.js.startlocalconference.md @@ -0,0 +1,27 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [startLocalConference](./sip.js.startlocalconference.md) + +## startLocalConference() function + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Start a conference. + +Signature: + +```typescript +export declare function startLocalConference(conferenceSessions: Array): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| conferenceSessions | Array<Session> | The sessions to conference. | + +Returns: + +void + diff --git a/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler._constructor_.md b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler._constructor_.md new file mode 100644 index 000000000..fbb5d6771 --- /dev/null +++ b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler._constructor_.md @@ -0,0 +1,25 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [WebAudioSessionDescriptionHandler](./sip.js.webaudiosessiondescriptionhandler.md) > [(constructor)](./sip.js.webaudiosessiondescriptionhandler._constructor_.md) + +## WebAudioSessionDescriptionHandler.(constructor) + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Constructs a new instance of the `WebAudioSessionDescriptionHandler` class + +Signature: + +```typescript +constructor(logger: Logger, mediaStreamFactory: MediaStreamFactory, sessionDescriptionHandlerConfiguration?: SessionDescriptionHandlerConfiguration); +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| logger | Logger | | +| mediaStreamFactory | [MediaStreamFactory](./sip.js.mediastreamfactory.md) | | +| sessionDescriptionHandlerConfiguration | [SessionDescriptionHandlerConfiguration](./sip.js.sessiondescriptionhandlerconfiguration.md) | | + diff --git a/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.audiocontext.md b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.audiocontext.md new file mode 100644 index 000000000..3259bc133 --- /dev/null +++ b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.audiocontext.md @@ -0,0 +1,14 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [WebAudioSessionDescriptionHandler](./sip.js.webaudiosessiondescriptionhandler.md) > [audioContext](./sip.js.webaudiosessiondescriptionhandler.audiocontext.md) + +## WebAudioSessionDescriptionHandler.audioContext property + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Signature: + +```typescript +static audioContext: AudioContext | undefined; +``` diff --git a/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.enablesendertracks.md b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.enablesendertracks.md new file mode 100644 index 000000000..cff7b9249 --- /dev/null +++ b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.enablesendertracks.md @@ -0,0 +1,27 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [WebAudioSessionDescriptionHandler](./sip.js.webaudiosessiondescriptionhandler.md) > [enableSenderTracks](./sip.js.webaudiosessiondescriptionhandler.enablesendertracks.md) + +## WebAudioSessionDescriptionHandler.enableSenderTracks() method + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Helper function to enable/disable media tracks. + +Signature: + +```typescript +enableSenderTracks(enable: boolean): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| enable | boolean | If true enable tracks. | + +Returns: + +void + diff --git a/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.initlocalmediastream.md b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.initlocalmediastream.md new file mode 100644 index 000000000..c817dffe6 --- /dev/null +++ b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.initlocalmediastream.md @@ -0,0 +1,27 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [WebAudioSessionDescriptionHandler](./sip.js.webaudiosessiondescriptionhandler.md) > [initLocalMediaStream](./sip.js.webaudiosessiondescriptionhandler.initlocalmediastream.md) + +## WebAudioSessionDescriptionHandler.initLocalMediaStream() method + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Returns a WebRTC MediaStream proxying the provided audio media stream. This allows additional Web Audio media stream source nodes to be connected to the destination node assoicated with the returned stream so we can mix aditional audio sorces into the local media stream (ie for 3-way conferencing). + +Signature: + +```typescript +initLocalMediaStream(stream: MediaStream): MediaStream; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| stream | MediaStream | The MediaStream to proxy. | + +Returns: + +MediaStream + diff --git a/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.joinwith.md b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.joinwith.md new file mode 100644 index 000000000..819a9a995 --- /dev/null +++ b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.joinwith.md @@ -0,0 +1,27 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [WebAudioSessionDescriptionHandler](./sip.js.webaudiosessiondescriptionhandler.md) > [joinWith](./sip.js.webaudiosessiondescriptionhandler.joinwith.md) + +## WebAudioSessionDescriptionHandler.joinWith() method + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Join (conference) media streams with another party. + +Signature: + +```typescript +joinWith(peer: WebAudioSessionDescriptionHandler): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| peer | [WebAudioSessionDescriptionHandler](./sip.js.webaudiosessiondescriptionhandler.md) | The session description handler of the peer to join with. | + +Returns: + +void + diff --git a/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.md b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.md new file mode 100644 index 000000000..50be33325 --- /dev/null +++ b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.md @@ -0,0 +1,43 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [WebAudioSessionDescriptionHandler](./sip.js.webaudiosessiondescriptionhandler.md) + +## WebAudioSessionDescriptionHandler class + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +A WebAudioSessionDescriptionHandler uses the Web Audio API to enable local conferencing of audio streams. + +Signature: + +```typescript +export declare class WebAudioSessionDescriptionHandler extends SessionDescriptionHandler +``` +Extends: [SessionDescriptionHandler](./sip.js.sessiondescriptionhandler.md) + +## Remarks + +This handler only works for one track of audio per peer connection. While the session description handler being extended supports both audio and video, attempting to utilize video with this handler is not defined. + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(logger, mediaStreamFactory, sessionDescriptionHandlerConfiguration)](./sip.js.webaudiosessiondescriptionhandler._constructor_.md) | | (BETA) Constructs a new instance of the WebAudioSessionDescriptionHandler class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [audioContext](./sip.js.webaudiosessiondescriptionhandler.audiocontext.md) | static | AudioContext \| undefined | (BETA) | + +## Methods + +| Method | Modifiers | Description | +| --- | --- | --- | +| [enableSenderTracks(enable)](./sip.js.webaudiosessiondescriptionhandler.enablesendertracks.md) | | (BETA) Helper function to enable/disable media tracks. | +| [initLocalMediaStream(stream)](./sip.js.webaudiosessiondescriptionhandler.initlocalmediastream.md) | | (BETA) Returns a WebRTC MediaStream proxying the provided audio media stream. This allows additional Web Audio media stream source nodes to be connected to the destination node assoicated with the returned stream so we can mix aditional audio sorces into the local media stream (ie for 3-way conferencing). | +| [joinWith(peer)](./sip.js.webaudiosessiondescriptionhandler.joinwith.md) | | (BETA) Join (conference) media streams with another party. | +| [setRealLocalMediaStream(stream)](./sip.js.webaudiosessiondescriptionhandler.setreallocalmediastream.md) | | (BETA) Sets the original local media stream. | + diff --git a/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.setreallocalmediastream.md b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.setreallocalmediastream.md new file mode 100644 index 000000000..6739535a8 --- /dev/null +++ b/docs/session-description-handler/sip.js.webaudiosessiondescriptionhandler.setreallocalmediastream.md @@ -0,0 +1,31 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [WebAudioSessionDescriptionHandler](./sip.js.webaudiosessiondescriptionhandler.md) > [setRealLocalMediaStream](./sip.js.webaudiosessiondescriptionhandler.setreallocalmediastream.md) + +## WebAudioSessionDescriptionHandler.setRealLocalMediaStream() method + +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Sets the original local media stream. + +Signature: + +```typescript +setRealLocalMediaStream(stream: MediaStream): void; +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| stream | MediaStream | Media stream containing tracks to be utilized. | + +Returns: + +void + +## Remarks + +Only the first audio and video tracks of the provided MediaStream are utilized. Adds tracks if audio and/or video tracks are not already present, otherwise replaces tracks. + diff --git a/docs/session-manager.md b/docs/session-manager.md new file mode 100644 index 000000000..a7bec72f0 --- /dev/null +++ b/docs/session-manager.md @@ -0,0 +1,26 @@ +# SessionManager + +## Overview + +The `SessionManager` class provides an easy simplified interface for making audio and video calls in a web page. + +While not intended for all use cases, `SessionManager` is intended to be suitable for many single page web browser applications. + +If requirements are more advanced, working directly with the [API](./api.md) which `SessionManager` is built on top of provides more flexiblity. + +## Reference Documentation + +* [SessionManager Class Reference](./session-manager/sip.js.md) + +## Getting Started + +The interface provdied by `SessionManager` supports multiple concurrent calls, but otherwise generally mirrors the interface provided by `SimpleUser`. + +1. Start with [SimpleUser](./simple-user.md). +2. If `SimpleUser` suffices, then stop. +3. If `SimpleUser` would suffice if only it handled concurrent calls, then `SessionManager` may be for you. +4. If `SimpleUser` does not suffice for the single call case and/or `SessionManager` does not suffice for the multiple concurrent call case, then you may need to utilize the [API](./api.md) direclty. + +## Example + +The `SimpleUser` class source code provides a working example of how one might utilize the `SessionManager` class. diff --git a/docs/session-manager/sip.js.sessionmanager.isheld.md b/docs/session-manager/sip.js.sessionmanager.isheld.md index c78e990ac..c43675bd4 100644 --- a/docs/session-manager/sip.js.sessionmanager.isheld.md +++ b/docs/session-manager/sip.js.sessionmanager.isheld.md @@ -9,7 +9,7 @@ Hold state. Signature: ```typescript -isHeld(session: Session): boolean | undefined; +isHeld(session: Session): boolean; ``` ## Parameters @@ -20,9 +20,9 @@ isHeld(session: Session): boolean | undefined; Returns: -boolean \| undefined +boolean ## Remarks -True if session media is on hold. Undefined is session doesn't exist. +True if session is on hold. diff --git a/docs/session-manager/sip.js.sessionmanager.ismuted.md b/docs/session-manager/sip.js.sessionmanager.ismuted.md index 6a1846bc6..50952caa3 100644 --- a/docs/session-manager/sip.js.sessionmanager.ismuted.md +++ b/docs/session-manager/sip.js.sessionmanager.ismuted.md @@ -9,7 +9,7 @@ Mute state. Signature: ```typescript -isMuted(session: Session): boolean | undefined; +isMuted(session: Session): boolean; ``` ## Parameters @@ -20,9 +20,9 @@ isMuted(session: Session): boolean | undefined; Returns: -boolean \| undefined +boolean ## Remarks -True if sender's media track is disabled. Undefined is session doesn't exist. +True if sender's media track is disabled. diff --git a/docs/simple-user.md b/docs/simple-user.md index d95deb38d..81a419218 100644 --- a/docs/simple-user.md +++ b/docs/simple-user.md @@ -6,7 +6,9 @@ The `SimpleUser` class provides an easy simplified interface for making audio an While not intended for all use cases, `SimpleUser` is intended to be suitable for many single page web browser applications. For instance, the examples on the [Demo](../demo/README.md) page are implemented using the `SimpleUser` class exclusively. Furthermore, the [Demo](../demo/README.md) source code provides concrete examples of how to use all the features provided by `SimpleUser`. -If requirements are more advanced, working directly with the [API](./api.md) which `SimpleUser` is built on top of provides more flexiblity. +If requirements are more advanced, working directly with the [SessionManager](./session-manager.md) which `SimpleUser` is built on top of provides more flexiblity and supports multiple concurrent calls. + +If requirements are still more advanced, working directly with the [API](./api.md) which `SessionManager` is built on top of provides more flexiblity. ## Reference Documentation diff --git a/docs/simple-user/sip.js.simpleuser.decline.md b/docs/simple-user/sip.js.simpleuser.decline.md index 5dc4cb03b..4f7b0e779 100644 --- a/docs/simple-user/sip.js.simpleuser.decline.md +++ b/docs/simple-user/sip.js.simpleuser.decline.md @@ -17,5 +17,5 @@ Promise<void> ## Remarks -Reject an incoming INVITE request. Resolves with the response is sent, otherwise rejects. Use `onCallTerminated` delegate method to determine if and when call is ended. +Reject an incoming INVITE request. Resolves with the response is sent, otherwise rejects. Use `onCallHangup` delegate method to determine if and when call is ended. diff --git a/docs/simple-user/sip.js.simpleuser.hangup.md b/docs/simple-user/sip.js.simpleuser.hangup.md index 8b3eb0860..4222a0c79 100644 --- a/docs/simple-user/sip.js.simpleuser.hangup.md +++ b/docs/simple-user/sip.js.simpleuser.hangup.md @@ -17,5 +17,5 @@ Promise<void> ## Remarks -Send a BYE request, CANCEL request or reject response to end the current Session. Resolves when the request/response is sent, otherwise rejects. Use `onCallTerminated` delegate method to determine if and when call is ended. +Send a BYE request, CANCEL request or reject response to end the current Session. Resolves when the request/response is sent, otherwise rejects. Use `onCallHangup` delegate method to determine if and when call is ended. diff --git a/docs/simple-user/sip.js.simpleuser.isheld.md b/docs/simple-user/sip.js.simpleuser.isheld.md index 6231ddcb5..c548e7d8a 100644 --- a/docs/simple-user/sip.js.simpleuser.isheld.md +++ b/docs/simple-user/sip.js.simpleuser.isheld.md @@ -17,5 +17,5 @@ boolean ## Remarks -True if session media is on hold. +True if session is on hold. diff --git a/docs/simple-user/sip.js.simpleuser.md b/docs/simple-user/sip.js.simpleuser.md index 54b288883..f0e283052 100644 --- a/docs/simple-user/sip.js.simpleuser.md +++ b/docs/simple-user/sip.js.simpleuser.md @@ -50,7 +50,7 @@ While this class is completely functional for simple use cases, it is not intend | [isMuted()](./sip.js.simpleuser.ismuted.md) | | Mute state. | | [message(destination, message)](./sip.js.simpleuser.message.md) | | Send a message. | | [mute()](./sip.js.simpleuser.mute.md) | | Mute call. | -| [register(registererOptions, registererRegisterOptions)](./sip.js.simpleuser.register.md) | | Start receiving incoming calls. | +| [register(registererRegisterOptions)](./sip.js.simpleuser.register.md) | | Start receiving incoming calls. | | [sendDTMF(tone)](./sip.js.simpleuser.senddtmf.md) | | Send DTMF. | | [unhold()](./sip.js.simpleuser.unhold.md) | | Unhold call. | | [unmute()](./sip.js.simpleuser.unmute.md) | | Unmute call. | diff --git a/docs/simple-user/sip.js.simpleuser.register.md b/docs/simple-user/sip.js.simpleuser.register.md index 6b4419dc8..e0a44858a 100644 --- a/docs/simple-user/sip.js.simpleuser.register.md +++ b/docs/simple-user/sip.js.simpleuser.register.md @@ -9,14 +9,13 @@ Start receiving incoming calls. Signature: ```typescript -register(registererOptions?: RegistererOptions, registererRegisterOptions?: RegistererRegisterOptions): Promise; +register(registererRegisterOptions?: RegistererRegisterOptions): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| registererOptions | RegistererOptions | | | registererRegisterOptions | RegistererRegisterOptions | | Returns: diff --git a/docs/simple-user/sip.js.simpleuseroptions.md b/docs/simple-user/sip.js.simpleuseroptions.md index 281c1c030..76679c6be 100644 --- a/docs/simple-user/sip.js.simpleuseroptions.md +++ b/docs/simple-user/sip.js.simpleuseroptions.md @@ -21,5 +21,6 @@ export interface SimpleUserOptions | [media](./sip.js.simpleuseroptions.media.md) | | [SimpleUserMedia](./sip.js.simpleusermedia.md) | Media options. | | [reconnectionAttempts](./sip.js.simpleuseroptions.reconnectionattempts.md) | | number | Maximum number of times to attempt to reconnection. | | [reconnectionDelay](./sip.js.simpleuseroptions.reconnectiondelay.md) | | number | Seconds to wait between reconnection attempts. | +| [registererOptions](./sip.js.simpleuseroptions.registereroptions.md) | | RegistererOptions | Options for Registerer. | | [userAgentOptions](./sip.js.simpleuseroptions.useragentoptions.md) | | UserAgentOptions | Options for UserAgent. | diff --git a/docs/simple-user/sip.js.simpleuseroptions.registereroptions.md b/docs/simple-user/sip.js.simpleuseroptions.registereroptions.md new file mode 100644 index 000000000..6d0eff612 --- /dev/null +++ b/docs/simple-user/sip.js.simpleuseroptions.registereroptions.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [sip.js](./sip.js.md) > [SimpleUserOptions](./sip.js.simpleuseroptions.md) > [registererOptions](./sip.js.simpleuseroptions.registereroptions.md) + +## SimpleUserOptions.registererOptions property + +Options for Registerer. + +Signature: + +```typescript +registererOptions?: RegistererOptions; +``` diff --git a/etc/api/sip.js.api.md b/etc/api/sip.js.api.md index 2d5aafd87..8a6a884bf 100644 --- a/etc/api/sip.js.api.md +++ b/etc/api/sip.js.api.md @@ -32,6 +32,13 @@ export class Bye { get request(): IncomingRequestMessage; } +// @public +export class Cancel { + // @internal + constructor(incomingCancelRequest: IncomingRequestMessage); + get request(): IncomingRequestMessage; +} + // Warning: (ae-forgotten-export) The symbol "Exception" needs to be exported by the entry point index.d.ts // // @public @@ -349,6 +356,7 @@ export interface RegistererOptions { expires?: number; extraContactHeaderParams?: Array; extraHeaders?: Array; + // @deprecated instanceId?: string; logConfiguration?: boolean; // @deprecated (undocumented) @@ -528,6 +536,7 @@ export interface SessionByeOptions { export interface SessionDelegate { onAck?(ack: Ack): void; onBye?(bye: Bye): void; + onCancel?(cancel: Cancel): void; onInfo?(info: Info): void; onInvite?(request: IncomingRequestMessage, response: string, statusCode: number): void; onMessage?(message: Message): void; @@ -758,6 +767,7 @@ export class UserAgent { getLogger(category: string, label?: string): Logger; // Warning: (ae-forgotten-export) The symbol "LoggerFactory" needs to be exported by the entry point index.d.ts getLoggerFactory(): LoggerFactory; + get instanceId(): string; isConnected(): boolean; // @internal _makeInviter(targetURI: URI, options?: InviterOptions): Inviter; @@ -819,9 +829,6 @@ export interface UserAgentOptions { authorizationHa1?: string; authorizationPassword?: string; authorizationUsername?: string; - // @deprecated (undocumented) - autoStart?: boolean; - autoStop?: boolean; contactName?: string; contactParams?: { [name: string]: string; @@ -829,12 +836,15 @@ export interface UserAgentOptions { delegate?: UserAgentDelegate; displayName?: string; forceRport?: boolean; + gracefulShutdown?: boolean; // @deprecated hackAllowUnregisteredOptionTags?: boolean; // @deprecated hackIpInContact?: boolean | string; // @deprecated hackViaTcp?: boolean; + instanceId?: string; + instanceIdAlwaysAdded?: boolean; logBuiltinEnabled?: boolean; logConfiguration?: boolean; logConnector?: LogConnector; diff --git a/etc/core/sip.js.api.md b/etc/core/sip.js.api.md index dd1e4456a..b2715fc7c 100644 --- a/etc/core/sip.js.api.md +++ b/etc/core/sip.js.api.md @@ -97,6 +97,7 @@ export interface Contact { toString: (options?: { anonymous?: boolean; outbound?: boolean; + register?: boolean; }) => string; // (undocumented) uri: URI; diff --git a/etc/session-description-handler/sip.js.api.md b/etc/session-description-handler/sip.js.api.md index 85bbcd0f9..a72e48995 100644 --- a/etc/session-description-handler/sip.js.api.md +++ b/etc/session-description-handler/sip.js.api.md @@ -14,7 +14,7 @@ export function defaultPeerConnectionConfiguration(): RTCConfiguration; export function defaultSessionDescriptionHandlerFactory(mediaStreamFactory?: (constraints: MediaStreamConstraints, sessionDescriptionHandler: SessionDescriptionHandler) => Promise): SessionDescriptionHandlerFactory; // @public -export type MediaStreamFactory = (constraints: MediaStreamConstraints, sessionDescriptionHandler: SessionDescriptionHandler) => Promise; +export type MediaStreamFactory = (constraints: MediaStreamConstraints, sessionDescriptionHandler: SessionDescriptionHandler, options?: SessionDescriptionHandlerOptions) => Promise; // @public export interface PeerConnectionDelegate { @@ -40,13 +40,15 @@ export class SessionDescriptionHandler implements SessionDescriptionHandler_2 { protected createLocalOfferOrAnswer(options?: SessionDescriptionHandlerOptions): Promise; get dataChannel(): RTCDataChannel | undefined; protected _dataChannel: RTCDataChannel | undefined; + enableReceiverTracks(enable: boolean): void; + enableSenderTracks(enable: boolean): void; // Warning: (ae-forgotten-export) The symbol "SessionDescriptionHandlerModifier" needs to be exported by the entry point index.d.ts // Warning: (ae-forgotten-export) The symbol "BodyAndContentType" needs to be exported by the entry point index.d.ts getDescription(options?: SessionDescriptionHandlerOptions, modifiers?: Array): Promise; protected getLocalMediaStream(options?: SessionDescriptionHandlerOptions): Promise; protected getLocalSessionDescription(): Promise; hasDescription(contentType: string): boolean; - protected iceGatheringComplete(): void; + iceGatheringComplete(): void; get localMediaStream(): MediaStream; protected _localMediaStream: MediaStream; // Warning: (ae-forgotten-export) The symbol "Logger" needs to be exported by the entry point index.d.ts @@ -105,5 +107,19 @@ export interface SessionDescriptionHandlerOptions extends SessionDescriptionHand onDataChannel?: (dataChannel: RTCDataChannel) => void; } +// @beta +export function startLocalConference(conferenceSessions: Array): void; + +// @beta +export class WebAudioSessionDescriptionHandler extends SessionDescriptionHandler { + constructor(logger: Logger, mediaStreamFactory: MediaStreamFactory, sessionDescriptionHandlerConfiguration?: SessionDescriptionHandlerConfiguration); + // (undocumented) + static audioContext: AudioContext | undefined; + enableSenderTracks(enable: boolean): void; + initLocalMediaStream(stream: MediaStream): MediaStream; + joinWith(peer: WebAudioSessionDescriptionHandler): void; + setRealLocalMediaStream(stream: MediaStream): void; +} + ``` diff --git a/etc/session-manager/sip.js.api.md b/etc/session-manager/sip.js.api.md index 66f50d174..154c8daca 100644 --- a/etc/session-manager/sip.js.api.md +++ b/etc/session-manager/sip.js.api.md @@ -54,8 +54,8 @@ export class SessionManager { hangup(session: Session): Promise; hold(session: Session): Promise; isConnected(): boolean; - isHeld(session: Session): boolean | undefined; - isMuted(session: Session): boolean | undefined; + isHeld(session: Session): boolean; + isMuted(session: Session): boolean; managedSessions: Array; message(destination: string, message: string): Promise; mute(session: Session): void; diff --git a/etc/simple-user/sip.js.api.md b/etc/simple-user/sip.js.api.md index 856d83a64..81b4da66f 100644 --- a/etc/simple-user/sip.js.api.md +++ b/etc/simple-user/sip.js.api.md @@ -30,9 +30,8 @@ export class SimpleUser { get localVideoTrack(): MediaStreamTrack | undefined; message(destination: string, message: string): Promise; mute(): void; - // Warning: (ae-forgotten-export) The symbol "RegistererOptions" needs to be exported by the entry point index.d.ts // Warning: (ae-forgotten-export) The symbol "RegistererRegisterOptions" needs to be exported by the entry point index.d.ts - register(registererOptions?: RegistererOptions, registererRegisterOptions?: RegistererRegisterOptions): Promise; + register(registererRegisterOptions?: RegistererRegisterOptions): Promise; // @deprecated get remoteAudioTrack(): MediaStreamTrack | undefined; get remoteMediaStream(): MediaStream | undefined; @@ -43,7 +42,7 @@ export class SimpleUser { unmute(): void; // Warning: (ae-forgotten-export) The symbol "RegistererUnregisterOptions" needs to be exported by the entry point index.d.ts unregister(registererUnregisterOptions?: RegistererUnregisterOptions): Promise; - } +} // @public export interface SimpleUserDelegate { @@ -91,6 +90,8 @@ export interface SimpleUserOptions { media?: SimpleUserMedia; reconnectionAttempts?: number; reconnectionDelay?: number; + // Warning: (ae-forgotten-export) The symbol "RegistererOptions" needs to be exported by the entry point index.d.ts + registererOptions?: RegistererOptions; // Warning: (ae-forgotten-export) The symbol "UserAgentOptions" needs to be exported by the entry point index.d.ts userAgentOptions?: UserAgentOptions; }