The PresenceService is the main entry point into Convergence's User Presence subsystem. User Presence tracks the availability and state of Domain Users within the System. Users are generally available or not if they have at least one session that is connected. Each user in the system can set presence state. Presence state is global for each user in that the state is shared across all sessions.

See the developer guide for additional background.

See PresenceServiceEvents for the events that may be emitted on this service.

### Hierarchy

- ConvergenceEventEmitter<IPresenceEvent>
  - PresenceService

## Index

### Methods

- addListener
- clearState
- events
- isAvailable
- off
- on
- once
- presence
- removeAllListeners
- removeListener
- removeListeners
- removeState
- session
- setState
- state
- subscribe

### Object literals

- Events

## Methods

### addListener

- addListener(event: string, listener: ConvergenceEventListener<IPresenceEvent>): ConvergenceEventEmitter<IPresenceEvent>

- Inherited from ConvergenceEventEmitter.addListener

  Adds a new event listener for the specified event. The class will ignore duplicate registrations of the same listener to the same event.

  #### Parameters

  - ##### event: string

    The name of the event to add the listener for.

  - ##### listener: ConvergenceEventListener<IPresenceEvent>

    The listener callback to register.

  #### Returns ConvergenceEventEmitter<IPresenceEvent>

  This object, in support of a fluent API.

### clearState

- clearState(): void

- Deletes all items in the local user's presence state.

  #### Returns void

### events

- events(): Observable<IPresenceEvent>

- Inherited from ConvergenceEventEmitter.events

  Provides the events emitted by this object as an Observable stream.

  example

        eventEmitter.events()
          .filter(e => e.name === "myevent")
          .subscribe(e => console.log(e));

  #### Returns Observable<IPresenceEvent>

  An Observable stream of all events emitted by this object.

### isAvailable

- isAvailable(): boolean

- Determines if the local user is available.

  #### Returns boolean

  True if the local user is available, false otherwise.

### off

- off(event: string, listener: ConvergenceEventListener<IPresenceEvent>): ConvergenceEventEmitter<IPresenceEvent>

- Inherited from ConvergenceEventEmitter.off

  Removes a single event listener for a specific event.

  #### Parameters

  - ##### event: string

    The name of the event to remove the listener for.

  - ##### listener: ConvergenceEventListener<IPresenceEvent>

    The listener callback to unregister.

  #### Returns ConvergenceEventEmitter<IPresenceEvent>

  This object, in support of a fluent API.

### on

- on(event: string, listener: ConvergenceEventListener<IPresenceEvent>): ConvergenceEventEmitter<IPresenceEvent>

- Inherited from ConvergenceEventEmitter.on

  Adds a new event listener for the specified event. The class will ignore duplicate registrations of the same listener to the same event.

  #### Parameters

  - ##### event: string

    The name of the event to add the listener for.

  - ##### listener: ConvergenceEventListener<IPresenceEvent>

    The listener callback to register.

  #### Returns ConvergenceEventEmitter<IPresenceEvent>

  This object, in support of a fluent API.

### once

- once(event: string, listener: ConvergenceEventListener<IPresenceEvent>): ConvergenceEventEmitter<IPresenceEvent>

- Inherited from ConvergenceEventEmitter.once

  Adds a single shot event listener for the specified event. The listener will be called the first time the specified event is fired after the event registration occurs, after which the registration will be removed and no further events will be passed to the listener.

  #### Parameters

  - ##### event: string

    The name of the event to add the listener for.

  - ##### listener: ConvergenceEventListener<IPresenceEvent>

    The listener callback to register.

  #### Returns ConvergenceEventEmitter<IPresenceEvent>

  This object, in support of a fluent API.

### presence

- presence(user: DomainUserIdentifier): Promise<UserPresence>
- presence(users: DomainUserIdentifier[]): Promise<UserPresence[]>

- Returns the given user's current presence.

  #### Parameters

  - ##### user: DomainUserIdentifier

    a username or DomainUserId

  #### Returns Promise<UserPresence>

  a promise that resolves with the give user's presence

- Returns the current presence of all the provided users.

  #### Parameters

  - ##### users: DomainUserIdentifier[]

  #### Returns Promise<UserPresence[]>

  a promise that resolves with the give users' presences

