From a9bfcb449c8cda9adf56e22b6d54a3e496ac5329 Mon Sep 17 00:00:00 2001 From: Ian Gulliver Date: Sun, 8 Jun 2014 10:44:20 -0700 Subject: [PATCH] Document more methods. --- overview.html | 4 +- reference.html | 141 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 138 insertions(+), 7 deletions(-) diff --git a/overview.html b/overview.html index 00a4d41..4f0a21a 100644 --- a/overview.html +++ b/overview.html @@ -25,11 +25,11 @@

Cosmopolite Ovewview

-

Architecture

+

Architecture

-

Data flow

+

Data flow

diff --git a/reference.html b/reference.html index 819cb46..fa7677c 100644 --- a/reference.html +++ b/reference.html @@ -62,7 +62,7 @@
  • sendMessage()
  • getMessages()
  • getLastMessage()
    • -
  • pin()
    • +
  • pin()
  • unpin()
  • getPins()
  • trackEvent()
    • @@ -279,7 +279,7 @@ succeeds.

    1. message: A message object including metadata and message content.
      2. -
    +

    The onMessage callback is called when a historical or new message is received from the server. It is only called for subjects that the client is currently subscribed to. @@ -298,6 +298,10 @@ messages being retreived. onMessage will not fire twice for the same message unl client. You can filter messages by comparing their sender field to the return value of currentProfile() to avoid processing your own messages.

    +

    onMessage may fire when we are not connected (per the onConnect and +onDisconnect callbacks), as messages may be received in RPC responses +instead of over the channel

    +

    onPin

    @@ -305,7 +309,7 @@ value of currentProfile() to avoid processing your
    1. message: A message object including metadata and message content.
      2. -
    +

    The onPin callback is called when a new pin is received from the server. It is only called for subjects that the client is currently subscribed to.

    @@ -321,6 +325,10 @@ Promise returned by subscribe() is called. Any onPin events after that point are You can filter pins by comparing their sender field to the return value of currentProfile() to avoid processing your own pins.

    +

    onPin may fire when we are not connected (per the onConnect and +onDisconnect callbacks), as messages may be received in RPC responses +instead of over the channel

    +

    onUnpin

    @@ -328,7 +336,7 @@ You can filter pins by comparing their sender field to the return value of
    1. message: A message object including metadata and message content.
      2. -
    +

    The onUnpin callback is called when a pin is deleted on from the server. It is also called when the channel disconnects from the server, hence the server state of pins is @@ -341,8 +349,131 @@ unknown.

    You can filter pins by comparing their sender field to the return value of currentProfile() to avoid processing your own pins.

    +

    onUnpin may fire when we are not connected (per the onConnect and +onDisconnect callbacks), as messages may be received in RPC responses +instead of over the channel

    -

    Methods

    + +

    Methods

    + + +

    Constructor

    + +

    Arguments: +

      +
    1. callbacks (optional): An object with callback names as + keys and functions as values. All callbacks are optional.
      2. +
    2. urlPrefix (optional): A string containing the URL path at which to find the + server-side cosmopolite endpoints. Defaults to "/cosmopolite". See the + architecture diagram.
      3. +
    3. namespace (optional): A string containing a namespace prefix to be used for + entries in localStorage. Defaults to "cosmopolite". Changing this allows multiple local instances + of Cosmopolite to co-exist on the same domain without interfering.
      4. +
    4. trackingID (optional): A string containing a + Google Analytics tracking / + web property ID (usually starting with "UA-") identifying your analytics account. Passing + this argument enables event tracking and the trackEvent() method.
      5. +

    + +

    Construct a new Cosmopolite instance. Always use the new keyword. All methods on +the instance are available for immediate use, though some deferred initialization is occuring and +some actions may be queued.

    + + + + +

    shutdown()

    + +

    Arguments: none

    + +

    Start shutdown of this instance. No callbacks will be fired after this call. Some RPCs may be +outstanding and some cleanup may be deferred.

    + + +

    getProfile()

    + +

    Arguments: none

    + +

    Returns: A + +Promise to provide a profile ID string.

    + +

    As the profile ID is generated by the server, it requires a round trip +to complete successfully before it is known to the client. getProfile() returns a promise that +resolves immediately if the profile ID is already known, or fires when it becomes available.

    + + +

    currentProfile()

    + +

    Arguments: none

    + +

    Returns: A profile ID string, or null if unknown.

    + +

    currentProfile() has simpler semantics than getProfile() but may +return null if the initial RPC to the server is still outstanding. It is not safe to use just after +construction. It is safe to use from callbacks and promises returned by other functions, as those +require a server response.

    + + +

    subscribe()

    + +

    Arguments: +

      +
    1. subject: A valid subject (string, number or object with + specific keys)
      2. +
    2. messages (optional): An integer number of historical messages to retrieve from + this subject if available. 0 means no messages; -1 means all messages.
      3. +
    3. lastID (optional): The id field from the last message received by the client. + The server will send historical messages starting from the message after that.
      4. +
    + +

    Returns: A + +Promise that resolves with no arguments on success, or rejects with no arguments if the client +is denied access to the subject.

    + +

    subscribe() creates a subscription on the server to a particular +subject. The subscription is tied to our current instance but is re-created +by the client library when it reconnects, transparent to the application.

    + +

    Before the promise returned by subscribe() resolves, the onMessage and +onPin callbacks will fire for any historical messages requests and available +and for any current pins. After the promise resolves, messages and +pins sent to this subject will cause the callbacks to fire when they are +received. Additionally, the onUnpin callback will fire for deleted pins.

    + +

    Callbacks fire for messages sent by our own profile and +client. You can filter messages by comparing their sender field to the return +value of currentProfile() to avoid processing your own messages.

    + +

    subscribe() may be called multiple times for the same subject to retrieve additional historical +messages. The subscriptions do not stack, however; a single call to +unsubscribe() undoes all preceding subscribe() calls to that subject. +

    + +

    subscribe() calls may fail (and reject the promise) when subscription is requested to a +subject that sets readable_only_by and that does not match our +profile.

    + + +

    unsubscribe()

    + +

    Arguments: +

      +
    1. subject: A valid subject (string, number or object with + specific keys)
      2. +

    + +

    Returns: A + +Promise that resolves on RPC completion.

    + +

    Unsubscribe from a subject and stop receiving +callbacks related to it. Callbacks stop immediately after calling +unsubscribe().

    + +

    A single call to unsubscribe() undoes all calls to subscribe() for the +given subject.