Server Application, API

This page references objects and events available in Server application of CumulusServer. To know how create a server application, and understand how it works, read Server application page.

Objects

Common notions

Some notions are common for all available objects.

properties

A property is available as following:

	value = object.property

And it can be assigned if it's not a read-only property like that:

	object.property = value

methods

A method is called as following:

	results = object:method(arguments)

It can take multiple parameters and return mutiple results.

events

A few objects have also some events, the system calls one of these member. Simply overload the named event by one function.

	function object:onManage()
		self:writeAMFMessage("push","test")
	end

pairs

Few objects which represent a map (hashtable) have a pairs method. It allows to iterate on the map as following:

	for name,value in mapObject:pairs() do
		print(name,value)
	end

ipairs

Few objects which represent an array have an ipairs method. It allows to iterate on the array as following:

	for index,value in arrayObject:ipairs() do
		print(index,value)
	end

Cumulus

cumulus is a global object providing access to main Cumulus elements, available anywhere in all script files.

properties

clients (read-only), clients actually connected, see clients object thereafter.
groups (read-only), existing groups (NetGroups running), see groups object thereafter.
pulications (read-only), server publications available, see publications object thereafter.
edges (read-only), CumulusEdge instances actually connected to the server, see edges object thereafter.
epochTime (read-only), gives the epoch time (since the Unix epoch, midnight, January 1, 1970) in milliseconds.
configs, return a LUA table which contains Cumulus configurations, it means the CumulusServer.ini content file, (see Installation page) and also some others usefull parameters (application.path, application.baseName, and many others. To know really all its content, iterate on this table and print its content). One sample is given in Global configurations in Server application page.

methods

publish(name), publishs a server publication with the name given, this method returns a Publication object if successful, or nil otherwise. Indeed it can fail if a publication with the same name exists already. Read publication object thereafter to get more details on how push audio,video or data packet for this publication.
absolutePath(path), take in first parameter the application path and returns a absolute way for its folder. Helpful to separate the code of your server application in many LUA files (see LUA extensions and files inclusion part of Server application page).
toAMF(...), convert the multiple LUA parameters given in a AMF format (see AMF and LUA types conversion part of Server application page to know how AMF/LUA conversion works). It returns a string which contain data converted.
toAMF0(...), exactly same that the precedent method, but with a conversion priority to AMF0 format (when possible).
fromAMF(data), convert the AMF data given in parameter in multiple LUA types relating (see AMF and LUA types conversion part of Server application page to know how AMF/LUA conversion works). It returns multiple LUA data resulting.
createTCPClient(), return a TCP client, see Server Application, Sockets page for more details.
createTCPServer(), return a TCP server, see Server Application, Sockets page for more details.
sendMail(sender,subject,content,...), send an email from sender to recipients given in the last mutiple arguments field. It returns a mail object which contains only one event, onSent(error) to get one notification on sent, see Server Application, Sockets page for more details.

Clients

clients object (available by cumulus.clients way, see above) is the collection of clients actually connected for the server.

properties

count (read-only), number of clients.

methods

pairs(), iterate on the collection, keys are client.id and values are client object (see client object thereafter).
(id/rawId), return a client object, it can take the id client parameter in a string format or a raw hex format (see client object thereafter).

Client

client object describes a connected client.

properties

id (read-only), the client id in a readable string format, it has a size of 64 bytes.
rawId (read-only), the client id in a hexadecimal raw format, it has a size of 32 bytes.
address (read-only), address of the client.
path (read-only), path used in the RTMFP URL connection, give server application relation (see Server application).
pageUrl (read-only), URL of the page which has gotten the connection, it means the URL of the page which contains the SWF client.
swfUrl (read-only), URL of the SWF file which has gotten the connection.
flashVersion (read-only), String representing the client flash version.
ping (read-only), client ping value.
writer (read-only), the main flowWriter to communicate with the client (see FlowWriter object thereafter).

Note client object can have other dynamic properties which relates HTTP properties used in the URL of connection.

	_netConnection.connect("rtmfp://localhost/myApplication?arg1=value1&arg2=value2");

	function onConnection(client,response,...)
		NOTE("client arg1 = "..client.arg1)
		NOTE("client arg2 = "..client.arg2)
	end