### removeAllListeners

- removeAllListeners(): ConvergenceEventEmitter<IPresenceEvent>

- Inherited from ConvergenceEventEmitter.removeAllListeners

  Removes all listeners for all events. This is useful for cleanup before disposing of this particular event emitter.

  #### Returns ConvergenceEventEmitter<IPresenceEvent>

  This object, in support of a fluent API.

### removeListener

- removeListener(event: string, listener: ConvergenceEventListener<IPresenceEvent>): ConvergenceEventEmitter<IPresenceEvent>

- Inherited from ConvergenceEventEmitter.removeListener

  Removes a single event listener for a specific event.

  #### Parameters

  - ##### event: string

    The name of the event to remove the listener for.

  - ##### listener: ConvergenceEventListener<IPresenceEvent>

    The listener callback to unregister.

  #### Returns ConvergenceEventEmitter<IPresenceEvent>

  This object, in support of a fluent API.

### removeListeners

- removeListeners(event: string): ConvergenceEventEmitter<IPresenceEvent>

- Inherited from ConvergenceEventEmitter.removeListeners

  Removes all listeners bound on the given event.

  #### Parameters

  - ##### event: string

    the name of the event to remove listeners for

  #### Returns ConvergenceEventEmitter<IPresenceEvent>

  This object, in support of a fluent API.

### removeState

- removeState(key: string): void
- removeState(keys: string[]): void

- Removes the key-value pair of the provided key on the local user's presence state.

  #### Parameters

  - ##### key: string

    an existing key in the local user's presence state

  #### Returns void

- Removes all the entries in the local user's presence state matching the provided array of keys.

  #### Parameters

  - ##### keys: string[]

    an array of keys

  #### Returns void

### session

- session(): ConvergenceSession

- #### Returns ConvergenceSession

  The session that this client is connected with.

### setState

- setState(state: StringMapLike): void
- setState(key: string, value: any): void

- Sets the given items on the local user's presence state.

  #### Parameters

  - ##### state: StringMapLike

    a `Map` or object literal whose keys are `String`s.

  #### Returns void

- Sets a single key-value pair on the local user's presence state.

  #### Parameters

  - ##### key: string

    the new pair's key

  - ##### value: any

    the new pair's value

  #### Returns void

### state

- state(): Map<string, any>

- Returns a `Map` representing the local user's presence state.

  #### Returns Map<string, any>

  a `Map` of the local user's presence state

### subscribe

- subscribe(user: DomainUserIdentifier): Promise<UserPresenceSubscription>
- subscribe(users: DomainUserIdentifier[]): Promise<UserPresenceSubscription[]>

- Returns a UserPresenceSubscription linked to the provided user. From this object, consumers can get the current presence and listen to changes on the user's presence state or availability.

  Make sure to UserPresenceSubscription.unsubscribe when you're done with the returned subscription.

  #### Parameters

  - ##### user: DomainUserIdentifier

    a username or DomainUserId

  #### Returns Promise<UserPresenceSubscription>

  a promise that resolves with a subscription to the given user's presence changes

- Returns an array of UserPresenceSubscriptions corresponding to the provided users. From these objects, consumers can get the current presence and listen to changes on the user's presence state or availability.

  Make sure to UserPresenceSubscription.unsubscribe when you're done with the returned subscriptions.

  #### Parameters

  - ##### users: DomainUserIdentifier[]

  #### Returns Promise<UserPresenceSubscription[]>

  a promise that resolves with an array of subscriptions to the given users' presence changes

## Object literals

### StaticEvents

Events: object

A mapping of the events this service could emit to each event's unique name. Use this to refer an event name:

    presenceService.on(PresenceService.Events.STATE_SET, function listener(e) {
      // ...
    })

### AVAILABILITY_CHANGED

AVAILABILITY_CHANGED: string = PresenceAvailabilityChangedEvent.NAME

### STATE_CLEARED

STATE_CLEARED: string = PresenceStateClearedEvent.NAME

### STATE_REMOVED

STATE_REMOVED: string = PresenceStateRemovedEvent.NAME

### STATE_SET

STATE_SET: string = PresenceStateSetEvent.NAME