API¶

Properties¶

A property is available as follows:

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 follows:

results = object:method(arguments)

It can take multiple parameters and return mutiple results.

events¶

A few objects have also some events called by the system. Simply overload the named event by defining a function as follows:

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

pairs and ipairs¶

Objects are kind of array or map, so you can iterate between elements of objects as follows:

for index,value in ipairs(object) do
  INFO(index,value)
end

properties¶

• clients (read-only), Clients actually connected.
• configs (read-only), return a LUA table which contains Mona configurations, it means the MonaServer.ini content file, (see Configurations) 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.
• environment (read-only), return a LUA table which contains environment variables from the system.
• groups (read-only), existing Groups (NetGroup running).
• pulications (read-only), server Publications available.
• servers (read-only), MonaServer instances actually connected to the server, see Servers object.

Example of access to a Mona global property :

for id, client in pairs(mona.clients) do
  INFO(id, " : ", client.address)
end

methods¶

• 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).
• addToBlacklist(…), add to the blacklist the address(es) ip given as input argument(s).
• removeFromBlacklist(…), remove from the blacklist the address(es) ip given as input argument(s).
• createIPAddress(address), convert an IP Address string to an IPAddress object without DNS resolution (not blocking method).
• createIPAddressWithDNS(address), convert an IP Address string to an IPAddress object with DNS resolution (blocking method).
• createSocketAddress(address), convert a Socket Address string (with host and port) to a SocketAddress object without DNS resolution (not blocking method).
• createSocketAddressWithDNS(address), convert a Socket Address string (with host and port) to a SocketAddress object with DNS resolution (blocking method).
• 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.
• createUDPSocket([allowBroadcast]), return a UDP socket. The optional boolean allowBroadcast argument allows broadcasting date by this socket (by default it’s to false). See Server Application Sockets page for more details.
• 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.
• fromAMF(data), convert the AMF data given in parameter in multiple LUA types relating (see AMF to LUA conversions to know how AMF/LUA conversion works). It returns multiple LUA data variables.
• toAMF(…), convert the multiple LUA parameters given in a AMF format (see AMF to LUA conversions 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).
• fromJSON(data), convert the JSON data given in parameter in multiple LUA types relating (see JSON to LUA conversions to know how JSON/LUA conversion works). It returns multiple LUA data variables.
• toJSON(…), convert the multiple LUA parameters given in a JSON format (see JSON to LUA conversions to know how Query/LUA conversion works). It returns a string which contain data converted.
• fromQuery(data), convert the Query string data given in parameter in multiple LUA types relating (see JSON to LUA conversions to know how Query/LUA conversion works). It returns multiple LUA data variables.
• toQuery(…), convert the multiple LUA parameters given in a Query string format (see JSON to LUA conversions to know how JSON/LUA conversion works). It returns a string which contain data converted.
• fromXML(data), convert the XML data given in parameter in multiple LUA types relating (see XML data compatibility (XML parser) to know how XML/LUA conversion works). It returns multiple LUA data variables.
• toXML(…), convert the multiple LUA parameters given in a XML format (see XML data compatibility (XML parser) to know how XML/LUA conversion works). It returns a string which contain data converted.
• fromXMLRPC(data), convert the XML-RPC data given in parameter in multiple LUA types relating (see XML-RPC to LUA conversions to know how XMLRPC/LUA conversion works). It returns multiple LUA data variables.
• toXMLRPC(…), convert the multiple LUA parameters given in a XML-RPC format (see XML-RPC to LUA conversions to know how XMLRPC/LUA conversion works). It returns a string which contain data converted.
• md5(…), computes and returns the MD5 values from input values given as arguments.
• sha256(…), computes and returns the SHA256 values from input values given as arguments.
• split(expression,separator[,option]), LUA has not real split operator, this function fills this gap. It splits the expression in relation with the separator term given, and returns tokens as a multiple result. A optional number argument indicates if you want to ignore empty tokens (option =1), or to remove leading and trailing whitespace from tokens (option =2), or the both in same time (option =3).
• listPaths(dirName), return a LUA table containing objects of type File in the dirName directory (relative to the www path).
• joinGroup(peerID, groupID), add Client with peerID to Group with groupID.
• time(), gives the epoch time (since the Unix epoch, midnight, January 1, 1970) in milliseconds.
• dump(data[, size]), dump data to the console and log file, if size is not specified it dump all the data.

