Class Subscription

Extends Resource.
Subscription Resource
Defined in: subscription.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Subscription(spire, data) Represents a subscription in the spire api.

Field Summary
Field Attributes	Field Name and Description
	data Actual data from the spire.io api.
	get Alias for subscription.retreiveEvents.
	last Timestamp of last event received.
	listening Whether the subscription is currently polling for events.
	spire Reference to spire object.

Method Summary
Method Attributes	Method Name and Description
	longPoll(options, cb) Gets new events for the subscription.
	name() Gets the name of the subscription.
	poll(options, cb) Gets new events for the subscription.
	retrieveEvents(options, cb) Gets events for the subscription.
	startListening(options, cb) Starts long polling for the subscription.
	stopListening() Stops listening on the subscription.

Methods borrowed from class Resource:: authorization, capabilities, capability, getIfCapable, mediaType, request, schema, update, url

Class Detail

Subscription(spire, data)

Represents a subscription in the spire api.

There are a few ways to get events from a subscription.

The first is to call subscription.retrieveEvents directly. This is the most general method, and supports a number of options.

There are convenience methods subscription.pollsubscription.longPoll which wrap retrieveEvents. The only difference is that subscription.poll has a timeout of 0, so the request will always come back right away, while subscription.longPoll has a 30 second timeout, so the request will wait up to 30 seconds for new events to arrive before returning.

You can also use the event message join and part events to listen for new events on the subscription.


   subscription.addListener('message', function (message) {
     console.log('Message received: ' + message.content);
   });

   subscription.addListener('join', function (join) {
     console.log('Subscription joined: ' + join.subscription_name);
   });

   subscription.addListener('part', function (part) {
     console.log('Subscription parted: ' + part.subscription_name);
   });

   subscription.addListener('event', function (event) {
     // This fires for messages, joins, and parts.
     console.log('Received event!');
   });

   subscription.startListening();

By default this will get all events from the beginning of time. If you only want messages created from this point forward, pass { min_timestamp: 'now' } in the options to `startListening`:


   subscription.startListening({ min_timestamp: 'now' });

Parameters:
{object} spire: Spire object
{object} data: Subscription data from the spire api

Field Detail

data

Actual data from the spire.io api.

get

Alias for subscription.retreiveEvents.

last

Timestamp of last event received.

listening

Whether the subscription is currently polling for events. You should not change this value yourself. Use `subscription.startListening()` and `subscription.stopListening()` instead.

spire

Reference to spire object.

Method Detail

longPoll(options, cb)

Gets new events for the subscription.

This method defaults to a 30 second timeout, so the request will wait up to 30 seconds for a new message to come in. You can increase the wait time with the options.timeout paraameter.

This method only makes one request. Use `subscription.startListening` to poll repeatedly.

subscription.longPoll({ timeout: 60 }, function (err, events) {
  if (!err) {
    // `events.messages` is an array of messages (possably empty)
  }
});

Parameters:
{object} options Optional: Optional options argument
{number} options.delay Optional: Optional delay
{number} options.timeout Optional: Optional timeout
{function (err|events)} cb: Callback

{string} name()

Gets the name of the subscription.

Returns:: {string} Name

poll(options, cb)

Gets new events for the subscription. This method forces a 0 second timeout, so the request will come back immediately, but may have an empty array of events if there are no new ones.

This method only makes one request. Use subscription.startListening to poll repeatedly.

subscription.poll(function (err, events) {
  if (!err) {
    // `events.messages` is an array of messages (possably empty)
  }
});

Parameters:
{object} options Optional: Optional options argument
{number} options.delay Optional: Optional delay
{function (err|events)} cb: Callback

retrieveEvents(options, cb)

Gets events for the subscription.

This method only makes one request. Use subscription.startListening to poll repeatedly.

subscription.retrieveEvents(function (err, events) {
  if (!err) {
    // `events` is a hash with `messages`, `joins`, and `parts` (each possibly empty)
  }
});

Parameters:
{object} options Optional: Optional options argument
{number} options.min_timestamp Optional: Optional min_timestamp of events to receive
{number} options.max_timestamp Optional: Optional max_timestamp of events to receive
{number} options.last Optional: Optional last message (same as min_timestamp)
{number} options.delay Optional: Optional delay
{number} options.timeout Optional: Optional timeout
{function (err|messages)} cb: Callback

startListening(options, cb)

Starts long polling for the subscription.

The message and messages events will fire when a request comes back with messages. The message event will fire once per message, while the messages event fires every time a request comes back with more than one message.

subscription.addListener('message', function (message) {
  console.log('Message received: ' + message.content);
});

subscription.startListening();

// Stop Listening after 100 seconds.
setTimout(function () {
  subscription.stopListening();
 }, 100000);

By default this will get all events from the beginning of time.
If you only want messages created from this point forward, pass { min_timestamp: 'now' } in the options to `startListening`:


   subscription.startListening({ min_timestamp: 'now' });

Parameters:
{object} options Optional: Optional options argument
{number} options.min_timestamp Optional: Optional min_timestamp of events to receive
{number} options.max_timestamp Optional: Optional max_timestamp of events to receive
{number} options.last Optional: Optional last message (same as min_timestamp)
{number} options.delay Optional: Optional delay
{number} options.timeout Optional: Optional timeout
{function (err|messages)} cb: Callback

stopListening()

Stops listening on the subscription.

Classes

Class Subscription