methods

client has no hard-coded method by default, and if you add some methods on, you create RPC function available from client side (see Communication between server and client part of Server Application page for more details).

events

onManage, overloading this method allows to get an inside handle every two seconds for the related client.

FlowWriter

a FlowWriter is an unidirectional communication pipe, which allows to write message in a fifo for the client. Each flowWriter is independant and have its own statistic exchange informations. It's used to communicate with the client, see Communication between server and client of Server application page to get more details. Each client have at less one flowWriter opened (available by client.writer, see client object above), it's its main communication channel, but you can open many flowWriters if need.

methods

writeAMFResult(...), write a result for an invokation client call, it takes multiple LUA variables as argument to convert it in AMF and send it to the client (see AMF and LUA types conversion part of Server application page to know how AMF/LUA conversion works).
writeAMFMessage(name,...), invoke a client method on client side. First parameter is the name of the function to call, and then it takes multiple LUA variables as argument to convert it in AMF and send it to the client (see AMF and LUA types conversion part of Server application page to know how AMF/LUA conversion works).
writeStatusResponse(code,[description]), call a status event on flash side. If code argument is Call.Failed for example the status event created will be NetConnection.Call.Failed. The second optional argument is the literal description of this event.
newFlowWriter(), create a new FlowWriter communication pipe and returns it.
flush([full]), fill queueing data to sending buffer of the pipe without wait anymore. Helpful in some special real-time sending case with an important flow rate, to optimize sending. In addition if the optional second argument equals true it sends all data immediatly.
close(), close the flowWriter communication pipe. This call is available only on flowWriter creates by yourself in calling client.writer:newFlowWriter(), if you can close the main flowWriter of one client, it closes its connection. After this call, you must not use anymore the flowWriter object which is going to be deleted.

events

onManage, overloading this method allows to get an inside handle every two seconds (see Communication between server and client part of Server application page to get a sample usage).

Groups

existing groups (NetGroups running), see group object thereafter. groups object (available by cumulus.groups way, see above) is the collection of groups actually ran on the server. It means all NetGroup created or joined by clients.

properties

count (read-only), number of groups.

methods

pairs(), iterate on the collection, keys are group.id and values are group object (see group object thereafter).
(id/rawId), return a group object, it can take the id group parameter in a string format or a raw hex format (see group object thereafter).

Group

group object describes a group instance (NetGroup instance).

properties

id (read-only), the group id in a readable string format, it has a size of 64 bytes.
rawId (read-only), the group id in a hexadecimal raw format, it has a size of 32 bytes.
size (read-only), number of clients in this group.

methods

ipairs(), iterate on clients connected for this group.

Edges

edges list of CumulusEdge actually connected to the server (see CumulusEdge, Scalability page for more details about CumulusEdge), and their number of clients (connected by the CumulusEdge related).

properties

count (read-only), number of edges.

methods

pairs(), iterate on the collection, keys are CumulusEdge address and values relates the number of client connected by this edge.
(address), return the number of client connected by the CumulusEdge at address point.

QualityOfService

qualityOfService object describes describes how are going a publication or a subscription (see publication and listener objects thereafter).

properties

byteRate (read-only), byte rate (bytes per second).
lostRate (read-only), value between 0 and 1 to indicate the lost data rate.
congestionRate (read-only), value between -1 and 1 to indicate the congestion data rate. When value is negative it means that byte rate could certainly be increased because there is available bandwith (-0.5 means that a byte rate increased of 50% is certainly possible).
latency (read-only), delay in milliseconds between data sending and receiving .
droppedFrames (read-only), only available in a video stream, indicate number of frames removed by CumulusServer to wait new key frame on lost data (on stream configured in a not reliable mode), or on new subscription when the publication is live-streaming.

Publications

publications object (available by cumulus.publications way, see above) is the collection of publications actually publishing on the server.

properties

count (read-only), number of publications.

methods

