Roster Class Reference

#include <Roster.h>

List of all members.

---

Detailed Description

The Roster provides facilities for Clients of the DTPF, and for Nodes.

The primary Client we envision for the DTPF is a graphical user interface which will provide access to the Roster facilities for end-users. Roster facilities will include: obtaining a list of Nodes that can be loaded, loading a Node, determining the Format Models accepted for input by Nodes or produced as output by Nodes. The Roster also enables communication connections to be established between pairs of nodes.

Clients access the Roster through the RosterClientInterface. This provides a messaging interface to the Roster. The Roster is implemented as a separate heavy weight process (HWP).

Public Member Functions
	Roster (muscle::String nodeDirectory)
	The constructor for the Roster is used only by the HWP that implements the Roster.
muscle::Message *	GetPluginNodes ()
muscle::Message *	GetRegisteredNodes ()
status_t	LoadPluginNode (muscle::String nodeName)
	Attempts to load an instance of the Node given by NodeName.
status_t	UnloadPluginNode (NodeID id)
	If the Node given by the NodeID has been previously loaded, and registered, and that Node is currently in a stopped state, then the roster attempts to unload that Node.
status_t	GetParameters (NodeID id, muscle::Message *parameters)
	These methods enable the parameters for a registered Node to be obtained or modified.
status_t	SetParameters (NodeID id, muscle::Message parameters)
status_t	StartNode (NodeID nid)
	Change the state of the node.
status_t	StopNode (NodeID nid)
status_t	GetNodeState (NodeID id, NodeState *state)
	Get the current state of the node.
status_t	GetConnectionEndpoints (NodeID id, muscle::Message **connectionEndpoints)
	Enables a Client to determine the ConnectionEndpoints for a registered Node.
status_t	ConnectNodes (EndpointID upstreamNode, EndpointID downstreamNode, muscle::Message *formatModel)
	Attempts to connect an upstream Node to a downstream Node in the given format.
status_t	DisconnectNodes (EndpointID upstreamNode, EndpointID downstreamNode)
	Attempts to disconnect an upstream Node from a downstream Node.
status_t	RegisterNode (muscle::Message *connectionEndpoints, NodeID *nid)
	Attempts to register a Node.
status_t	UnregisterNode (NodeID nid)
	Attempts to unregister a node.

---

Constructor & Destructor Documentation

Roster::Roster (  muscle::String  nodeDirectory  )

The constructor for the Roster is used only by the HWP that implements the Roster. Parameters: NodeDirectory  gives the directory to search for plugin Nodes.

---

Member Function Documentation

status_t Roster::ConnectNodes (  EndpointID  upstreamNode, EndpointID  downstreamNode, muscle::Message *  formatModel )

Attempts to connect an upstream Node to a downstream Node in the given format. Parameters: upstreamNode  is the EndpointID for the upstream node ConnectionEndpoint. The name of the field is "UpstreamEndpoint". downstreamEndpoint  also is a EndpointID but for the downstream node ConnectionEndpoint. The name of this field is "DownstreamEndpoint". formatModel  specifies the requested communication format between the two nodes. If the Nodes can be connected, this call may implictly create a BufferGroup for the communication between the Nodes. A BufferGroup will not be created if this is a broadcast connection. I.e., if the upstream node is being connected to multiple downstream nodes, and one connection from that node to a downstream node has already been connected. In this case, the BufferGroup will be re-used. BufferGroups used for broadcast connections will be read-only, other BufferGroups will be read-write. Returns: E_OK if the connection could be established. E_BAD_FORMAT if the Nodes could not process the requested FormatModel.

status_t Roster::DisconnectNodes (  EndpointID  upstreamNode, EndpointID  downstreamNode )

Attempts to disconnect an upstream Node from a downstream Node. Parameters: upstreamNode  is the EndpointID for the upstream node ConnectionEndpoint. The name of the field is "UpstreamEndpoint". downstreamEndpoint  also is a EndpointID but for the downstream node ConnectionEndpoint. The name of this field is "DownstreamEndpoint". Returns: E_OK if the connection could be established.

status_t Roster::GetConnectionEndpoints (  NodeID  id, muscle::Message **  connectionEndpoints )

Enables a Client to determine the ConnectionEndpoints for a registered Node. See RegisterNode for the format of the Message.

status_t Roster::GetNodeState (  NodeID  id, NodeState *  state )

