StorageReflectSession Class Reference

An intelligent AbstractReflectSession that knows how to store data on the server, and filter using wildcards. More...

#include <StorageReflectSession.h>

Inheritance diagram for StorageReflectSession:


Public Member Functions
	StorageReflectSession ()
	Default constructor.
virtual	~StorageReflectSession ()
	Virtual Destructor.
virtual status_t	AttachedToServer ()
	Called after the constructor, when the session is ready to interact with the server.
virtual void	AboutToDetachFromServer ()
	Implemented to remove our nodes from the server-side database and do misc cleanup.
virtual void	MessageReceivedFromGateway (const MessageRef &msg, void *userData)
	Called when a new message is received from our IO gateway.
virtual void	AfterMessageReceivedFromGateway (const MessageRef &msg, void *userData)
	Overridden to call PushSubscriptionMessages().
virtual const char *	GetTypeName () const
	Returns a human-readable label for this session type: "Session".
virtual void	MessageReceivedFromSession (AbstractReflectSession &from, const MessageRef &msg, void *userData)
	Called when a message is sent to us by another session (possibly this one).
void	SetReflectToSelf (bool reflectToSelf)
	Set this true to enable self-reflection: if true, messages sent by a given client will be reflected back to that client.
bool	GetReflectToSelf () const
	Returns true iff our client's own messages will be bounced back to him.
const String &	GetHostName () const
	Returns the hostname of this client that is associated with this session.
uint16	GetPort () const
	Returns the server-side port that this session was accepted on, or 0 if we weren't accepted from a port (e.g.
const ip_address &	GetLocalInterfaceAddress () const
	Returns the server-side network interface IP that this session was accepted on, or 0 if we weren't created via accepting a network connection (e.g.
uint32	GetSessionID () const
	Returns a globally unique ID for this session.
const String &	GetSessionIDString () const
	Returns an ID string to represent this session with.
void	EndSession ()
	Marks this session for immediate termination and removal from the server.
bool	DisconnectSession ()
	Forces the disconnection of this session's TCP connection to its client.