pairs(), iterate on the collection, keys are publication.name and values are publication object (see publication object thereafter).
(name), return a publication object, it can take the name of the publication in argument (see publication object thereafter).

Publication

publication object describes a publication.

properties

name (read-only), name of the publication
publisherId (read-only), unique identifier the publisher.
listeners (read-only), listeners which have subscribed for this publication, see listeners object thereafter.
audioQOS (read-only), qualityOfService object about audio transfer for this publication (see qualityOfService object above).
videoQOS (read-only), qualityOfService object about video transfer for this publication (see qualityOfService object above).

methods

pushAudioPacket(time,packet[,offset,lost]), push audio data to this publication. First argument is the time in milliseconds of this audio sample in the stream, the second argument is the packet data. The third optional argument allows to give an offset beginning position on the packet given (0 by default), and the last optional argument is to indicate the number of lost packets gotten since the last call for this method (it's used by qualityOfService object, see above).
pushVideoPacket(time,packet[,offset,lost]), push video data to this publication. First argument is the time in milliseconds of this video frame in the stream, the second argument is the packet data. The third optional argument allows to give an offset beginning position on the packet given (0 by default), and the last optional argument is to indicate the number of lost packets gotten since the last call for this method (it's used by qualityOfService object, see above).
pushDataPacket(name,packet[,offset]), push named data to this publication. First argument is the name of this data which relates methods to invoke on listeners side, second argument is the packet data, and the third optional argument allows to give an offset beginning position on the packet given (0 by default),
flush(), when you push audio, video or data packets, they are not flushed to listeners, you have to call this method to broadcast data when you have finished of pushed all available packets.
close([code,description]), close a publication. If this publication had been published with cumulus.publish function (see cumulus object above), the publication will be unpublished and deleted, and optional arguments are useless. Now if it's a client publication, its method close will be invoked, and a status event will be sent if optional arguments are indicated. For example, publication:close('Publish.Error','error message') will send a NetStream.Publish.Error statut event with as description error message, and then will invoke close method on client side for the NetStream object related.

Listeners

listeners object describes a collection of subscribers for one publication (see publication object above).

properties

count (read-only), number of listeners

methods

ipairs(), iterate on the list of listener (see listener object thereafter).

Listener

listener object describes a subscriber for one publication.

properties

id (read-only), unique identifier for the listener.
audioQOS (read-only), qualityOfService object about audio transfer for this subscription (see qualityOfService object above).
videoQOS (read-only), qualityOfService object about video transfer for this subscription (see qualityOfService object above).
publication (read-only), publication object which describes publication listening by the subscriber (see publication object above).
audioSampleAccess, boolean to authorize or not audio sample access by the subscriber (see NetStream:audioSampleAccess property).
videoSampleAccess, boolean to authorize or not video sample access by the subscriber (see NetStream:videoSampleAccess property).
receiveAudio, boolean to mute audio reception on the subscription.
receiveVideo, boolean to mute video reception on the subscription.

AMFObjectWriter

AMFObjectWriter is used only in one location: response argument in onConnection event (see onConnection events thereafter). It's an AMF object writer, to add some new AMF properties for the object related.

methods

write(name,value), add a new AMF property to the AMF object related. First argument is the property name of this addition, and value is a LUA variable (see AMF and LUA types conversion part of Server application page to know how AMF/LUA conversion works).

ByteReader

This object is only used for IExternalizable typed object, it's the first argument of __readExternal function, and it's an equivalent for IDataInput AS3 class (see AMF and LUA types conversion part of Server application page to know how AMF/LUA conversion works). It contains exactly same functions, excepting readObject() which is replaced by readAMF(x) function. readAMF(x) returns the x first LUA results which come from the AMF unserialization.

ByteWriter

This object is only used for IExternalizable typed object, it's the first argument of __writeExternal function, and it's an equivalent for IDataOutput AS3 class (see AMF and LUA types conversion part of Server application page to know how AMF/LUA conversion works). It contains exactly same functions, excepting writeObject(object:*) which is replaced by writeAMF(...) function. writeAMF(...) takes multiple LUA arguments for AMF serialization.

Events

CumulusServer calls some events in application server script.

Common notions

All event names starts with the on prefix.

	function onConnection(client,response,...)
	end

onStart(path)

Call when the server application is built and executed the first time. The first argument is the path of the application (see Create a server application part of Server application page).

Warning All server application are built on first client connection for the application, except root application (/ application), which is started on CumulusServer starting.

onStop(path)

Call when the server application is unloaded. It happens in three different cases:

When you edit main.lua file of one server application. Application is restarted (stopped and started).
When you delete a server application.
When CumulusServer is stopping.

The first argument is the path of the application (see Create a server application part of Server application page).

onConnection(client,response,...)

Call on a new client connection. First argument is the new comer client, and second response argument is an AMFObjectWriter to add new properties for the info object of the current NetConnection.Connect status response (see AMFObjectWriter objects in Objects part). It allows to add some new properties for this object response.

	function onConnection(client,response,...)
		response.write("message","welcome")
	end

	function onStatusEvent(event:NetStatusEvent):void {
		switch(event.info.code) {
			case "NetConnection.Connect.Success":
			trace(event.info.message); // displays "welcome"
			break;
		}
	}

Last multiple arguments are AMF parameters given to NetConnection:connect(address:String, ... parameters) converted in LUA types (see AMF and LUA types conversion part of Server application page to know how AMF/LUA conversion works).

If you return nothing for this event, the new connection client is accepted ; same thing if you return true value.

Now if you return false value, client is rejected. It answers with a NetConnection.Connect.Rejected status event and close the client connection. The event.info.description field will contain "client rejected" message. You can custome this description in returning a litteral expression:

	function onConnection(client,response,...)
		login = unpack(arg)
		if login ~= "Tom" then
			return "you are not Tom!"
		end
	end

	_netConnection.connect("rtmfp://localhost/","Ben")

	function onStatusEvent(event:NetStatusEvent):void {
		switch(event.info.code) {
			case "NetConnection.Connect.Rejected":
			trace(event.info.description); // displays "you are not Tom!"
			break;
		}
	}

Also, if you raise one error in this context, client will receive a NetConnection.Connect.Error status event which will contain the error message in its info.description field.

	function onConnection(client,response,...)
		if #arg==0 then
			error("connect takes one 'login' argument")
		end
		login = unpack(arg)
		if login ~= "Tom" then
			return "you are not Tom!"
		end
	end

	_netConnection.connect("rtmfp://localhost/")

	function onStatusEvent(event:NetStatusEvent):void {
		switch(event.info.code) {
			case "NetConnection.Connect.Error":
			trace(event.info.description); // displays "connect takes one 'login' argument"
			break;
		}
	}

Finally, other problems in this execution will send a NetConnection.Connect.Failed status event and close the client connection.

onDisconnection(client)

Call on client disconnection. client argument is the disconnected client.

Note At this stage you can send no more data to the client, all writing for a flowWriter object of this client has no effect.

onFailed(client,error)

Call on client failing. client argument is the failed client, and error argument is the error message.

Note At this stage you can send no more data to the client, all writing for a flowWriter object of this client has no effect.

onJoinGroup(client,group)

Call when a client creates or joins a group (a NetGroup). client argument is the client which is joining the group second argument (see group object in Objects part).

onUnjoinGroup(client,group)

Call when a client unjoins a group (a NetGroup). client argument is the client which is unjoining the group second argument (see group object in Objects part).

onPublish(client,publication)

Call when a publication starts. client is the client which starts the publication, and publication argument is the publication description (see publication object in Objects part).

If you return false value on this event, it will send a NetStream.Publish.Failed status event with as info.description field a "Not allowed to publish [name]" message. Otherwise you can cutomize this message in raising one error in this context.

	function onPublish(client,publication)
		if not client.right then
			error("no rights to publish it")
		end
	end

	function onStatusEvent(event:NetStatusEvent):void {
		switch(event.info.code) {
			case "NetStream.Publish.Failed":
			trace(event.info.description); // displays "no rights to publish it"
			break;
		}
	}