Example of access to a Mona global function :

# Print congiguration array in a JSON format
INFO(mona:toJSON(mona.configs))

methods¶

• (id/rawId), return a Client object, it can take the id client parameter in a string format or a raw hex format.

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 URL connection, it gives server application related (see Server Application).
• ping (read-only), client ping value.
• lastReceptionTime (read-only), time of last data reception.
• protocol (read-only), client protocol name (HTTP, WebSocket, RTMP or RTMFP).
• query (read-only), query part of the url (used in HTTP).
• writer (read-only), the main Writer to communicate with the client.
• properties (read-only), dynamic properties of the client connection, depends on the protocol (see Specific Protocol Features).
• parameters (read-only), static parameters/configuration of the client protocol (parameters can be substituated by protocol name).

In client.properties the word properties can be omitted to access directly to client’s attributes. Here is a sample with an RTMFP connection :

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

function onConnection(client,...)
  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 for more details).

events¶

• onAddressChanged(oldAddress), happen on client.address change (can happen for an UDP based protocol like RTMFP).
• onJoinGroup(group), happen when the client join a P2P Group (RTMFP - NetGroup).
• onUnjoinGroup(group), happen when the client leaves a P2P Group (RTMFP - NetGroup).
• onPublish(publication), happen on Publication starts.

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 client:onPublish(publication)
  if not client.right then
    error("no rights to publish it")
  end

  function publication:onData(time,packet)
    -- write code here
  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;
  }
}

• onUnpublish(publication), happen on Publication stops.

• onSubscribe(listener), happen on publication subscription, Listener argument describes this subscription.

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

function client:onSubscribe(listener)
  if not client.right then
    error("no rights to play it")
  end
end

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

• onUnsubscribe(listener), happen on publication unsubscription, Listener argument describes the abandoned subscription.

• onRead(file,parameters…)

This event is used with HTTP protocol.

Called when a client try to read a file on the server. The file should exists. Parameters should be used to perform REST functionnalities.

You can also reject the connexion like this :

