Client Actions

The gopherClient.connect() function is one of many actions the client can send to the server. Here, I will list all client actions linked to the section that describes it's usage:

• connect(): Connects the client to the server
• disconnect(): Disconnects the client from the server
• login(): Logs the client in as a User
• logout(): Logs the client out of a User
• signup(): Creates a User account
• changePassword(): Changes the client User's account password
• changeAccountInfo(): Changes one or more client User's custom account info columns
• deleteAccount(): Deletes a User account
• joinRoom(): Makes the client User join an existing room
• leaveRoom(): Makes the client User leave their current room
• createRoom(): Creates a room
• deleteRoom(): Deletes a room created by the client User
• sendInvite(): Sends an invite to another User to the client's private room
• revokeInvite(): Revokes a previously sent invite to the client's private room
• chatMessage(): Sends a chat message to the client User's current room
• privateMessage(): Sends a private message from the client User to another User
• requestFriend(): Sends a friend request from the client User to another User
• acceptFriend(): Accepts a friend request to the client User from another User
• declineFriend(): Declines a friend request to the client User from another User
• removeFriend(): Removes a friend from the client User's friend list
• changeStatus(): Changes the client User's status and sends update to their friends
• setUserVariable(): Sets a single client User's variable
• setUserVariables(): Sets multiple client User's variables
• getUserVariable(): Gets a single client User's variable (API retrieves from RAM, not server)
• customClientAction(): Executes a custom client action on the server

Login & Logout

Logging the client in and out is easy. Just use the gopherClient.login() and gopherClient.logout() functions:

gopherClient.login("My Name", "", false, false, null);
gopherClient.logout();

The login() function takes in 5 parameters: userName string, password string, rememberMe boolean, isGuest boolean, and customCols object. The userName parameter accepts a string that logs the client in under that name, and the fourth parameter isGuest logs the user in as a guest. The password, rememberMe, and customCols are used with the SQL features.

logout() takes no parameters and immediately logs the client out from their current User.

Login & Logout Event Listeners

When the server is done logging the client in or out, it sends back a response with either a success message or error. You can capture the error and success messages with the events.login and events.logout listeners:

gopherClient.addEventListener(gopherClient.events.login, onLogin);
gopherClient.addEventListener(gopherClient.events.logout, onLogout);

function onLogin(userName, error){
    if(error != null){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Logged in as: "+userName);
    }
}

function onLogout(success, error){
    if(error != null){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("You have been logged out");
    }
}

If one of these event listeners has an error that is not null, an error occurred while logging in or out. error is an object with id being an integer representing an error ID, and m being a string with a message about what went wrong.

Rooms

Joining and Leaving

To join a room the client must be logged in, a room to join must exist on the server, and if the room is private, the client User needs to be on the invite list. You can use the joinRoom() and leaveRoom() functions:

gopherClient.joinRoom("roomName");
gopherClient.leaveRoom();

The joinRoom() function takes one parameter, being the name of the room the client wishes to join. leaveRoom() will immediately remove the client from their current room.

Similar to logging in and out, you can make event listeners for joining and leaving rooms with the events.joined and events.left listeners:

gopherClient.addEventListener(gopherClient.events.joined, joinedRoom);
gopherClient.addEventListener(gopherClient.events.left, leftRoom);

function joinedRoom(roomName, error){
    if(error != null){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Joined '"+roomName+"'");
    }
}

function leftRoom(roomName, error){
    if(error != null){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Left '"+roomName+"'");
    }
}

Similarly, if the client is in a room with BroadcastUserEnter or BroadcastUserLeave enabled, they will receive an events.userJoined or events.userLeft event that you can capture when another User enters/leaves the current room:

gopherClient.addEventListener(gopherClient.events.userJoined, userJoinedRoom);
gopherClient.addEventListener(gopherClient.events.userLeft, userLeftRoom);

function userJoinedRoom(userName, isGuest){
    console.log("'"+userName+"' has joined the room");
}

function userLeftRoom(userName){
    console.log("'"+userName+"' has left the room");
}

userName is a string which is the name of the entering/leaving User, and isGuest is a boolean that's true if the User entering the room is a guest.

Creating and Deleting

To create and delete rooms, a client must be logged in, and the server's rules (UserRoomControl - and don't forget RoomType rules) must allow it. With that in mind, you can use the createRoom() and deleteRoom() functions:

gopherClient.createRoom("name", "type", true, 0);
gopherClient.deleteRoom("name");

createRoom() takes four parameters: roomName string, roomType string, isPrivate boolean, and maxUsers integer. roomName is the name of the room to create, roomType is the type of room to create, isPrivate makes the room private when true, and maxUsers is a number representing the maximum amount of users that can join.

deleteRoom() only needs one parameter roomName (string), which is the name of the room to delete

Note: A client must be the owner of a room in order to delete it or send/revoke invitations

You can set event listeners for when the room is either created or deleted with the events.roomCreate and events.roomDelete listeners:

gopherClient.addEventListener(gopherClient.events.roomCreate, createdRoom);
gopherClient.addEventListener(gopherClient.events.roomDelete, deletedRoom);

function createdRoom(roomName, error){
    if(error != null){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Created room '"+roomName+"'");
    }
}

function deletedRoom(roomName, error){
    if(error != null){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Deleted room '"+roomName+"'");
    }
}

Sending and Revoking Invitations

Clients can only send and revoke invites for the room they are currently in. Clients must also be the owner of the room to send and revoke invitations to it. With that in mind, you can send/revoke invitations with the sendInvite() and revokeInvite() functions:

sendInvite("name");
revokeInvite("name");

Both functions accept one parameter: a string which is the name of the User the client wishes to send an invite to, or revoke the invite from.

You can set event listeners for when the client sends/revokes an invitation with the events.invited and events.inviteRevoked listeners:

gopherClient.addEventListener(gopherClient.events.invited, invited);
gopherClient.addEventListener(gopherClient.events.inviteRevoked, revokedInvite);

function invited(success, error){
    if(error != null){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Invite was sent");
    }
}

function revokedInvite(success, error){
    if(error != null){
        console.log("Error: [ID - "+error.id+"], [Message - '"+error.m+"']");
    }else{
        console.log("Invite revoked");
    }
}

Similarly, when the client receives an invite to a room, you can catch it with a events.inviteReceived listener:

gopherClient.addEventListener(gopherClient.events.inviteReceived, receivedInvite);

function receivedInvite(userName, roomName){
    console.log("Invite from '"+userName+"' to the room '"+roomName+"'");
}