## Properties

onConnect
onDisconnect

onError
onProjectInfo

onStateChanged

## Methods

beginSubscription()
connect([_reconnect])
destroy()
disconnect()
endSubscription()
getCameraArchive(key[, subscriptionCallback])
getCameraPicture(key)

getCommunicationObject(key[, subscriptionCallback])
getDataArchive(key[, subscriptionCallback])
getMessageArchive(key[, subscriptionCallback])
getProjectId()
getReconnect()
getReconnectInterval()
getScene(key[, subscriptionCallback])

getSequence(key[, subscriptionCallback])
getState()
getUniversalTimer(key[, subscriptionCallback])
getVacationCalendar(key[, subscriptionCallback])
reset()
select(options[, Callback])
setReconnectInterval([interval])

## Abstract types

getCameraArchiveCallback(err, data)
getCommunicationObjectCallback(err, data, isInit)
getDataArchiveCallback(err, data)
getMessageArchiveCallback(err, data)
getSceneCallback(err, data)

getSequenceCallback(err, data)
getUniversalTimerCallback(err, data)
getVacationCalendarCallback(err, data)
onConnectCallback()
onDisconnectCallback(cause)

onErrorCallback(err)
onProjectInfoCallback(projectID)
onStateChangedCallback(oldState, newState[, error])
selectCallback(err, result, context)

## new _Connection()

Maps a connection to the HomeServer.
May not be directly instanced. An instance of the class is created by the method createConnection().

### Example

Call of the 'createConnection()' method.

    var conn = HomeServerConnector.createConnection("user1", "pw1", {"hostname": "192.168.123.234", "port": 443, "protocol": "wss"});

## Properties

### onConnect HomeServerConnector._Connection~onConnectCallback

The callback method assigned here is called as soon as a connection has been established.

#### Example

Connection was established

    function myConnectResponse() {
      ...
    }
    ...
    conn.onConnect = myConnectResponse;

### onDisconnect HomeServerConnector._Connection~onDisconnectCallback

The callback function assigned here is called as soon as there is no longer a connection.

#### Example

Connection terminated

    function myDisconnectResponse(cause) {
      ...
    }
    ...
    conn.onDisconnect = myDisonnectResponse;

### onError HomeServerConnector._Connection~onErrorCallback

The callback function assigned here is called when an error occurs.

#### Example

Error occurs

    function myErrorResponse(error) {
      ...
    }
    ...
    conn.onError = myErrorResponse;

### onProjectInfo HomeServerConnector._Connection~onProjectInfoCallback

The callback function assigned here is called when the information is available.

#### Example

    conn.onProjectInfo = function(projectID) {};

### onStateChanged HomeServerConnector._Connection~onStateChangedCallback

The callback function assigned here is called when the status of the current connection changes.

#### Example

Connection status has changed

    function myStChgResponse(oldState, newState, error) {
      ...
    }
    ...
    conn.onStateChanged = myStChgResponse;

## Methods

### beginSubscription()

Initiation of a transaction to perform several subscriptions at the same time.
To optimise communication between the client and the HS, several subscriptions can be combined into one transaction. The client must then communicate with the HS only once instead of carrying out the procedure for each subscription separately.
The transaction is initiated with this method.
To end the transaction, endSubscription() is called.

#### Example

Subscription to 4 communication objects and one data archive in one transaction.

    conn.beginSubscription():
    var ko_1 = conn.getCommunicationObject("CO@1_1_1", function(err, value, isInit) {});
    var ko_2 = conn.getCommunicationObject("CO@MyCoNo2", function(err, value, isInit) {});
    var ko_3 = conn.getCommunicationObject("CO@TEST_CO_3", function(err, value, isInit) {});
    var ko_4 = conn.getCommunicationObject("CO:31", function(err, value, isInit) {});
    var arch = conn.getDataArchive("DA@MyDataArchive", function(err, data) {});
    conn.endSubscription():

### connect([_reconnect]) → Boolean

Establishment of connection is initiated.
An attempt to establish a connection is started immediately if a connection does not already exist.

#### Example

Attempts to connect to the HomeServer. Reconnection should be attempted if the connection is lost

    var conn = HomeServerConnector.createConnection("user1", "pw1");
    conn.connect(true);

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
_reconnect | Boolean | Yes | true: If the connection is lost, a reconnection attempt is initiated after the Reconnect-Intervall . false: If the connection is lost,no new connection attempt is initiated. Defaults to `true`.

