Please check the status of this specification in Launchpad before editing it. If it is Approved, contact the Assignee or another member of the Core Development Team before making changes.

• Launchpad Entry: https://blueprints.launchpad.net/mira/+spec/net-protocols-client-server
• Created: 2007-09-12 by clsk
• Contributors: beyonddc, clsk, j_k9

• Empty spaces in front of messages are to be ignored.
• A message must end with a New Line character (\n)
• Clients should NOT expect that only this number of parameters are to be given at all times.
• Clients should be able to add more parameters than expected even if they are not parsed. This will guarantee that old clients don't break in case extensions to the protocol are made. New parameters not included in this edition of the protocol are to be added to the end of the parameters list.
• Message Tokens are command abbreviations used so that the server doesn't have to send explicit commands and save some bandwidth. This has been proved to be useful in IRC with thousands of clients connected. I believed we should take advantage of this.
• If a parameter has more than one word in it then it should be enclosed within quotation marks (””).

Fields within <> are Mandatory.
Fields within [] are Optional.

An error message from the server to a Client.

E <Command> [Message]

Example: [Server] E N “Bad User”

NOTES: Error message should try to be as generic as possible so that error message handling can be done at the client level.

Attempt to create a new client.

NU <username> <eMail> <password> <FirstName> [LastName]

UA <UserID> <username>

Example: [Client] NU clsk alan.alvarez@us.army.mil encryptedPass Alan Alvarez
[Server] UA 283 clsk

NOTES: It'll be optional to let anyone create a new account or let only the Server admin or Group Managers to create a new accountd.
This should be an option in mira-server.conf
Also, note that the UserID is generated by the server.

LM <workplace>

The server would then respond with a ML message

ML <workplace> username1:n,username2:f

LU <workplace>

The server would then respond with a UL message

UL <workplace> Utility1,Utilit2

LW

The server would then respond with a WL message

WL id:workplacename1,id:workplacename2

Attempt to login to the server.

L <username> <password>

LS

Example: [Client] L clsk EncryptedPass
[Server] LS

A client letting know the server that it is logging out, and closing the connection.

LO

A user sending a Message to a group

[Client] M <GroupName> <Message>

[Server] M <username> <GroupName> <Message> <TimeStamp>

Example: [Client] M Mira “Welcome to Group Mira” [Server] M clsk Mira “Welcome to Group Mira” 7898547

[Server] NM <username> <"Workplace">

[Client] PM <username> <Message>

[Server] PM <sender username> <reciever username> <Message> <TimeStamp>

Example: [Client] PM J_K9 “Hello J_K9, this is clsk”\n
[Server] PM clsk J_K9 “Hello J_K9, this is clsk” 75654198

[Client] PG <workplace>

[Server] GP <username> <workplace>

Note: Server will respond with WP to all workplace members.

A user trying to create a new group.

NG <GroupName> <GroupOwner>

GA <GroupName>

Example: [Client] NG Mira clsk
[Server] GA Mira

A server describing a group to a user.

G <GroupName> <GroupMembers>

Example: [Server] G Mira clsk,J_K9,beyonddc

NOTES: GroupMembers is a comma-separated list of usernames in that group.
Examples of times where this message would be sent are: When a user logs in to the server, when an user joins a group .

[Client] PG <workplace>

[Server] GP <username> <workplace>

Note: Server will respond with GP to all workplace members.

A user trying to join a new group

JG <GroupName> [InvitationID]

NOTES: Invitation IDs are to be passed whenever possible as this should make the process of finding the ID faster. If not the server would have to find a matching invitation for the user to that specific group in its invitation table.
Some groups might be able to be joined without invitations. This is up to the Group Manager and is a Group configuration.
If a user successfully joins a group, a server responds with a Group description message.

This is the response given by a Mira server to a successful JG message.

GJ <GroupName>

A server describing an User to another User

U <username> [eMail] [FirstName] [LastName] [GroupIDs] [...]

Example: [Server] clsk alan.alvarez@us.army.mil Alan Alvarez Mira,Group2

NOTES: How much data is sent depends on how much data the user wants other people to be able to see.
This is a message that will probably be highly modified throughout time.

This token is used for Utility communication between the client and the server.
This is not used for inter-utility communication
ie: A file utility communication with its counterpart on the server.

UT <utility> <workplace> <...>

Example: [Client] UT Files “Blues Project” CREATE document.txt
[Server] UT Files “Blues Project” CREATED document.txt 1230394

A user trying to find out information about another User or Group.

Q <USERS|GROUPS> <Field1,Field2,Field3,...|*> [Field1=Value1,Field2=Value2,Field3=Value3,etc...]

Example: [Client] Q USERS * FirstName=Alan,LastName=Alvarez
Server responds with a User or Group Description returning only those fields specified in parameter 2.
If * is specified all fields will be sent back.

If no Field=Value is passed then the server will show all users or groups.

A Client OR Server checking for response.

PI <ID>

PO <ID>

Example: [Server] PI 25
[Client] PO 25

A Client OR Server checking for response.

PI <ID>

PO <ID>

Example: [Server] PI 25
[Client] PO 25

UL <workplace> [Utility1],[Utility2],[...]

Note that utilities are separated by commas.

WL [id:workplacename1],[id:workplacename2],[...]

WD <Workplace Name> <Workplace Description>

Note: In the Mira client and server implementation, this message is automatically sent to the client when requesting the workplace's utility list (WL).

This is how a normal conversation should look like:

[Client] NU clsk alan.alvarez@us.army.mil EncryptedPass Alan Alvarez
[Server] UA clsk
[Client] L clsk EncryptedPass
[Server] LS
[Client] NG Mira
[Server] GA Mira
[Client] Q GROUPS * GroupName=Mira
[Server] G Mira clsk,J_K9,
[Client] M clsk "Welcome to Group Mira"
[Server] M clsk Mira "Welcome to Group Mira" 7898547
[Server] T SomeServerToken147 SomeClientToken258
[Client] PI foo
[Server] PO foo