In addition to message passing, the channel library also provides notification of connection state to the server. This is passed to the application code using the -onConnect and onDisconnect callbacks.
+connect and disconnect events.When a message is received (via the onMessage callback or the return +
When a message is received (via a message event or the return result from getMessages() or getLastMessage()), metadata is attached, packaged into an object with the message data itself: @@ -224,145 +224,150 @@ method.
A pin is a message that is deleted when the instance that sent it disconnects. Subscribers to the pin's -subject are notified (via the onPin and -onUnpin callbacks) when it is added and deleted. This allows pins to be +subject are notified (via the pin and +unpin events) when it is added and deleted. This allows pins to be used for presence detection.
Pins are added and deleted by the application using the pin() and unpin() methods.
-The Cosmopolite client library uses JavaScript Events by implementing +EventTarget. +Listening for these events is the primary means to receive notification of changes in status and +incoming messages. Event listeners may be added at any time, but are most useful when +added immediately after construction. Adding listeners later won't replay events sent in the +interim.
+ +Note that all the event-specific values mentioned below are contained within the Event's +detail member, not on the top-level Event object.
-Arguments: none
+Values: none
-The onConnect callback is called when the channel is established to the -server. It is paired with the onDisconnect callback except when +
The connect event is called when the channel is established to the +server. It is paired with the disconnect event except when shutdown() is called.
-Arguments: none
+Values: none
-The onDisconnect callback is called when the channel is disconnected. +
The disconnect event fires when the channel is disconnected. This can happen due to connectivity problems, server outages or periodically when the channel expires.
-Arguments: +
Values:
username: The user's Google username string.logout_url: A URL that the user can load to terminate their session. This should
be opened in a new window (using target="_blank").The onLogin callback is called when the user logs in. It is also called after the first RPC -to the server succeeds if the user was already logged in. It is guaranteed that either onLogin -or onLogout is called after the first RPC succeeds.
+The login event fires when the user logs in. It also fires after the first RPC +to the server succeeds if the user was already logged in. It is guaranteed that either login +or logout will fire after the first RPC succeeds.
-Arguments: +
Values:
login_url: A URL that the user cna load to log in to their Google account. This
should be opened in a new window (using target="_blank").The onLogin callback is called when the user logs out or is logged out by Google. It is also -called after the first RPC to the server succeeds if the user was not already logged in. It is -guaranteed that either onLogin or onLogout is called after the first RPC -succeeds.
+The login event fires when the user logs out or is logged out by Google. It also +fires after the first RPC to the server succeeds if the user was not already logged in. It is +guaranteed that either login or logout fires after the first RPC succeeds.
-Arguments: +
Values:
message: A message object including metadata and message
content.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. +
The message event fires when a historical or new message is received from the server. +It only fires for subjects that the client is currently subscribed to.
-After a call to subscribe(), onMessage fires once for each historical +
After a call to subscribe(), message fires once for each historical message received from the server. After all historical messages have been processed, the resolve -callback for the Promise returned by subscribe() is called. Any onMessage events after that point +callback for the Promise returned by subscribe() is called. Any message events after that point are for new messages.
Calling subscribe() more than once may lead to additional historical -messages being retreived. onMessage will not fire twice for the same message unless +messages being retreived. message will not fire twice for the same message unless unsubscribe() is called in the interim.
-onMessage fires for messages sent by our own profile and +
message fires 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.
-onMessage may fire when we are not connected (per the onConnect and -onDisconnect callbacks), as messages may be received in RPC responses +
message may fire when we are not connected (per the connect and +disconnect events), as messages may be received in RPC responses instead of over the channel
-Arguments: +
Values:
message: A message object including metadata and message
content.The onPin callback is called when a new pin is received from the server. It is only called for +
The pin event fires when a new pin is received from the server. It only fires for subjects that the client is currently subscribed to.
-After a call to subscribe(), onPin fires once for each pin already +
After a call to subscribe(), pin fires once for each pin already present in the subject. After all standing pins have been processed, the resolve callback for the -Promise returned by subscribe() is called. Any onPin events after that point are for new pins.
+Promise returned by subscribe() is called. Any pin events after that point are for new pins. -onPin callbacks are paired with onUnpin callbacks except when +
pin events are paired with unpin events except when shutdown() is called.
-onPin fires for pins from own profile and client. +
pin fires for pins from our own profile and client. 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 +
pin may fire when we are not connected (per the connect and +disconnect events), as messages may be received in RPC responses instead of over the channel
-Arguments: +
Values:
message: A message object including metadata and message
content.The onUnpin callback is called when a pin is deleted on from the server. It is also called when +
The unpin event fires when a pin is deleted on from the server. It also fires when the channel disconnects from the server, hence the server state of pins is unknown.
-onUnpin callbacks are paired with onPin callbacks except when +
unpin events are paired with pin events except when shutdown() is called.
-onUnpin fires for pins from own profile and client. +
unpin fires for pins from own profile and client. 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 +
unpin may fire when we are not connected (per the connect and +disconnect events), as messages may be received in RPC responses instead of over the channel
@@ -373,8 +378,6 @@ instead of over the channelArguments:
callbacks (optional): An object with callback names as
- keys and functions as values. All callbacks are optional.urlPrefix (optional): A string containing the URL path at which to find the
server-side cosmopolite endpoints. Defaults to "/cosmopolite". See the
architecture diagram.Arguments: none
-Start shutdown of this instance. No callbacks will be fired after this call. Some RPCs may be +
Start shutdown of this instance. No events will be fired after this call. Some RPCs may be outstanding and some cleanup may be deferred.
@@ -433,8 +436,8 @@ resolves immediately if the profile ID is already known, or fires when it becomecurrentProfile() 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.
+construction. It is safe to use from event listeners and promises returned by other functions, as +those require a server response.Before the promise returned by subscribe() resolves, the onMessage and -onPin callbacks will fire for any historical messages requests and available +
Before the promise returned by subscribe() resolves, the message and +pin events 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.
+pins sent to this subject will cause events to fire when they are +received. Additionally, the unpin event 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 @@ -492,7 +495,7 @@ profile.
Promise that resolves on RPC completion.Unsubscribe from a subject and stop receiving -callbacks related to it. Callbacks stop immediately after calling +events related to it. Events stop immediately after calling unsubscribe().
A single call to unsubscribe() undoes all calls to subscribe() for the
@@ -513,7 +516,7 @@ given subject.
Promise that resolves on success, or rejects with no arguments if the client is denied access
to write to the subject. On success, a message argument is passed to the
-resolution callback; it differs from the original message argument in that it has
+resolve callback; it differs from the original message argument in that it has
metadata added by the server.
Sends a message to the given subject. The message
@@ -529,10 +532,11 @@ to a pin which is ephemeral and tied to the current
subject sets writable_only_by and it does not match our
current profile.
If we are also subscribed to the given subject and have provided an -onMessage callback, it will fire for this message when it is received -back from the server. You can filter messages by comparing their sender field to the return value -of currentProfile() to avoid processing your own messages.
+If we are also subscribed to the given subject and are listening to +message events, listeners will fire for this message when it +is received back from the server. You can filter messages by comparing their sender field to the +return value of currentProfile() to avoid processing your own +messages.
writable_only_by and it does not match our
current profile.
-If we are also subscribed to the given subject and have provided an -onPin callback, it will fire for this pin when it is received back from the -server. You can filter pins by comparing their sender field to the return value of +
If we are also subscribed to the given subject and are listening to +pin events, listeners will fire for this pin when it is received back +from the server. You can filter pins by comparing their sender field to the return value of currentProfile() to avoid processing your own pins.
@@ -607,7 +611,7 @@ server. You can filter pins by comparing their sender field to the return valueid: An ID string previously passed to the resolve callback of the promise
returned by pin() or the sender_message_id from the
- onPin callback or the return value of getPins().
+ pin event or the return value of getPins().
Returns: A