Returns

  `Boolean` true: An attempt to establish a connection was initiated.
  false: An attempt to set up a connection could not be initiated as a connection attempt was already initiated or a connection already exists.

### destroy()

All events and references will be resolved. The WebSocket will be closed.
After this method has been called this instance can no longer be used.

#### Example

    conn.destroy();

### disconnect() → Boolean

Disconnection is initiated.

#### Example

    conn.disconnect();

Returns

  `Boolean` true: Disconnection was initiated.
  false: There is no connection.

### endSubscription()

Termination of a subscription transaction.
The mode of operation is explained in the section on the method for initiating the transaction: beginSubscription().

### getCameraArchive(key[, subscriptionCallback]) → HomeServerConnector._CameraArchive

Returns an instance of a camera archive.

#### Example

    var ca = conn.getCameraArchive("CA@MyCameraArchive", function(err, data) {});

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
key | String |  | Key of camera archive
subscriptionCallback | function() | Yes | The Callback-Methode is called on subscription and on addition of a new entry.

Returns

  `HomeServerConnector._CameraArchive`

### getCameraPicture(key) → HomeServerConnector._CameraPicture

Returns a camera image.

#### Example

    var cp = conn.getCameraPicture("CP@MyCamera");

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
key | String |  | Key of camera

Returns

  `HomeServerConnector._CameraPicture`

### getCommunicationObject(key[, subscriptionCallback]) → HomeServerConnector._CommunicationObject

Returns an instance of a communication object (CO)

#### Example

    var co = conn.getCommunicationObject("CO@1_1_1", function(err, value, isInit) {});

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
key | String |  | Key of the communication object.
subscriptionCallback | function() | Yes | The Callback-Methode is called on subscription and on the change of value of the communication object.

Returns

  `HomeServerConnector._CommunicationObject`

### getDataArchive(key[, subscriptionCallback]) → HomeServerConnector._DataArchive

Returns an instance of a data archive.

#### Example

    var da = conn.getDataArchive("DA@MyDataArchive", function(err, data) {});

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
key | String |  | Key of the data archive.
subscriptionCallback | function() | Yes | The Callback-Methode is called on subscription and on addition of a new entry.

Returns

  `HomeServerConnector._DataArchive`

### getMessageArchive(key[, subscriptionCallback]) → HomeServerConnector._MessageArchive

Returns an instance of a message archive.

#### Example

    var ma = conn.getMessageArchive("MA@MyMessageArchive", function(err, data) {});

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
key | String |  | Key of the message archive.
subscriptionCallback | function() | Yes | The Callback-Methode is called on subscription and on addition of a new entry.

Returns

  `HomeServerConnector._MessageArchive`

### getProjectId() → (String or Undefined)

Project ID. Is only available as soon as there is a connection to the HomeServer.

#### Example

Query project ID

    var conn = HomeServerConnector.createConnection("user1", "pw1");
    ...
    var pid = conn.getProjectId()

Returns

  `(String or Undefined)` Project ID of the HomeServer project.

### getReconnect() → Boolean

Provides the information whether a reconnection attempt should be made if the connection is lost.
This information can be set in the connect() method.

#### Example

Query reconnect status

    var conn = HomeServerConnector.createConnection("user1", "pw1");
    ...
    rc = conn.getReconnect()

Returns

  `Boolean` true: If the connection is aborted, new attempts to connect should be made.

### getReconnectInterval() → Number

Query reconnect attempt interval. Specification in seconds.

#### Example

Returns the interval in which attempts to reconnect are made if the connection was interrupted.

    var conn = HomeServerConnector.createConnection("user1", "pw1");
    ...
    ri = conn.getReconnectInterval();

Returns

  `Number` Interval (in seconds) in which new attempts to connect are made.

### getScene(key[, subscriptionCallback]) → HomeServerConnector._Scene

Returns an instance of a scene.

#### Example

    var sc = conn.getScene("SC@MyScene", function(err, data) {});

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
key | String |  | Key of the scene
subscriptionCallback | function() | Yes | The Callback-Methode is called on subscription and on learning a scene.

Returns

  `HomeServerConnector._Scene`

### getSequence(key[, subscriptionCallback]) → HomeServerConnector._Sequence

Returns an instance of a sequence.