function client:onRead(file)
  if file ~= "index.html" then
    error("Access to file is forbidden)
  end
end

You can redirect to another file returning the file name as first parameter :

function client:onRead(file)
  return "newFile"
end

Other parameters are treated as values for replacing templates <% property %> in file. So with the script below each <% name %> element will be replaced by “robert” :

function client:onRead(file)
  return file, {name="robert"}
end

If you need to return a custom response you can return nil and write you response using the writer as below:

function client:onRead(file,parameters)
  self.writer:writeRaw("hello"); -- my custom response
  return nil
end

properties¶

• reliable, boolean to make communication server to client reliable or not. In a no-reliable case, the packet can be lost but are transfered more faster than in a reliable case. By default reliable=true.

function onConnection(client,...)
  client.writer.reliable = false
  client.writer.writeInvocation("method","hello")  -- packet more fast but can be lost
  client.writer.reliable = true
end

_netStream.dataReliable = false
_netStream.send("method","hello") -- packet more fast but can be lost

About stream publication it’s done like that:

_netStream.audioReliable = false
_netStream.videoReliable = false
_netStream.publish("myStream")

And about stream subscription you opt for a no-reliable mode like that:

_netStream.play("myStream?unbuffered=true")

Here the server will stream in a no-reliable way and without buffering, it can improve significantly performances and better cope with congestion.

methods¶

• writeRaw(…), write a result for an invocation client call, it takes multiple LUA variables as argument to convert it to AMF and send it to the client (see AMF to LUA conversions to know how AMF/LUA conversion works).
• writeMessage(…), write a result for an invocation client call, it takes multiple LUA variables as argument to convert it to the output format and send it to the client (see AMF to LUA conversions to know how AMF/LUA conversion works).
• writeInvocation(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 to AMF and send it to the client (see AMF to LUA conversions 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.
• flush([full]), fill queueing data to sending buffer to the pipe without waiting anymore. Helpful in some special real-time sending case with an important flow rate, to control sending. By default the sending is complete and immediate (full=true), however if the optional full argument equals false it sends only the UDP packets where no more data can be written (maximum size reached), but keep the last writing suspended. It can be usefull when you use several writers, and that you want flush their data with a certain order: you call flush(false) on all the writers, and to finish a flush() final to send last suspended data.
• newWriter(), create a new writer communication pipe and returns it.
• close(), close the communication pipe. In the case where you close a writer creating by yourself (in calling client.writer:newWriter()), it closes the writer and you must not use anymore the writer object which is going to be deleted. In the case where you close the main writer of its client (client.writer:close()) it closes the entiere client session.

events¶

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

methods¶

• (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).
• join(peerId,groupId), add the peerId in the group groupId. This feature acts on the NetGroup members exchange (rendezvous service), it doesn’t add the client with for id peerId in the group, it adds the peerId value as a virtual member of the group. For this reason, you have to be sure that this peer exists somewhere and has joined this group. Indeed, it’s used just in multiple-servers case (see Scalability and load-balancing page). On success it returns a Member object related.

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.
• members (read-only), the list of Clients in the group.

methods¶

• size(), return the number of client of the group.

properties¶

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

methods¶

• release(), unjoin its group, its existence has no more meaning.

properties¶

• lostRate (read-only), value between 0 and 1 to indicate the lost data rate.
• byteRate (read-only), byte rate (bytes per second).
• latency (read-only), delay in milliseconds between data sending and receiving.
• lastSendingTime (read-only), last time a frame has been sent.

methods¶

• (name), return a Publication object, it can take the name of the Publication in argument.

properties¶

• name (read-only), name of the publication
• lastTime (read-only), returns the last media time published.
• droppedFrames (read-only), return the number of dropped video frames till the publication is alive. Frames are dropped when at least one fragment is lost.
• listeners (read-only), Listeners which have subscribed for this publication.
• audioQOS (read-only), QualityOfService object about audio transfer for this publication.
• videoQOS (read-only), QualityOfService object about video transfer for this publication.
• dataQOS (read-only), QualityOfService object about data transfer for this publication.
• running (read-only), true if the publication is running.
• properties (read-only), returns publication properties (metadata).

methods¶

• writeProperties(properties), set publication properties (write metadata).
• clearProperties(), clear publication properties (clear metadata).
• pushAudio(time,packet[,ping]), 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. And the last optional argument is to increment the latency counter (it’s used by QualityOfService object).
• pushVideo(time,packet[,ping]), 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. And the last optional argument is to increment the latency counter (it’s used by QualityOfService object).
• pushAMFData(…), push data to this publication. The arguments passed are serialized in AMF.
• pushAMF0Data(…), push data to this publication. The arguments passed are serialized in AMF0.
• pushXMLRPCData(…), push data to this publication. The arguments passed are serialized in XMLRPC.
• pushJSONData(…), push data to this publication. The arguments passed are serialized in JSON.
• pushData(…), push data to this publication. The arguments passed are just raw concatenated (no typed serialization).
• 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 mona.publish function (see Mona object), 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.

events¶

• onVideo(time,packet), call on video packet reception for one Publication. time is the time in milliseconds of this packet in the stream, and packet contains video data.
• onAudio(time,packet), call on audio packet reception for one Publication. time is the time in milliseconds of this packet in the stream, and packet contains video data.
• onData(packet), call on data packet reception for one Publication. packet contains raw data.
• onFlush(), call on publication flush.

properties¶

• client (read-only), refers to the Client object which is listening.
• audioQOS (read-only), QualityOfService object about audio transfer for this subscription.
• videoQOS (read-only), QualityOfService object about video transfer for this subscription.
• dataQOS (read-only), QualityOfService object about data transfer for this subscription.
• publication (read-only), Publication object which describes publication listening by the subscriber.
• parameters (read-only), an array containing the url query parameters after the name of the publication (publicationName?arg1=1&arg2=test).
• receiveAudio, boolean to mute audio reception on the subscription.
• receiveVideo, boolean to mute video reception on the subscription.

properties¶

• initiators (read-only), return a Broadcaster object including the server initiators. Server connections have a direction, with an iniator of the connection, and a target of the connection (see Scalability and load-balancing page for more details).
• targets (read-only), return a Broadcaster object including the server targets. Server connections have a direction, with an iniator of the connection, and a target of the connection (see Scalability and load-balancing page for more details).

methods¶

• broadcast(handler,…), broadcast data to servers (initiators and targets). The handler parameter is the name of the remote procedure call method to receive data, multiple arguments following are the data (see Scalability and load-balancing page for more details).
• (address/index), return a Server object. It can take the address of the server (string format) or the index of server (number format) as input argument. Indeed the list is sorted by order of connections.

properties¶

• address (read-only), object address of the server.
• host (read-only), hostname of the server.
• port (read-only), port used for the server-to-server connection.
• isTarget (read-only), true if the server is a target of current server.
• configs (read-only), configuration properties of the server (see Configurations).

methods¶

• send(handler[,parameters]), call a method of the server.
• reject([message]), disconnect from the server.

You can add some methods into a Server object to create RPC functions availables from other servers (see Scalability and load-balancing page for more details).

properties¶

• count (read-only), number of servers.

methods¶

• broadcast(handler,…), broadcast data to servers. The handler parameter is the name of the remote procedure call method to receive data, multiple arguments following are the data (see Scalability and load-balancing page for more details).
• (address/index), return a Server object. It can take the address of the server (string format) or the index of server (number format) as input argument. Indeed the list is sorted by order of connections.

properties¶

• name (read-only), name of the file
• baseName (read-only), name of the file, without extension
• parent (read-only), name of the parent directory
• extension (read-only), extension of the file
• size (read-only), size of the file
• lastModified (read-only), date of last modification (in seconds)
• isFolder (read-only), true if the file is a directory
• value (read-only), full path of the file

properties¶

• isWildcard (read-only), true if this address is the wildcard address (all zero)
• isBroadcast (read-only), true if this address is the local network broadcast address (255.255.255.255, only IPv4 addresses can be broadcast addresses)
• isAnyBroadcast (read-only), true if this address is a broadcast address (only IPv4 addresses can be broadcast addresses)
• isLoopback (read-only), true if this address is a loopback address
• isMulticast (read-only), true if this address is a multicast address (224.0.0.0 to 239.255.255.255 for IPv4, FFxx:x:x:x:x:x:x:x range for IPv6)
• isUnicast (read-only), true if this address is a unicast address (if it is neither a wildcard, broadcast or multicast address)
• isLinkLocal (read-only), true if this address is a link local unicast address (169.254.0.0/16 range for IPv4, FE80:: for IPv6)
• isSiteLocal (read-only), true if this address is a a site local unicast address (10.0.0.0/24, 192.168.0.0/16 or 172.16.0.0 to 172.31.255.255 ranges for IPv4, FEC0:: for IPv6
• isIPv4Compatible (read-only), true if this address is IPv4 compatible (for IPv6 the address must be in the ::x:x range)
• isIPv4Mapped (read-only), true if this address is an IPv4 mapped IPv6 address (For IPv6, the address must be in the ::FFFF:x:x range)
• isWellKnownMC (read-only), true if this address is a well-known multicast address (224.0.0.0/8 range for IPv4, FF0x:x:x:x:x:x:x:x range for IPv6)
• isNodeLocalMC (read-only), true if this address is a node-local multicast address (always false for IPv4, in the FFx1:x:x:x:x:x:x:x range for IPv6)
• isLinkLocalMC (read-only), true if this address is a link-local multicast address (224.0.0.0/24 range for IPv4, FFx2:x:x:x:x:x:x:x range for IPv6)
• isSiteLocalMC (read-only), true if this address is a site-local multicast address (239.255.0.0/16 range for IPv4, FFx5:x:x:x:x:x:x:x for IPv6)
• isOrgLocalMC (read-only), true if this address is an organization-local multicast address (239.192.0.0/16 range for IPv4, FFx8:x:x:x:x:x:x:x range for IPv6)
• isGlobalMC (read-only), true if this address is a global multicast address (224.0.1.0 to 238.255.255.255 range for IPv4, FFxF:x:x:x:x:x:x:x range for IPv6)
• isLocal (read-only), true if this address is local
• isIPv6 (read-only), true if this address is a IPv6 address
• value (read-only), the string representation of the address

properties¶

• host (read-only), the IPAddress object of this socket address
• port (read-only), the port of the socket address
• isIPv6 (read-only), true if the host is an IPv6 address
• value (read-only), the string representation of the socket address (host:port)