Action Message Format
for Unity3D

AMF for Unity Documentation

How to install

Add AMF for Unity package to your Unity project.

If you do not need demos, just add [UCSS.dll] to [Plugins] folder in your project.

How to configure

Use [UCSSconfig] to setup several parameters.

UCSSconfig.amfDefaultVersion — choose correct version (0 or 3) of your AMF server.

UCSSconfig.requestDefaultTimeOut – maximal time of expectation of response from server (in seconds).

How to use

AMF for Unity is a part of UCSS (Client-Server Solution for Unity). For this reason using of this format is closely linked to UCSS.

Use [Using Ucss;] in files, where you’ll be using UCSS (and it's AMF part).

Initialization

Use [UCSS.InitService] method for AMF initialization. AMF initialization does not require connection to server, that is why using AMF (sending requests to server) will be available via 1 frame.

[UCSS.InitService] Parameters

  • protocol — for AMF this always is UCSSprotocols.amf or "amf"
  • serviceName – any identifier for your server. May be string key or key from [UCSSservices]. It is necessary for identifying server to which you would like to make request (if you are using several servers in one project).
  • host — address to AMF server (gateway)
  • initedCallback – will be called after 1 frame after initialization of AMF service.
  • errorCallback — will be called if an error during performing request occurs (it is possible to re-define for each request). If no callback is specified for error, this will be called.

After AMF service is initialized (and initedCallback is called) there is an option to get access to AMF service using method [UCSS.GetInitedProtocol]

For example:

AMFProtocol amfProtocol = UCSS.GetInitedProtocol(”MyServerName”) as AMFProtocol;

After you have got access to service, you can set version (0 or 3):

amfProtocol.version = 3;

To set global headers (which will be sent in all requests):

amfProtocol.AddGlobalHeader(string headerName, bool mustUnderstand, object headerValue);

Sending Requests

To send requests to server method [UCSS.DoRequest] is used.

Parameters:

  • serviceName – identifier of any initialized service

  • request — prepared AMFRequest

How to prepare AMFRequest

AMFRequest has constructor, which accepts the following parameters:

  • target — a string which defines purpose of request. Format SERVICE.METHOD
    For example, if the request must be processed by service UserService and its method InitUser, then target will be "UserService.InitUser"
  • data — data for transfer to method on server (from out example, to method InitUser of service UserService)

After creation of object AMFRequest you can assign callback for processing answer from server (AMFRequest.successCallback).

For example,

request.successCallback = new EventHandlerAMFSuccess(this.UserInitedAnswer);

Also, for this request from example you can specify:

The error handler - EventHandlerServiceError onError;

Timeout handler - EventHandlerServiceTimeOut onTimeOut;

Timeout value in seconds - int timeOut;

Also you can add headers, which will be sent with this request:

AddHeader(string headerName, bool mustUnderstand, object headerValue);

Format of data

For listing method arguments (on server) List<object> is used.

E.g., if service’s method accepts 2 parameters, you must pass them in the following way:

List<object> params = new List<object>(); params.Add(param1); params.Add(param2);

If method does not accept parameters, just pass [new List<object>()] to AMFRequest constructor.

Features of AMF

The key feature of AMF is transferring of typified data. This means that you can pass custom object with data from client to server and back. For example if you have class UserVo on Client and on Server, you can pass its initialized object in the following way:

UserVo userData = new UserVo(); userData.name = “John”; userData.age = 32; // ... and any other fields List<object> args = new List<object>(); args.Add(userData); AMFRequest request = new AMFRequest("UserService.GetUser", args); UCSS.DoRequest(UCSSservices.APIServer, request);

And that’s it. Just 4 lines to send the whole object. Parameter of method [GetUser] will get an object userData with all values, which it had on client.

It works in the same way in the reverse direction (Server-Client).

Processing an answer from server

After receiving data from server and its successful processing, method [successCallback] of [AMFRequest] object is called (if it was defined).

Method of answer processing has the following format:

delegate void EventHandlerAMFSuccess(object data, string transactionId);

Type of data variable can be very different.

Primitive Types

  • Boolean
  • SByte
  • Byte
  • Char
  • Double
  • Int16
  • Int32
  • Int64
  • SByte
  • Single
  • UInt16
  • UInt32
  • UInt64

Simple Types

  • String
  • DateTime
  • Decimal
  • Guid
  • XmlReader
  • XmlDocument
  • byte[]
  • char[]

As well as:

  • null
  • IList
  • IDictionary
  • AMF3 Array
  • AMF3 Dictionary
  • AMF3 VectorObject
  • AMF3 VectorInt (uint, double)

If an object that is being sent is not recognized, it will be introduced through class AMFObject (Hashtable)

Also data will be AMFObject if an error occurred.

If you are receiving an object of class created by you from server and this class is available in your application, then data will be initialized as object of this class. Here is a useful magic!

Features of platforms

Webplayer

You should add crossdomain.xml to root folder of your server. File should be available by address [server-host]/crossdomain.xml

Example of contents of crossdomain.xml:

<?xml version="1.0" ?> <cross-domain-policy> <allow-access-from domain="*" /> </cross-domain-policy>

Server

You can use any server with support of AMF0 or AMF3. List of platforms and frameworks see on wikipedia http://en.wikipedia.org/wiki/Action_Message_Format#Support_for_AMF

You can download AmfPHP server (used for tests and demo in this package).