#### Example

    var sq = conn.getSequence("SQ@MySequence", function(err, data) {});

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
key | String |  | Key of the sequence
subscriptionCallback | function() | Yes | The Callback-Methode is called on subscription, on starting, stopping of the sequence or while the sequence is running.

Returns

  `HomeServerConnector._Sequence`

### getState() → Number

Status of the connection as code.
See CONNECTION_STATE.

#### Example

Query status

    var conn = HomeServerConnector.createConnection("user1", "pw1");
    ...
    var st = conn.getState()

Returns

  `Number` Status-Code.

### getUniversalTimer(key[, subscriptionCallback]) → HomeServerConnector._UniversalTimer

Returns an instance of a universal timer (UT).

#### Example

    var ca = conn.getUniversalTimer("TI@MyTimer", function(err, data) {});

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
key | String |  | Key of the timer
subscriptionCallback | function() | Yes | The Callback-Methode is called on subscription and on changes to the timer.

Returns

  `HomeServerConnector._UniversalTimer`

### getVacationCalendar(key[, subscriptionCallback]) → HomeServerConnector._VacationCalendar

Returns an instance of a holiday calendar.

#### Example

    var vc = conn.getVacationCalendar("VC@MyCalendar", function(err, data) {});

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
key | String |  | Key of holiday calendar
subscriptionCallback | function() | Yes | The Callback-Methode is called on subscription and on changes to the holiday calendar.

Returns

  `HomeServerConnector._VacationCalendar`

### reset()

Resets all the HS objects and cancels the corresponding subscriptions.
All the HS objects generated via this connection can no longer be used after the call.

### select(options[, Callback])

Returns a list of object keys with designations, as an option also the metadata of the objects.
The object options is transferred.

#### Example

Returns a maximum of 1000 communication objects with the tag "BM" (basement) or "Light" and no metadata

    var conn = HomeServerConnector.createConnection("user1", "pw1");
    ...
    function mySelectResponse(error, result, context) {
      ...
    }
    ...
    conn.select({"objectKey": "CO@*", "tags": ["BM", "Light"], "meta": False, "context": "test002"}, mySelectResponse)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
options | Object |  | Options (see 'Properties')
Callback | function() | Yes | The Callback-Methode which returns the return values.

#### Properties

Name | Type | Optional | Description
--- | --- | --- | ---
options.objectKey | String |  | [Filter] Object type: (see object_types).
options.tags | String | Yes | [Filter] List of tags. A specified tag must match the tag defined in Expert.
options.search | String | Yes | [Filter] List of search words. All the objects where any word begins with the specified search word in their designation or description are found.
options.from | Number | Yes | Position as consecutive number, beginning with '0'. Defaults to `0`.
options.count | Number | Yes | Maximum number of returned object keys. (Maximum value: 1000) Defaults to `1000`.
options.meta | Boolean | Yes | true: Metadata of the selected objects are also returned. Defaults to `false`.
options.context | Object | Yes | The Callback-Methode returns this object unedited.

### setReconnectInterval([interval])

Set reconnect attempt interval. Specification in seconds.

#### Example

Sets the reconnect attempt interval to 30 seconds

    var conn = HomeServerConnector.createConnection("user1", "pw1");
    ...
    conn.setReconnectInterval(30);

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
interval | Number | Yes | Defines the interval. Defaults to `60`.

## Abstract types

inner

### getCameraArchiveCallback(err, data)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object
data | Object |  | Meta information #### Structure (on subscription)
    undefined
#### Structure (on addition of an entry)
    {
      "first":  Number,
      "last":   Number,
      "count":  Number,
      "pic_id": Number
    }
#### Explanation first - Unix time stamp (in seconds, milliseconds as a decimal value) of the oldest entry in the archive. last - Unix time stamp (in seconds, milliseconds as a decimal value) of the youngest entry in the archive. count - Number of entries in the archive. pic_id - ID of the image. Is required for retrieval using getPicture().

inner

### getCommunicationObjectCallback(err, data, isInit)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object
data | Object |  | Meta information #### Structure (on subscription and on change to value)
    {
      "value": Number|String
    }
#### Explanation value - Value of the communication object
isInit | Boolean |  | true: On subscription - false: In case of value change

inner

### getDataArchiveCallback(err, data)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object
data | Object |  | Meta information #### Structure (on subscription)
    null
