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).
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.
- 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]
After you have got access to service, you can set version (0 or 3):
To set global headers (which will be sent in all requests):
To send requests to server method [UCSS.DoRequest] is used.
- 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).
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:
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:
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:
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:
Type of data variable can be very different.
As well as:
- 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
You should add crossdomain.xml to root folder of your server. File should be available by address
Example of contents of crossdomain.xml:
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).