Instances of the NetGroup class represent membership in an RTMFP group. Use this class to do the following:
Monitor Quality of Service. The info property contains a NetGroupInfo object whose properties provide QoS statistics for this group.
Posting. Call NetGroup.post() to broadcast ActionScript messages to all members of a group.
Direct routing. Call sendToNearest(), sendToNeighbor(), and sendToAllNeighbors() to send a short data message to a specific member of a peer-to-peer group. The source and the destination do not need to have a direct connection.
Ingest a multicast stream. Call getMulticastStreamIngest() to ingest a multicast RTMFP stream from a group.
For more information, see Building peer-assisted networking applications in the Adobe Media Server Developer’s Guide.
NetGroup class constructor
netGroup = new NetGroup(connection, groupspec)
Constructs a NetGroup on the specified NetConnection object and joins it to the group specified by the groupspec parameter. Use the GroupSpecifier class to build the groupspec string. In Server-Side ActionScript, you can pass a groupspec String or a GroupSpecifier object as the groupspec argument. The NetConnection must use the RTMFP protocol.
Throws an Error if either argument is missing or null, if the NetGroup fails to join the group specified in the groupspec parameter, or if the protocol is not RTMFP.
The status messages are dispatched to NetGroup.onStatus().
Availability
Flash Media Server 4
Parameters
connection
A NetConnection object. The protocol must be RTMFP.
groupspec
To publish or play a stream in a peer-to-peer multicast group, specify a groupspec string or a GroupSpecifier object. To create a groupspec string, call GroupSpecifier.toString().
Example
The following example passes a GroupSpecifier object as the groupspec parameter:
netGroup = new NetGroup(myConnection, myGroupSpecifier);
The following example passes a GroupSpecifier string as the groupspec parameter:
netGroup = new NetGroup(myConnection, myGroupSpecifier.toString());
NetGroup.addMemberHint()
netGroup.addMemberHint(peerID)
Manually adds a record specifying that peerID is a member of the Group. An immediate connection to it is attempted only if it is needed for the topology.
Availability
Flash Media Server 4
Parameters
peerID
A String. The peerID to add to the set of potential neighbors.
Returns
A Boolean value. If successful, returns true. Otherwise, returns false.
NetGroup.addNeighbor()
netGroup.addMemberHint(peerID)
Manually adds a neighbor by immediately connecting directly to the specified peerID, which must already be in this Group. This direct connection may later be dropped if it is not needed for the topology.
Availability
Flash Media Server 4
Parameters
peerID
A String. The peerID to which to connect.
Returns
A Boolean value. If successful, returns true. Otherwise, returns false.
NetGroup.addPermanentNeighborByName()
netGroup.addPermanentNeighborByName(rtmfpEndpointName:String, addresses:Array);
Manually adds a neighbor, by RTMFP endpoint name, which must already be in this group via a NetGroup instance constructed using a NetConnection that has been assigned the target RTMFP endpoint name. Unlike addNeighbor(), this direct connection is permanent.
Throws an error if any argument is of the wrong type or missing, or if address values within the addresses argument are incorrectly formatted.
Availability
Flash Media Server 4.5
Parameters
rtmfpEndpointName
A String. The name assigned to the RTMFP protocol stack at the target peer. See NetConnection.rtmfpEndpointName.
addresses
An Array of address Strings specifying the IPv4 or IPv6 addresses where the target peer is running, followed by a colon (":") and port number. If specifying an IPv6 address and a port, enclose the IPv6 address in square brackets.
Returns
A Boolean value. If successful, returns true. Otherwise, returns false.
Example
The following example adds a neighbor with the RTMFP endpoint name bootstrap-peer, using a known address where the peer is running:
ng.addPermanentNeighborByName("bootstrap-peer", [bootstrapPeerAddress]);
NetGroup.close()
netGroup.close()
Disconnect from the group and close this NetGroup. This NetGroup is not usable after calling this method.
Availability
Flash Media Server 4
Parameters
None.
Returns
None.
NetGroup.convertPeerIDToGroupAddress()
netGroup.convertPeerIDToGroupAddress(peerID)
Converts a peerID to a group address to pass to the sendToNearest() method.
Availability
Flash Media Server 4
Parameters
peerID
A String. The peerID to convert
Returns
A String. The group address for the peerID..
NetGroup.getMulticastStreamIngest()
netGroup.getMulticastStreamIngest(sourceStreamName)
A factory function used to construct a MulticastStreamIngest class. Call this function to ingest a multicast stream from an RTMFP group.
It’s a good idea to call getMulticastStreamIngest() in response to a "NetGroup.MulticastStream.PublishNotify event". Alternately, you could decide how long to wait for receipt of multicast stream bytes and use setInterval() to close down the ingest attempt.
This class throws an error if the stream parameter is not a String. If the stream name is incorrect (but is a String), it will not throw an error. For example, if you specify a sourceStreamName that isn't currently being published into the Group, you will not receive an error. Multicast streams within a Group do not necessarily have a sole source or owner, so there's no single peer to contact to determine whether the stream name is valid or not.
If this is an issue for your application, consider checking whether the returned MulticastStreamIngest object is ingesting on an interval and logging a failure after an application-defined timeout.
Availability
Flash Media Server 4.5
Parameters
sourceStreamName
A String. The name of the source multicast stream.
Returns
If a MulticastStreamIngest instance already exists for this group with this stream name, it returns the existing one, otherwise it creates a new MulticastStreamIngest instance.
Example
The following example is pseudocode that provides a high-level description of how to ingest a multicast stream, convert it into a Stream object, record it, and play it.
// First, set up Stream instance that will play (and record) the multicast ingest.
var stream = Stream.get("mp4:multicast-ingest.f4v");
// Next, set up a server-side NetConnection and NetGroup to join the Flash Group
// where the desired multicast stream is being published.
var nc = new NetConnection();
nc.onStatus = function(info) {
if (info.code == "NetConnection.Connect.Success") {
ng = new NetGroup(nc, groupspec);
ng.onStatus = ngStatusHandler;
}
};
nc.connect("rtmfp://<ams-introduction-server>...");
// Handle NetGroup status events; this simple example handles only the initial join.
function ngStatusHandler(info) {
if (info.code == "NetGroup.Connect.Success") {
// As soon as we've successfully joined the Group,
// attempt to start ingesting a multicast stream.
// Assume we know the stream name we want to ingest (sourceStreamName).
ingest = ng.getMulticastStreamIngest(sourceStreamName);
}
}
// At some later point (or directly in the ngStatusHandler above),
// play the multicast ingest.
stream.playFromGroup(ingest);
// The stream can be recorded locally.
stream.record();
...
stream.record(false); // And recording stopped.
// To stop playback of a multicast stream, pass the Boolean false.
stream.playFromGroup(false);
NetGroup.estimatedMemberCount
groupSpecifier.estimatedMemberCount
Read-only; A Number specifying the estimated number of members of the group, based on local neighbor density and assuming an even distribution of group addresses.
Availability
Flash Media Server 4
NetGroup.info
groupSpecifier.info
Read-only; a NetGroupInfo object whose properties provide Quality of Service statistics related to this NetGroup's RTMFP peer-to-peer data transport.
Availability
Flash Media Server 4
NetGroup.localCoverageTo
groupSpecifier.localCoverageTo
Read-only; Specifies the end of the range of group addresses for which this node is the “nearest” and responsible. The range is specified in the increasing direction along the group address ring mod 2256.
Availability
Flash Media Server 4
NetGroup.localCoverageFrom
groupSpecifier.localCoverageFrom
Read-only; Specifies the start of the range of group addresses for which this node is the “nearest” and responsible. The range is specified in the increasing direction along the group address ring mod 2256.
Availability
Flash Media Server 4
NetGroup.onStatus()
netGroup.onStatus = function(infoObject){})
Invoked every time a status change or error occurs in a NetGroup object.
Availability
Flash Media Server 4
Parameters
infoObject
An Object with code and level properties that provide information about the status of a NetGroup call. Both properties are strings.
Code property |
Level property |
Description |
|---|---|---|
"NetGroup.Connect.Failed" |
"error" |
The creation of or connection to a NetGroup has failed. For example, this code is sent if there is an error in the GroupSpecifier. |
"NetGroup.Connect.Success" |
"status" |
A NetGroup was created successfully. |
"NetGroup.LocalCoverage.Notify" |
"status" |
Sent when a portion of the group address space for which this node is responsible changes. |
"NetGroup.MulticastStream.PublishNotify" |
"status" |
A NetStream has started publishing into a group. |
"NetGroup.MulticastStream.UnpublishNotify" |
"status" |
A NetStream has stopped publishing into a group. |
"NetGroup.Neighbor.Connect" |
"status" |
Sent when a neighbor connects to this node. There are two additional properties: e.info.neighbor, a String specifying the group address of the neighbor. e.info.peerID, a String specifying the peerID of the neighbor. |
"NetGroup.Neighbor.Disconnect" |
"status" |
Sent when a neighbor disconnects to this node. There are two additional properties: e.info.neighbor, a String specifying the group address of the neighbor. e.info.peerID, a String specifying the peerID of the neighbor. |
"NetGroup.Posting.Notify" |
"status" |
Dispatched when the group receives a message from the NetGroup.post() method. There are two additional properties: info.message, an Object containing the message, and info.messageID, a String containing the message's messageID. |
"NetGroup.SendTo.Notify" |
"status" |
Dispatched when a message sent directly to this node is received. The info.message property is an Object containing the message. The info.from property is a String specifying the groupAddress from which the message was received. The info.fromLocal property is a Boolean value. The value is true if the message was sent by this node (the local node is the node closest to the destination group address), and false if the message was received from a different node. To implement recursive routing, if info.fromLocal is false, call NetGroup.sendToNearest() to resend the message. |
Example
var netGroup = new NetGroup(nc, myGroupSpecifier);
netGroup.onStatus = function(info){
if (info.code == "NetGroup.Connect.Success"){
trace("Successful NetGroup connection");
}
}
NetGroup.post()
netGroup.post(message)
If authorized, sends the message to all other members of the group. All messages must be unique; a message that is identical to one posted earlier might not be propagated.
This method returns the messageID for this message, or null on error. The messageID is the hex of the SHA256 of the raw bytes of the serialization of the message.
This method sends "NetGroup.Posting.Notify" to NetStream.onStatus() with two additional properties: e.info.message, an Object containing the message, and e.info.messageID, a String containing the message's messageID.
For more information, see Post messages to a groupin the Adobe Media Server Developer’s Guide.
Availability
Flash Media Server 4
Parameters
message
An Object. The message to send to all other members of the group. The message can be an Object, an int, a Number, or a String.
Returns
A String. The messageID of the message if posted, or null on error.
NetGroup.receiveMode
groupSpecifier.receiveMode
Specifies the routing receive mode for this node. Use a property of the NetGroupReceiveMode class. The value can be either NetGroupReceiveMode.EXACT or NetGroupReceiveMode.NEAREST. See the NetGroupReceiveMode class for more information.
Availability
Flash Media Server 4
NetGroup.removePermanentNeighborByName()
netGroup.removePermanentNeighborByName(rtmfpEndpointName:String);
Manually removes the "permanent" status for a neighbor by RTMFP endpoint name. This method call does not cause an existing neighbor connection to be dropped immediately. However, if either end chooses to drop the connection at a future point the drop is allowed.
Throws an error if any argument is of the wrong type or missing.
Availability
Flash Media Server 4.5
Parameters
rtmfpEndpointName
A String. The name assigned to the RTMFP protocol stack at the target peer. See NetConnection.rtmfpEndpointName.
Returns
A Boolean value. If successful, returns true. Otherwise, returns false.
Example
The following example removes the “permanent” status of a neighbor with the RTMFP endpoint name bootstrap-peer:
ng.removePermanentNeighborByName("bootstrap-peer");
NetGroup.sendToAllNeighbors()
netGroup.sendToAllNeighbors(message)
Sends a message to all neighbors. Returns NetGroupSendResult.SENT if at least one neighbor was selected.
When a node receives a message, a "NetGroup.SendTo.Notify" is sent to the NetStream.onStatus() method.
Use this method to route messages directly to a peer, also called “direct routing”. See Route messages directly to a peer.
Availability
Flash Media Server 4
Parameters
message
An Object. The message to send.
Returns
A String. A property of the NetGroupSendResult class indicating the success or failure of the send.
NetGroup.sendToNearest()
netGroup.sendToNearest(message, groupAddress)
Sends a message to the neighbor (or local node) nearest to the specified group address. Considers neighbors from the entire ring. Returns NetGroupSendResult.SENT if the message was successfully sent toward its destination.
When a node receives a message, "NetGroup.SendTo.Notify" is sent to the NetStream.onStatus() method.
Use this method to route messages directly to a peer, also called “direct routing”. See Route messages directly to a peer.
Availability
Flash Media Server 4
Parameters
message
An Object. The message to send.
groupAddress
A String. The group address toward which to route the message.
Returns
A String. A property of the NetGroupSendResult class indicating the success or failure of the send.
NetGroup.sendToNeighbor()
netGroup.sendToNeighbor(message, sendMode)
Sends a message to the neighbor specified by the sendMode parameter. Returns NetGroupSendResult.SENT if the message was successfully sent to the requested destination.
When a node receives a message, a "NetGroup.SendTo.Notify" is sent to the NetStream.onStatus() method.
Use this method to route messages directly to a peer, also called “direct routing”. See Route messages directly to a peer.
Availability
Flash Media Server 4
Parameters
message
An Object. The message to send.
sendMode
A String. A property of enumeration class NetGroupSendMode specifying the neighbor to which to send the message.
Returns
A String. A property of the NetGroupSendResult class indicating the success or failure of the send.
