open-easyrtc

EasyRTC: Rooms ============== EasyRTC Room Features --------------------- - Clients can connect to one or more rooms - Clients can see all other clients in the same room - Server can restrict who gains access to rooms - Server can define room fields (variables) which are shared to all clients in a room Default Room Behavior --------------------- - If no room is specified the client will join a default room named "default" - Requested rooms will automatically be created if they don't currently exist - Clients see all other authenticated clients within the same room Server Options which Effect Rooms --------------------------------- **Room Options** - roomAutoCreateEnable - Enables the creation of rooms from the API. Occurs when client joins a nonexistent room. - Defaults to: true - roomDefaultEnable - Enables connections joining a default room if it is not initially specified. If false, than a connection initially may be in no room. - Defaults to: true - roomDefaultFieldObj - Default fields which are set when a room is created. In form of {"fieldName":{fieldValue:<JsonObj>, fieldOption:{isShared:<boolean>}}[, ...]} - Defaults to: null - roomDefaultName - The default room a connection joins if it is not initially specified. - Defaults to: "default" JavaScript Client API - Joining a room -------------------------------------- ### easyrtc.joinRoom() Joining a room is handled using the joinRoom function. This can be run before or after `easyrtc.connect()` or `easyrtc.easyApp()`. It may be called multiple times to be in multiple rooms simultaneously. It may be called before or after connecting to the server. Note: the successCB and failureDB will only be called if you are already connected to the server. **Format** `easyrtc.joinRoom(roomName, roomParameters, successCB, failureCB)` **Parameters** - **roomName** - String. Unique room name - **roomParameters** - Can be null. Parameters set here are sent to the server and seen in the `roomJoin` event. - **successCB** - Success callback which expects a function(roomName). May be null. Is only called if client is already connected to the server. - **failureCB** - Failure callback which expects a function(errorCode, errorText, roomName). May be null. Is only called if client is already connected to the server. JavaScript Client API - Leaving a room -------------------------------------- ### easyrtc.leaveRoom() Leaving a room is handled using the leaveRoom function, or through disconnecting. **Format** `easyrtc.leaveRoom(roomName, successCB, failureCB)` **Parameters** - **roomName** - String. Unique room name - **successCB** - Success callback which expects a function(roomName). May be null. Is only called if client is already connected to the server. - **failureCB** - Failure callback which expects a function(errorCode, errorText, roomName). May be null. Is only called if client is already connected to the server. Server - "roomCreate" Event --------------------------- When a client has requested to create a room, the "roomCreate" event is fired. By setting a new listener for the "roomCreate" event, the default behavior can be overruled. Note: The roomCreate event will be fired when a client requests to join a room which doesn't exist and the "roomAutoCreateEnable" option is set to true. Upon successful callback. ### Common Uses: - Authenticate who is permitted to create rooms - Set roomField's - Perform application logic, where rooms may be matched to a database entry Server - "roomJoin" Event ------------------------- Controlling who can join an existing room, and what occurs when joining is controlled by a listener for the "roomJoin" event. By setting a new listener for the "roomJoin" event, the default behavior can be overruled. ### Common Uses: - Authenticate who is permitted to join rooms - Set roomField's - Control which other clients receive an update that a client joined the room - Perform application logic, where rooms may be matched to a database entry Server - "roomLeave" Event --------------------------- When a client has requested to leave a room, the "roomLeave" event is fired. By setting a new listener for the "roomLeave" event, the default behavior can be overruled. ### Common Uses: - Prevent a client from leaving a room - Set roomField's - Control which other clients receive an update that a client left the room - Perform application logic, where rooms may be matched to a database entry If You Run Into Problems ------------------------ Please feel free to post on our discussion forum: - [https://groups.google.com/forum/?fromgroups#!forum/easyrtc](https://groups.google.com/forum/?fromgroups#!forum/easyrtc)