## Signaller Events

There are a number of events that are generating throughout the lifecycle of a signaller.

### Events regarding local state

The following events are generated by the signaller in response to updates n it's own state:

- `connected`

  A connection has been established via the underlying messenger to a signalling server (or equivalent).

- `disconnected`

  The connection has been lost (possibly temporarily) with the signalling server (or transport).  It is possible that the connection will be re-established so this does not necessarily mean the end.

- `local:announce`

  This event is trigged when an `/announce` message is sent via the messenging channel.  The event includes a single `data` argument which contains the object data that has been sent.

### Events regarding peer state

The following events relate to information that has been relayed to this signaller about other peers:

- `peer:filter`

  The `peer:filter` event is triggered prior to the `peer:announce` or `peer:update` events being fired and provides an application the opportunity to reject a peer.  The handler for this event is passed the id of the peer that has connected to the room and a JS `data` object for the announce data. This data only differs from the `peer:announce` (or `peer:update`) data in that an `allow` attribute is included and controls whether we will acknowledge the presence of this new peer.

  Due to the way event emitters behave in node, the last handler invoked is the authority on whether the peer is accepted or not (so make sure to check the previous state of the allow flag):

  ```js
  // only accept connections from Bob
  signaller.on('peer:filter', function(id, data) {
    data.allow = data.allow && (data.name === 'Bob');
  });
  ```

- `peer:connected`

  If a peer has passed the `peer:filter` test (either no filtering has been applied, or the allow flag is set to true in the filter events) then a `peer:connected` event will be emitted:

  ```js
  signaller.on('peer:connected', function(id) {
    console.log('peer ' + id + ' has connected');
  });
  ```

  This event can be useful if you wish to know when a peer has connected to the signalling server, and don't care whether it is a new peer (generating a `peer:announce` event) or known peer (generating a `peer:update` event).

- `peer:announce`

  While the `peer:connected` event is triggered each time a peer reconnects and announces to the signalling server, a `peer:announce` event is only emitted by your local signaller if this is considered a new connection from a peer.

  If you are writing a WebRTC application, then this event is the best place to start creating `RTCPeerConnection` objects between the local machine and your remote, announced counterpart.  You will then be able to [couple](https://github.com/rtc-io/rtc#rtccouple) those connections together using the signaller.

  ```js
  signaller.on('peer:announce', function(data) {
    console.log('discovered new peer: ' + data.id, data);

    // TODO: create a peer connection with our new friend :)
  });
  ```

- `peer:update`

  An existing peer in the system has been "re-announced" possibly with some data changes:

  ```js
  signaller.on('peer:update', function(data) {
    console.log('data update from peer: ' + data.id, data);
  });
  ```
  
- `message:<command>`
  
  When a signaller receives a command that is not associated with a specific handler (such as announce) it emits an event for that command prefixed with `message:`.  For example:
  
  ```js
  signallerA.on('message:greet', function(text) {
    console.log('signallerB sends greeting: ' + text);
  });

  signallerB.send('/greet', 'hello friend');
  ```