Protocol CMD

Louis Charette edited this page Apr 19, 2014 · 1 revision

The APE Server is controllable via Commands sent by an external client (for example the APE JavaScript Framework). The Commands are sent via an HTTP request to the Server via GET or POST methods. A command refers to data sent from the client to the server. A command is a JSON object with the following mandatory keys:

  • cmd: Name of the command
  • chl: Challenge, the challenge is as integer incremented to every request sent to server.
[
    {
        "cmd":"<command name>",
        "chl":<challenge>
    }
]

###Example command to server Either POST or GET is allowed as the HTTP method. The url querystring (if GET is used) or the request body (if POST is used) must be added after ? with the value of a json-encoded array.

Requests to a server are done on the following URL :

http://[Frequency].[Server URL]/?

GET example :

GET /?[{"cmd":"CONNECT","chl":0,"params":{"transport":0}}] HTTP/1.1
Post: 0.ape.ape-project.org

POST example :

POST /? HTTP/1.1
Host: 0.ape.ape-project.org

[{"cmd":"CONNECT","chl":0,"params":{"transport":0}}]

The Host header is used to detect new sub user, this feature allows multiple windows/tabs. See Session for more information.

###Multiple commands at once You can send several commands at once by putting them into a JSON Array ([])

[{"cmd":"COMMAND_NAME","chl":1,"sessid":"xxxxxx","params":{"foo":"bar}},{"cmd":"COMMAND...."}]

#Extend commands APE is shipped out of the box with a set of pre-registered Commands, allowing lots of different actions such as :

  • CONNECT Returns a RAW IDENT set a sessid on the user an sends a RAW LOGIN
  • SCRIPT Sends the files thaw were requested in the json array
  • CHECK (sessid needed) does nothing
  • SEND (sessid needed) send a Raw Data to the requested pipe
  • QUIT (sessid needed) sends a Raw quit and makes the user quit
  • JOIN (sessid needed) Joins the user on the channel if possible. If the channel does not exist, it is created
  • LEFT (sessid needed) makes a user leave a channel or sends error {103 UNKNOWN, 104 NOT_IN_CHANNEL}
  • SESSION (sessid needed) sets or gets session propertyies and returns with Raw SESSIONS or sends a error (203 SESSION_ERROR BAD_PARAMS), The APE Server API allows to a C or JavaScript (server-side) Plugin to easily add Commands (see server API register_cmd()).

#Events The APE_JSF can intercept CMD, based on that you can trigger further actions in your client. You can also define on the APE server the desired behaviour for every CMD that arrives.