#### Structure (on addition of an entry)
    {
      "first": Number,
      "last":  Number,
      "count": Number
    }
#### Explanation first - Unix time stamp (in seconds, milliseconds as a decimal value) of the oldest entry in the archive. last - Unix time stamp (in seconds, milliseconds as a decimal value) of the youngest entry in the archive. count - Number of entries in the archive.

inner

### getMessageArchiveCallback(err, data)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object
data | Object |  | Meta information #### Structure (on subscription)
    null
#### Structure (on addition of an entry)
    {
      "first": Number,
      "last":  Number,
      "count": Number,
      "token": String,
      "text":  String
    }
#### Explanation first - Unix time stamp (in seconds, milliseconds as a decimal value) of the oldest entry in the archive. last - Unix time stamp (in seconds, milliseconds as a decimal value) of the youngest entry in the archive. count - Number of entries in the archive. token - Abbreviation defined in Expert for the entry. text - Text defined in Expert for the entry.

inner

### getSceneCallback(err, data)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object
data | Object |  | Meta information #### Structure (on subscription)
    null
#### Structure (on new teaching in)
    {
      "ts":       Number,
      "modified": Boolean
ÿ ኘ #### Explanation ts - Unix time stamp (in seconds, milliseconds as a decimal value). modified - true: The scene was taught in again.

inner

### getSequenceCallback(err, data)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object
data | Object |  | Meta information #### Structure (on subscription)
    null
#### Structure (on start, stop or expiry)
    {
      "ts":      Number,
      "running": Boolean
    }
#### Explanation ts - Unix time stamp (in seconds, milliseconds as a decimal value). running - true: The sequence is running.

inner

### getUniversalTimerCallback(err, data)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object
data | Object |  | Meta information #### Structure (on subscription)
    undefined
#### Structure (in the event of change to the timer)
    {
      ts:       Number,
      active:   Boolean,
      modified: Boolean
    }
#### Explanation ts - Unix time stamp (in seconds, milliseconds as a decimal value) of the change. active - true: the timer is active. modified - true: the timer was changed (event created, changed or deleted).

inner

### getVacationCalendarCallback(err, data)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object
data | Object |  | Meta information #### Structure (on subscription) and in the event of change to the holiday calendar
     {
      "active": Boolean,
      "from":   Date,
      "to":     Date
    }
#### Explanation active - true: the holiday calendar is active. from - Date object. Start of the period. to - Date object. End of the period.

inner

### onConnectCallback()

#### Example

Connection was established

    function myConnectResponse() {
      ...
    }
    ...
    conn.onConnect = myConnectResponse;

inner

### onDisconnectCallback(cause)

#### Example

Connection terminated

    function myDisconnectResponse(cause) {
      ...
    }
    ...
    conn.onDisconnect = myDisonnectResponse;

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
cause | Number |  | WebSocket status code. Reason for disconnection.

inner

### onErrorCallback(err)

#### Example

Error occurs

    function myErrorResponse(err) {
      ...
    }
    ...
    conn.onError = myErrorResponse;

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object

inner

### onProjectInfoCallback(projectID)

#### Parameter

Name | Type | Optional | Description
--- | --- | --- | ---
projectID | String |  | ID of project, e.g. "20160331114440548".

inner

### onStateChangedCallback(oldState, newState[, error])

#### Example

Connection status has changed

    function myStChgResponse(oldState, newState, error) {
      ...
    }
    ...
    conn.onStateChanged = myStChgResponse;

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
oldState | Number |  | Status value before the change.
newState | Number |  | Status value after the change.
error | Object | Yes | Error object.

inner

### selectCallback(err, result, context)

Callback method of HomeServerConnector._Connection.select().

#### Example

Returns a maximum of 1000 communication objects with the tag "BM" (basement) or "Light" and no metadata

    var conn = HomeServerConnector.createConnection("user1", "pw1");
    ...
    function mySelectResponse(error, result, context) {
      ...
    }
    ...
    conn.select({"objectKey": "CO@*", "tags": ["BM", "Light"], "meta": False, "context": "test002"}, mySelectResponse)

#### Parameters

Name | Type | Optional | Description
--- | --- | --- | ---
err | (Object or undefined) |  | Error object. The following errors may occur: "no connection", "connection lost", "server error", "too many selects".
result | Object |  | List of object keys and designations, optionally with metadata.
context | Object |  | The unmodified context specified on the call.