====== Remoting envelope ======

{{tag>documentation amf remoting}}

A Remoting request from the client consists of a short preamble, headers, and bodys. The preamble contains basic information about the nature of the request. Headers can be used to request debugging information, send authentication info, tag transactions, etc. Bodies contain actual Remoting requests and responses. A single Remoting envelope can contain several requests; Remoting supports batching out of the box.

Client headers and bodies need not be responded to in a one-to-one manner. That is, a body or header may not require a response. Debug information is requested by a header but sent back as a body object. The response index is essential for Flash player to understand the response therefore.


===== Preamble =====

The first two bytes of an AMF message are an unsigned short int. In PHP you can read this with the following code. 

''
public function readUnsignedShort() {
  $byte1 = $this->readByte();
  $byte2 = $this->readByte();
  return (($byte1 << 8) | $byte2);
}
''

The result indicates what type of Flash Player connected to the server. 
  * **0x00** for Flash Player 8 and below
  * **0x01** for FlashCom/FMS
  * **0x03** for Flash Player 9

Note that Flash Player 9 will always set the second byte to 0x03, regardless of whether the message was sent in AMF0 or AMF3.

The **third and fourth bytes** form an integer value that specifies the number of headers.

===== AMF Headers =====

Each header consists of the following:

  * UTF string (including length bytes) - name
  * Boolean - specifies if understanding the header is 'required'
  * Long - Length in bytes of header
  * Variable - Actual data (including a type code)

AMF headers may be user-created. However, certain headers have certain meaning that a gateway should respond to. See [[documentation:amf:envelopes:remoting:headers|predefined headers]] for more information.

===== AMF Bodies =====

Between the headers and the start of the bodies is a int specifying the number of bodies. Each body consists of the following:

  * UTF String - Target
  * UTF String - Response
  * Long - Body length in bytes
  * Variable - Actual data (including a type code)

The target may be one of the following:

  * An http or https URL. In that case the gateway should respond by sending a SOAP request to that URL with the specified data. In that case the data will be an array and the first key (data[0]) contains the parameters to be sent.
  * A string with at least one period (.). The value to the right of the right-most period is the method to be called. The value to the left of that is the service to be invoked including package name. In that case data will be an array of arguments to be sent to the method.

The response is a string that gives the body an id so it can be tracked by the player. 

===== Body response =====

The response to a request has the exact same structure as a request.
A request requiring a body response should be answered in the following way:

  * Target: set to Response index plus one of "/onStatus", "onResult", or "/onDebugEvents". "/onStatus" is reserved for runtime errors. "/onResult" is for succesful calls. "/onDebugEvents" is for debug information, see [[documentation:amf:envelopes:remoting:debugInfo|debug information]]. Thus if the client requested something with response index '/1', and the call was succesful, '/1/onResult' should be sent back.
  * Response: should be set to the **string** 'null'.
  * Data: set to the returned data.