status_t	ReplaceSession (const AbstractReflectSessionRef &newSession)
	Causes this session to be terminated (similar to EndSession(), and the session specified in (newSessionRef) to take its place using the same socket connection & message IO gateway.
virtual bool	ClientConnectionClosed ()
	Called when the TCP connection to our client is broken.
virtual void	AsyncConnectCompleted ()
	For sessions that were added to the server with AddNewConnectSession(), or AddNewDormantConnectSession(), this method is called when the asynchronous connect process completes successfully.
void	SetInputPolicy (const PolicyRef &newPolicy)
	Set a new input I/O policy for this session.
PolicyRef	GetInputPolicy () const
	Returns a reference to the current input policy for this session.
void	SetOutputPolicy (const PolicyRef &newPolicy)
	Set a new output I/O policy for this session.
PolicyRef	GetOutputPolicy () const
	Returns a reference to the current output policy for this session.
void	SetGateway (const AbstractMessageIOGatewayRef &ref)
	Installs the given AbstractMessageIOGateway as the gateway we should use for I/O.
const AbstractMessageIOGatewayRef &	GetGateway () const
	Returns a reference to our internally held message IO gateway object, or NULL reference if there is none.
virtual bool	HasBytesToOutput () const
	Should return true iff we have data pending for output.
virtual bool	IsReadyForInput () const
	Should return true iff we are willing to read more bytes from our client connection at this time.
virtual int32	DoInput (AbstractGatewayMessageReceiver &receiver, uint32 maxBytes)
	Called by the ReflectServer when it wants us to read some more bytes from our client.
virtual int32	DoOutput (uint32 maxBytes)
	Called by the ReflectServer when it wants us to push some more bytes out to our client.
virtual SocketRef	CreateDefaultSocket ()
	Socket factory method.
virtual DataIORef	CreateDataIO (const SocketRef &socket)
	DataIO factory method.
virtual AbstractMessageIOGatewayRef	CreateGateway ()
	Gateway factory method.
virtual uint64	GetPulseTime (uint64 now, uint64 sched)
	Overridden to support auto-reconnect via SetAutoReconnectDelay().
virtual void	Pulse (uint64 now, uint64 sched)
	Overridden to support auto-reconnect via SetAutoReconnectDelay().
virtual String	GetDefaultHostName () const
	May be overridden to return the host name string we should be assigned if no host name could be automatically determined by the ReflectServer (i.e.
String	GetSessionDescriptionString () const
	Convenience method -- returns a human-readable string describing our type, our hostname, our session ID, and what port we are connected to.
const ip_address &	GetAsyncConnectIP () const
	Returns the IP address we connected asynchronously to.
uint16	GetAsyncConnectPort () const
	Returns the remote port we connected asynchronously to.
virtual const String &	GetSessionRootPath () const
	Returns the node path of the node representing this session (e.g.
void	SetAutoReconnectDelay (uint64 delay)
	Sets the amount of time that should pass between when this session loses its connection (that was previously set up using AddNewConnectSession() or AddNewDormantConnectSession()) and when it should automatically try to reconnect to that same destination (by calling Reconnect()).
uint64	GetAutoReconnectDelay () const
	Returns the current automatic-reconnect delay period, as was previously set by SetAutoReconnectDelay().
bool	IsConnectingAsync () const
	Returns true iff we are currently in the middle of an asynchronous TCP connection.
bool	IsConnected () const
	Returns true iff this session is currently connected to our remote counterpart.
virtual void	MessageReceivedFromFactory (ReflectSessionFactory &from, const MessageRef &msg, void *userData)
	Called when a message is sent to us by a ReflectSessionFactory object.
bool	IsAttachedToServer () const
	Returns true if we are attached to the ReflectServer object, false if we are not.
ReflectServer *	GetOwner () const
	Returns the ReflectServer we are currently attached to, or NULL if we aren't currently attached to a ReflectServer.
void	SetOwner (ReflectServer *s)
	Sets the ReflectServer we are currently attached to.
void	IncrementRefCount () const
	Increments the counter and returns true iff the new value is zero.
bool	DecrementRefCount () const
	Decrements the counter and returns true iff the new value is zero.
void	SetManager (AbstractObjectManager *manager)
	Sets the recycle-pointer for this object.
AbstractObjectManager *	GetManager () const
	Returns this object's current recyler pointer.
uint32	GetRefCount () const
	Returns this object's current reference count.
status_t	PutPulseChild (PulseNode *child)
	Adds the given child into our set of child PulseNodes.
status_t	RemovePulseChild (PulseNode *child)
	Attempts to remove the given child from our set of child PulseNodes.
void	ClearPulseChildren ()
	Removes all children from our set of child PulseNodes.
bool	ContainsPulseChild (PulseNode *child) const
	Returns true iff the given child is in our set of child PulseNodes.
uint64	GetScheduledPulseTime () const
	Returns when this object wants its call to Pulse() scheduled next, or MUSCLE_TIME_NEVER if it has no call to Pulse() currently scheduled.
uint64	GetCycleStartTime () const
	Returns the run-time at which the PulseNodeManager started calling our callbacks.
void	SetSuggestedMaximumTimeSlice (uint64 maxUsecs)
	Sets the maximum number of microseconds that this class should allow its callback methods to execute for (relative to the cycle start time, as shown above).
uint64	GetSuggestedMaximumTimeSlice () const
	Returns the current suggested maximum duration of our time slice, or MUSCLE_TIME_NEVER if there is no suggested limit.
bool	IsSuggestedTimeSliceExpired () const
	Convenience method -- returns true iff the current value of the run-time clock (GetRunTime64()) indicates that our suggested time slice has expired.
void	CallMessageReceivedFromGateway (const MessageRef &msg, void *userData=NULL)
	This method calls MessageReceivedFromGateway() and then AfterMessageReceivedFromGateway().
Protected Types
typedef int(*)	PathMatchCallback (StorageReflectSession This, DataNode &node, void userData)
	This typedef represents the proper signature of a node-tree traversal callback function.
Protected Member Functions
virtual status_t	SetDataNode (const String &nodePath, const MessageRef &dataMsgRef, bool allowOverwriteData=true, bool allowCreateNode=true, bool quiet=false, bool addToIndex=false, const String *optInsertBefore=NULL)
	Create or Set the value of a data node.
virtual status_t	RemoveDataNodes (const String &nodePath, const QueryFilterRef &filterRef=QueryFilterRef(), bool quiet=false)
	Remove all nodes that match (nodePath).
status_t	SaveNodeTreeToMessage (Message &msg, const DataNode node, const String &path, bool saveData, uint32 maxDepth=MUSCLE_NO_LIMIT, const ITraversalPruner optPruner=NULL) const
	Recursively saves a given subtree of the node database into the given Message object, for safe-keeping.
status_t	RestoreNodeTreeFromMessage (const Message &msg, const String &path, bool loadData, bool appendToIndex=false, uint32 maxDepth=MUSCLE_NO_LIMIT, const ITraversalPruner *optPruner=NULL)
	Recursively creates or updates a subtree of the node database from the given Message object.
virtual status_t	InsertOrderedData (const MessageRef &insertMsg, Hashtable< String, DataNodeRef > *optRetNewNodes)
	Create and insert a new node into one or more ordered child indices in the node tree.
virtual bool	HasPrivilege (int whichPriv) const
	Returns true iff we have the given PR_PRIVILEGE_* privilege.
void	BounceMessage (uint32 errorCode, const MessageRef &msgRef)
	Returns the given Message to our client, inside an error message with the given error code.
void	Cleanup ()
	Removes our nodes from the tree and removes our subscriptions from our neighbors.
status_t	FindMatchingSessions (const String &nodePath, const QueryFilterRef &filter, Hashtable< const String *, AbstractReflectSessionRef > &retSessions, bool matchSelf, uint32 maxResults=MUSCLE_NO_LIMIT) const
	Convenience method: Adds sessions that contain nodes that match the given pattern to the passed-in Hashtable.
AbstractReflectSessionRef	FindMatchingSession (const String &nodePath, const QueryFilterRef &filter, bool matchSelf) const
	Convenience method: Same as FindMatchingsession(), but finds only the first matching session.
status_t	SendMessageToMatchingSessions (const MessageRef &msgRef, const String &nodePath, const QueryFilterRef &filter, bool matchSelf)
	Convenience method: Passes the given Message on to the sessions who match the given nodePath.
status_t	CloneDataNodeSubtree (const DataNode &sourceNode, const String &destPath, bool allowOverwriteData=true, bool allowCreateNode=true, bool quiet=false, bool addToTargetIndex=false, const String optInsertBefore=NULL, const ITraversalPruner optPruner=NULL)
	Convenience method (used by some customized daemons) -- Given a source node and a destination path, Make (path) a deep, recursive clone of (node).
virtual void	NotifySubscribersThatNodeChanged (DataNode &node, const MessageRef &oldData, bool isBeingRemoved)
	Tells other sessions that we have modified (node) in our node subtree.
virtual void	NotifySubscribersThatNodeIndexChanged (DataNode &node, char op, uint32 index, const String &key)
	Tells other sessions that we have changed the index of (node) in our node subtree.
virtual void	NodeChanged (DataNode &node, const MessageRef &oldData, bool isBeingRemoved)
	Called by NotifySubscribersThatNodeChanged(), to tell us that (node) has been created, modified, or is about to be destroyed.
virtual void	NodeIndexChanged (DataNode &node, char op, uint32 index, const String &key)
	Called by NotifySubscribersThatIndexChanged() to tell us how (node)'s index has been modified.
void	PushSubscriptionMessages ()
	Takes any messages that were created in the NodeChanged() callbacks and sends them to their owner's MessageReceivedFromSession() method for processing and eventual forwarding to the client.
void	PushSubscriptionMessage (MessageRef &msgRef)
	Auxilliary helper method for PushSubscriptionMessages().
void	DoGetData (const Message &getMsg)
	Executes a data-gathering tree traversal based on the PR_NAME_KEYS specified in the given message.
void	DoRemoveData (NodePathMatcher &matcher, bool quiet=false)
	Executes a node-removal traversal using the given NodePathMatcher.
void	SendGetDataResults (MessageRef &msg)
	Auxilliary helper function.
void	SetSubscriptionsEnabled (bool e)
	If set false, we won't receive subscription updates.
bool	GetSubscriptionsEnabled () const
	Returns true iff our "subscriptions enabled" flag is set.
DataNode *	GetDataNode (const String &path) const
	Convenience method: Uses the given path to lookup a single node in the node tree and return it.
DataNodeRef	GetNewDataNode (const String &nodeName, const MessageRef &initialValue)
	Call this to get a new DataNode, instead of using the DataNode ctor directly.
void	ReleaseDataNode (DataNode *node)
	Call this when you are done with a DataNode, instead of the DataNode destructor.
void	JettisonOutgoingResults (const NodePathMatcher *matcher)
	This method goes through the outgoing-messages list looking for PR_RESULT_DATAITEMS messages.
void	JettisonOutgoingSubtrees (const String *optMatchString)
	This method goes through the outgoing-messages list looking for PR_RESULT_SUBTREE messages.
DataNodeRef	GetSessionNode () const
	Returns a reference to our session node.
Message &	GetParameters ()
	Returns a reference to our parameters message.
DataNode &	GetGlobalRoot () const
	Returns a reference to the global root node of the database.
	DECLARE_MUSCLE_TRAVERSAL_CALLBACK (StorageReflectSession, PassMessageCallback)
	Macro to declare the proper callback declarations for the message-passing callback.
virtual status_t	AddOutgoingMessage (const MessageRef &ref)
	Adds a MessageRef to our gateway's outgoing message queue.
void	BroadcastToAllSessions (const MessageRef &msgRef, void *userData=NULL, bool includeSelf=true)
	Convenience method: Calls MessageReceivedFromSession() on all session objects.
void	BroadcastToAllFactories (const MessageRef &msgRef, void *userData=NULL)
	Convenience method: Calls MessageReceivedFromSession() on all installed session-factory objects.
status_t	Reconnect ()
	Closes this session's current TCP connection (if any), and creates a new TCP socket that will then try to asynchronously connect back to the previous socket's host and port.
const SocketRef &	GetSessionSelectSocket () const
	Convenience method: Returns the file descriptor associated with this session's DataIO class, or a NULL reference if there is none.
void	SetSessionRootPath (const String &p)
	Set by StorageReflectSession::AttachedToServer().
uint64	GetServerUptime () const
	Returns the number of milliseconds that the server has been running.
uint32	GetNumAvailableBytes () const
	Returns the number of bytes that are currently available to be allocated.
uint32	GetMaxNumBytes () const
	Returns the maximum number of bytes that may be allocated at any given time.
uint32	GetNumUsedBytes () const
	Returns the number of bytes that are currently allocated.
status_t	PutAcceptFactory (uint16 port, const ReflectSessionFactoryRef &factoryRef, const ip_address &interfaceIP=invalidIP, uint16 *optRetPort=NULL)
	Passes through to ReflectServer::PutAcceptFactory().
status_t	RemoveAcceptFactory (uint16 port, const ip_address &interfaceIP=invalidIP)
	Passes through to ReflectServer::RemoveAcceptFactory().
void	EndServer ()
	Tells the whole server process to quit ASAP.
Message &	GetCentralState () const
	Returns a reference to a Message that is shared by all objects in a single ReflectServer.
status_t	AddNewSession (const AbstractReflectSessionRef &session, const SocketRef &socket=SocketRef())
	Adds the given AbstractReflectSession to the server's session list.
status_t	AddNewConnectSession (const AbstractReflectSessionRef &session, const ip_address &targetIPAddress, uint16 port, uint64 autoReconnectDelay=MUSCLE_TIME_NEVER)
	Like AddNewSession(), only creates a session that connects asynchronously to the given IP address.
status_t	AddNewDormantConnectSession (const AbstractReflectSessionRef &ref, const ip_address &targetIPAddress, uint16 port, uint64 autoReconnectDelay=MUSCLE_TIME_NEVER)
	Like AddNewConnectSession(), except that the added session will not initiate a TCP connection to the specified address immediately.
const Hashtable< const String *, AbstractReflectSessionRef > &	GetSessions () const
	Returns our server's table of attached sessions.
AbstractReflectSessionRef	GetSession (uint32 id) const
	Looks up a session connected to our ReflectServer via its session ID string.
AbstractReflectSessionRef	GetSession (const String &id) const
	Looks up a session connected to our ReflectServer via its session ID string.
const Hashtable< IPAddressAndPort, ReflectSessionFactoryRef > &	GetFactories () const
	Returns the table of session factories currently attached to the server.
ReflectSessionFactoryRef	GetFactory (uint16) const
	Given a port number, returns a reference to the factory of that port, or a NULL reference if no such factory exists.
void	InvalidatePulseTime (bool clearPrevResult=true)
	Sets a flag to indicate that GetPulseTime() should be called on this object.
virtual void	BeginMessageReceivedFromGatewayBatch ()
	This method will be called just before MessageReceivedFromGateway() and AfterMessageReceivedFromGateway() are called one or more times.
virtual void	EndMessageReceivedFromGatewayBatch ()
	This method will be called just after MessageReceivedFromGateway() and AfterMessageReceivedFromGateway() have been called one or more times.
Friends
class	DataNode
class	StorageReflectSession::NodePathMatcher
	Our node class needs access to our internals too.
Classes
class	NodePathMatcher
	A slightly extended version of PathMatcher that knows how to handle DataNodes directly. More...
class	StorageReflectSessionSharedData
	This class holds data that needs to be shared by all attached instances of the StorageReflectSession class.

Detailed Description

An intelligent AbstractReflectSession that knows how to store data on the server, and filter using wildcards.

This class is used by the muscled server program to handle incoming connections. See StorageReflectConstants.h and/or "The Beginner's Guide.html" for details.

Definition at line 81 of file StorageReflectSession.h.

Member Typedef Documentation

typedef int(*) StorageReflectSession::PathMatchCallback(StorageReflectSession *This, DataNode &node, void *userData) [protected]

This typedef represents the proper signature of a node-tree traversal callback function.

Functions with this signature may be used with the NodePathMatcher::DoTraversal() method.

Parameters:

	This	The StorageReflectSession doing the traveral, as specified in the DoTraversal() call
	node	The DataNode that was matched the criteria of the traversal
	userData	the same value that was passed in to the DoTraversal() method.

Returns:: The callback function should return the depth at which the traversal should continue after the callback is done. So to allow the traversal to continue normally, return (node.GetDepth()), or to terminate the traversal immediately, return 0, or to resume the search at the next session, return 2, or etc.

Definition at line 185 of file StorageReflectSession.h.

Member Function Documentation

virtual status_t StorageReflectSession::AttachedToServer ( ) [virtual]

Called after the constructor, when the session is ready to interact with the server.

Returns:: B_NO_ERROR if everything is okay to go, B_ERROR if there was a problem setting up, or if the IP address of our client has been banned.

Reimplemented from ServerComponent.

Reimplemented in ThreadWorkerSession.

virtual status_t StorageReflectSession::SetDataNode	(	const String &	nodePath,
		const MessageRef &	dataMsgRef,
		bool	allowOverwriteData = `true`,
		bool	allowCreateNode = `true`,
		bool	quiet = `false`,
		bool	addToIndex = `false`,
		const String *	optInsertBefore = `NULL`
	)			`[protected, virtual]`

Create or Set the value of a data node.

Parameters:

	nodePath	Should be the path relative to the home dir (e.g. "MyNode/Child1/Grandchild2")
	dataMsgRef	The value to set the node to
	allowOverwriteData	Indicates whether existing node-data may be overwritten. If false, the method will fail if the specified node already exists.
	allowCreateNode	indicates whether new nodes may be created. (If false, the method will fail if any node in the specified node path doesn't already exist)
	quiet	If set to true, subscribers won't be updated regarding this change to the database.
	addToIndex	If set to true, this node will be inserted under its parent as a new indexed node, rather than doing the regular add/replace bit.
	optInsertBefore	If (addToIndex) is true, this may be the name of the node to insert this new node before in the index. If NULL, the new node will be appended to the end of the index. If (addToIndex) is false, this argument is ignored.

Returns:: B_NO_ERROR on success, or B_ERROR on failure.

virtual status_t StorageReflectSession::RemoveDataNodes	(	const String &	nodePath,
		const QueryFilterRef &	filterRef = `QueryFilterRef()`,
		bool	quiet = `false`
	)			`[protected, virtual]`

Remove all nodes that match (nodePath).

Parameters:

	nodePath	A relative path indicating node(s) to remove. Wildcarding is okay.
	filterRef	If non-NULL, we'll use the given QueryFilter object to filter out our result set. Only nodes whose Messages match the QueryFilter will be removed. Default is a NULL reference.
	quiet	If set to true, subscriber's won't be updated regarding this change to the database

Returns:: B_NO_ERROR on success, or B_ERROR on failure.

status_t StorageReflectSession::SaveNodeTreeToMessage	(	Message &	msg,
		const DataNode *	node,
		const String &	path,
		bool	saveData,
		uint32	maxDepth = `MUSCLE_NO_LIMIT`,
		const ITraversalPruner *	optPruner = `NULL`
	)			const `[protected]`

Recursively saves a given subtree of the node database into the given Message object, for safe-keeping.

(It's a bit more efficient than it looks, since all data Messages are reference counted rather than copied)

Parameters:

	msg	the Message to save the subtree into. This object can later be provided to RestoreNodeTreeFromMessage() to restore the subtree.
	node	The node to begin recursion from (i.e. the root of the subtree)
	path	The path to prepend to the paths of children of the node. Used in the recursion; you typically want to pass in "" here.
	saveData	Whether or not the payload Message of (node) should be saved. The payload Messages of (node)'s children will always be saved no matter what, as long as (maxDepth) is greater than zero.
	maxDepth	How many levels of children should be saved to the Message. If left as MUSCLE_NO_LIMIT (the default), the entire subtree will be saved; otherwise the tree will be clipped to at most (maxDepth) levels. If (maxDepth) is zero, only (node) will be saved.
	optPruner	If set non-NULL, this object will be used as a callback to prune the traversal, and optionally to filter the data that gets saved into (msg).

Returns:: B_NO_ERROR on success, or B_ERROR on failure (out of memory?)

status_t StorageReflectSession::RestoreNodeTreeFromMessage	(	const Message &	msg,
		const String &	path,
		bool	loadData,
		bool	appendToIndex = `false`,
		uint32	maxDepth = `MUSCLE_NO_LIMIT`,
		const ITraversalPruner *	optPruner = `NULL`
	)			`[protected]`

Recursively creates or updates a subtree of the node database from the given Message object.

(It's a bit more efficient than it looks, since all data Messages are reference counted rather than copied)

Parameters:

	msg	the Message to restore the subtree into. This Message is typically one that was created earlier by SaveNodeTreeToMessage().
	path	The relative path of the root node, e.g. "" is your home session node.
	loadData	Whether or not the payload Message of (node) should be restored. The payload Messages of (node)'s children will always be restored no matter what.
	appendToIndex	Used in the recursion to handle restoring indexed nodes. You will usually want to Leave it as false when you call this method.
	maxDepth	How many levels of children should be restored from the Message. If left as MUSCLE_NO_LIMIT (the default), the entire subtree will be restored; otherwise the tree will be clipped to at most (maxDepth) levels. If (maxDepth) is zero, only (node) will be restored.
	optPruner	If set non-NULL, this object will be used as a callback to prune the traversal, and optionally to filter the data that gets loaded from (msg).

Returns:: B_NO_ERROR on success, or B_ERROR on failure (out of memory?)

virtual status_t StorageReflectSession::InsertOrderedData	(	const MessageRef &	insertMsg,
		Hashtable< String, DataNodeRef > *	optRetNewNodes
	)			`[protected, virtual]`

Create and insert a new node into one or more ordered child indices in the node tree.

This method is similar to calling MessageReceivedFromGateway() with a PR_COMMAND_INSERTORDEREDDATA Message, only it gives more information back about what happened.

Parameters:

	insertMsg	a PR_COMMAND_INSERTORDEREDDATA Message specifying what insertions should be done.
	optRetNewNodes	If non-NULL, any newly-created DataNodes will be adde to this table for your inspection.

Returns:: B_NO_ERROR on success, or B_ERROR on failure.

virtual bool StorageReflectSession::HasPrivilege ( int whichPriv ) const [protected, virtual]

Returns true iff we have the given PR_PRIVILEGE_* privilege.

Returns:: Default implementation looks at the PR_NAME_PRIVILEGE_BITS parameter.

void StorageReflectSession::Cleanup ( ) [protected]

Removes our nodes from the tree and removes our subscriptions from our neighbors.

Called by the destructor.

status_t StorageReflectSession::FindMatchingSessions	(	const String &	nodePath,
		const QueryFilterRef &	filter,
		Hashtable< const String *, AbstractReflectSessionRef > &	retSessions,
		bool	matchSelf,
		uint32	maxResults = `MUSCLE_NO_LIMIT`
	)			const `[protected]`

Convenience method: Adds sessions that contain nodes that match the given pattern to the passed-in Hashtable.

Parameters:

	nodePath	the node path to match against. May be absolute (e.g. "/0/1234/frc*") or relative (e.g. "blah") If the nodePath is a zero-length String, all sessions will match.
	filter	If non-NULL, only nodes whose data Messages match this filter will have their sessions added to the (retSessions) table.
	retSessions	A table that will on return contain the set of matching sessions, keyed by their session ID strings. Make sure you have called SetKeyCompareFunction(StringCompareFunc) on this table!
	matchSelf	If true, we will include as a candidate for pattern matching. Otherwise we won't.
	maxResults	Maximum number of matching sessions to returns. Defaults to MUSCLE_NO_LIMIT.

Returns:: B_NO_ERROR on success, or B_ERROR on failure (out of memory?)

AbstractReflectSessionRef StorageReflectSession::FindMatchingSession	(	const String &	nodePath,
		const QueryFilterRef &	filter,
		bool	matchSelf
	)			const `[protected]`

Convenience method: Same as FindMatchingsession(), but finds only the first matching session.

Returns a reference to the first matching session on success, or a NULL reference on failue.

status_t StorageReflectSession::SendMessageToMatchingSessions	(	const MessageRef &	msgRef,
		const String &	nodePath,
		const QueryFilterRef &	filter,
		bool	matchSelf
	)			`[protected]`

Convenience method: Passes the given Message on to the sessions who match the given nodePath.

(that is, any sessions who have nodes that match (nodePath) will have their MessageReceivedFromSession() method called with the given Message)

Parameters:

	msgRef	the Message to pass on.
	nodePath	the node path to match against. May be absolute (e.g. "/0/1234/frc*") or relative (e.g. "blah") If the nodePath is a zero-length String, all sessions will match.
	filter	If non-NULL, only nodes whose data Messages match this filter will receive the Message.
	matchSelf	If true, we will include as a candidate for pattern matching. Otherwise we won't.

Returns:: B_NO_ERROR on success, or B_ERROR on failure (out of memory?)

status_t StorageReflectSession::CloneDataNodeSubtree	(	const DataNode &	sourceNode,
		const String &	destPath,
		bool	allowOverwriteData = `true`,
		bool	allowCreateNode = `true`,
		bool	quiet = `false`,
		bool	addToTargetIndex = `false`,
		const String *	optInsertBefore = `NULL`,
		const ITraversalPruner *	optPruner = `NULL`
	)			`[protected]`

Convenience method (used by some customized daemons) -- Given a source node and a destination path, Make (path) a deep, recursive clone of (node).

Parameters:

	sourceNode	Reference to a DataNode to clone.
	destPath	Path of where the newly created node subtree will appear. Should be relative to our home node.
	allowOverwriteData	If true, we will clobber any previously existing node at the destination path. Otherwise, the existence of a pre-existing node there will cause us to fail.
	allowCreateNode	If true, we will create a node at the destination path if necessary. Otherwise, the non-existence of a pre-existing node there will cause us to fail.
	quiet	If false, no subscribers will be notified of the changes we make.
	addToTargetIndex	If true, the newly created subtree will be added to the target node using InsertOrderedChild(). If false, it will be added using PutChild().
	optInsertBefore	If (addToTargetIndex) is true, this argument will be passed on to InsertOrderedChild(). Otherwise, this argument is ignored.
	optPruner	If non-NULL, this object can be used as a callback to prune the traversal or filter the MessageRefs cloned.

Returns:: B_NO_ERROR on success, or B_ERROR on failure (may leave a partially cloned subtree on failure)

virtual void StorageReflectSession::NotifySubscribersThatNodeChanged	(	DataNode &	node,
		const MessageRef &	oldData,
		bool	isBeingRemoved
	)			`[protected, virtual]`

Tells other sessions that we have modified (node) in our node subtree.

Parameters:

	node	The node that has been modfied.
	oldData	If the node is being modified, this argument contains the node's previously held data. If it is being created, this is a NULL reference. If the node is being destroyed, this will contain the node's current data.
	isBeingRemoved	If true, this node is about to go away.

virtual void StorageReflectSession::NotifySubscribersThatNodeIndexChanged	(	DataNode &	node,
		char	op,
		uint32	index,
		const String &	key
	)			`[protected, virtual]`

Tells other sessions that we have changed the index of (node) in our node subtree.

Parameters:

	node	The node whose index was changed.
	op	The INDEX_OP_* opcode of the change. (Note that currently INDEX_OP_CLEARED is never used here)
	index	The index at which the operation took place (not defined for clear operations)
	key	The key of the operation (aka the name of the associated node)

virtual void StorageReflectSession::NodeChanged	(	DataNode &	node,
		const MessageRef &	oldData,
		bool	isBeingRemoved
	)			`[protected, virtual]`

Called by NotifySubscribersThatNodeChanged(), to tell us that (node) has been created, modified, or is about to be destroyed.

Parameters:

	node	The node that was modified, created, or is about to be destroyed.
	oldData	If the node is being modified, this argument contains the node's previously held data. If it is being created, this is a NULL reference. If the node is being destroyed, this will contain the node's current data.
	isBeingRemoved	True iff this node is about to be destroyed.

virtual void StorageReflectSession::NodeIndexChanged	(	DataNode &	node,
		char	op,
		uint32	index,
		const String &	key
	)			`[protected, virtual]`

Called by NotifySubscribersThatIndexChanged() to tell us how (node)'s index has been modified.

Parameters:

	node	The node whose index was changed.
	op	The INDEX_OP_* opcode of the change. (Note that currently INDEX_OP_CLEARED is never used here)
	index	The index at which the operation took place (not defined for clear operations)
	key	The key of the operation (aka the name of the associated node)

void StorageReflectSession::DoGetData ( const Message & getMsg ) [protected]

Executes a data-gathering tree traversal based on the PR_NAME_KEYS specified in the given message.

Parameters:

getMsg

a Message whose PR_NAME_KEYS field specifies which nodes we are interested in.

void StorageReflectSession::DoRemoveData	(	NodePathMatcher &	matcher,
		bool	quiet = `false`
	)			`[protected]`

Executes a node-removal traversal using the given NodePathMatcher.

Note that you may find it easier to call RemoveDataNodes() than to call this method directly.

Parameters:

	matcher	Reference to the NodePathMatcher object to use to guide the node-removal traversal.
	quiet	If set to true, subscriber's won't be updated regarding this change to the database

void StorageReflectSession::SetSubscriptionsEnabled ( bool e ) [inline, protected]

If set false, we won't receive subscription updates.

Parameters:

Whether or not we wish to get update messages from our subscriptions.

Definition at line 378 of file StorageReflectSession.h.

bool StorageReflectSession::GetSubscriptionsEnabled ( ) const [inline, protected]

Returns true iff our "subscriptions enabled" flag is set.

Default state is of this flag is true.

Definition at line 381 of file StorageReflectSession.h.

DataNode* StorageReflectSession::GetDataNode ( const String & path ) const [inline, protected]

Convenience method: Uses the given path to lookup a single node in the node tree and return it.

As of MUSCLE v4.11, wildcarding is supported in the path argument. If (path) begins with a '/', the search will begin with the root node of the tree; if not, it will begin with this session's node. Returns NULL on failure.

Parameters:

path

The fully specified path to a single node in the database.

Returns:: A pointer to the specified DataNode, or NULL if the node wasn't found.

Definition at line 391 of file StorageReflectSession.h.

StorageReflectSession Class Reference

Public Member Functions

Protected Types

Protected Member Functions

Friends

Classes

Detailed Description

Member Typedef Documentation

Member Function Documentation