Get the current state of the node. The State can be: Starting, Started, Stopping, Stopped. Returns: E_OK if the operation could be performed, and the NodeState.

status_t Roster::GetParameters (  NodeID  id, muscle::Message *  parameters )

These methods enable the parameters for a registered Node to be obtained or modified. Parameters: parameters  returns or provides the set of parameters. This is a list of Flattened ParameterModel's, each with a field name of "ParameterModel". Returns: E_OK if the operation could be completed, and in the case of the "Get" method, returns the parameters.

muscle::Message* Roster::GetPluginNodes (   )

Returns: muscle::Message containing a list of the Nodes that may be loaded as plugins. This will be NULL if the call was unsuccessful. Nodes can be implemented as shared libraries ("plugins") that have been programmed for DTPF usage. (Or they can be implemented as statically linked-- but these Nodes will not be returned in a call to GetNodes). The Roster searches the directory given to the constructor for Nodes. The message fields are muscle::String's, and the names of the String's are each "NodeName". There may be 0 Nodes-- i.e., if no Nodes exist in the directory specified. The caller owns (and should deallocate) the returned Message.

muscle::Message* Roster::GetRegisteredNodes (   )

Returns: muscle::Message containing a list of Nodes that have already been registered with the Roster. This will be NULL if the call was unsuccessful. Nodes that can be returned by this call include those that are returned in a call to GetNodes. (Nodes implemented via a static linking method and that have been registered will be included here, but will not be seen in a call to GetNodes). The message fields are Flattened NodeDescriptors. The names of fields are "NodeDescriptor". There may be 0 Nodes-- i.e., if no Nodes have been registered. The caller owns (and should deallocate) the returned Message.

status_t Roster::LoadPluginNode (  muscle::String  nodeName  )

Attempts to load an instance of the Node given by NodeName. An instance of the object is created using its constructor. It is a responsiblity of the Node to register itself (e.g., in its constructor; see method RegisterNode on this interface). The nodeName should be one of those returned from a call to GetPluginNodes. It depends on the semantics of the Node whether multiple instances of the specific Node can be loaded at the same time. For example, Nodes that read from hardware devices may be constrained to having only one instance loaded. Returns: E_OK if the Node is now loaded. Note that the loaded node is not yet registered (see the RegisterNode method). The Node will be in a stopped state.

status_t Roster::RegisterNode (  muscle::Message *  connectionEndpoints, NodeID *  nid )

Attempts to register a Node. It is assumed that the FormatModel's of the ConnectionEndpoint's for a Node do not change while a node is instantiated. As a part of registering a Node, communications are established with the Node's event looper, so that the Roster can send messages to the event looper for the Node. Part of the Registration procedure thus starts the event looper for a Node. Returns: E_OK if the Node could be successfully registered. In that case, nid will be returned with a unique identifier for the registered Node instance, and will be valid until the Node is explicitly unloaded (for plugin nodes only), or the node terminates in some other manner. Successfully registered nodes still have a state of "Stopped". Parameters: connectionEndpoints  gives a muscle::Message with the ConnectionEndpoint's for the Node. The Message contains a list of Flattened ConnectionEndpoint's in its fields. The names of the fields should be "ConnectionEndpoint". A ConnectionEndpoint can be used to connect one Node (an upstream node, for output) to another Node (a downstream node, for input). In general a Node can accept N inputs and M outputs, and this call should return N + M ConnectionEndpoint's. After this method is called the Roster owns (and should deallocate) the Message.

status_t Roster::SetParameters (  NodeID  id, muscle::Message  parameters )

status_t Roster::StartNode (  NodeID  nid  )

Change the state of the node. To Start a node, it must be in a Stopped state. To Stop a node, it must be in a Started state. Parameters: nid  is the NodeID for the Node to start or stop. Returns: E_OK if the operation could be performed.

status_t Roster::StopNode (  NodeID  nid  )

status_t Roster::UnloadPluginNode (  NodeID  id  )

If the Node given by the NodeID has been previously loaded, and registered, and that Node is currently in a stopped state, then the roster attempts to unload that Node. This call should not be used for nodes not implemented through dynamic linking. Returns: E_OK if the Roster was able to successfully unload the Node. In this case, the Node is no longer loaded into memory.

status_t Roster::UnregisterNode (  NodeID  nid  )

Attempts to unregister a node.

---

The documentation for this class was generated from the following file:

• App/Roster/Roster.h

---