Class: MRemoteDispatcher

Declaration: RemoteDispatcher.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TAudioProcessor TMediaRegistry TTelephoneLineFeature TVideoDeviceDriver TTelephoneHandset TTelephoneLine

Purpose:

MRemoteDispatcher is a mixin class that complements the MRemoteCaller class. You can use MRemoteDispatcher to create remote procedure call servers.

Instantiation:

MRemoteDispatcher is a generic base class and is not intended to be instantiated.

Deriving Classes:

MRemoteDispatcher is a mixin class for deriving dispatchers that handle remote procedure call requests.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: MRemoteDispatcher::MRemoteDispatcher

MRemoteDispatcher ()
MRemoteDispatcher (const MRemoteDispatcher & theDispatcher)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor. Only copies those without child dispatchers.

Calling Context:

Called to instantiate an object. Called by derived classes.
Called to copy an object. Called by derived classes.

Parameters:

Takes no parameters.
const MRemoteDispatcher & theDispatcher -The object to be copied.

Return Value:

None.

Exceptions:

Throws TRemoteCallException(kCantCopyParentDispatcher) if theDispatcher is a parent dispatcher.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MRemoteDispatcher::~MRemoteDispatcher

virtual ~ MRemoteDispatcher ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object. Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MRemoteDispatcher::operator=

MRemoteDispatcher & operator =(const MRemoteDispatcher & theDispatcher)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object. Called by derived classes or users of derived classes.

Parameters:

const MRemoteDispatcher & theDispatcher -The object to be copied.

Return Value:

A reference to the left-hand side object.

Exceptions:

Throws TRemoteCallException(kCantCopyParentDispatchers) when this dispatcher has child dispatchers.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MRemoteDispatcher::RegisterRequests

void RegisterRequests (const TText & dispatcherClassName, MRemoteCaller :: RequestID maxRequest, RequestEntry requestList [])

Interface Category:

API.

Purpose:

Registers a dispatcher class, the range of request identifiers it handles, and the functions that correspond to each request identifier.

Calling Context:

Called to add a new dispatcher class and its requests to the class dictionary. Called by derived classes or users of derived classes.

Parameters:

const TText & dispatcherClassName -The dispatcher class.
MRemoteCaller :: RequestID maxRequest -The maximum request identifier.
RequestEntry requestList [] -The list of request identifiers and their corresponding functions.
ESpecialSync syncType =kInternalSync -Internal only. Indicates whether a lock must be acquired for the class dictionary before the update is attempted.

Return Value:

None.

Exceptions:

Throws TRemoteCallException(kRequestTableFull) if the request table is full. Throws TRemoteCallException(kInvalidRequestEnum) if a request identifier in requestList is greater than maxRequest. Throws TRemoteCallException(kRequestAlreadyRegistered) if a request in requestList is already registered. Throws TRemoteCallException(kClassHashConflict) if another class name exists in the class dictionary that has the same hash value as dispatcherClassName. Throws TRemoteCallException(kRegistrationConflict) if dispatcherClassName is already registered in the class dictionary.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MRemoteDispatcher::SetDispatchResult

void SetDispatchResult (bool continueDispatching)

Interface Category:

API.

Purpose:

Sets the value to indicate whether dispatching should continue.

Calling Context:

Called to set the value to indicate whether dispatching should continue. Called by derived classes or users of derived classes.

Parameters:

bool continueDispatching -The value indicating whether dispatching should continue.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MRemoteDispatcher::DispatchRequest

virtual bool DispatchRequest (TStream & theArgumentStream, TStream & theResultStream)

Interface Category:

API.

Purpose:

Dispatches an incoming request.

Calling Context:

Called to dispatch a request. Called by derived classes or users of derived classes.

Parameters:

TStream & theArgumentStream -The stream from which the request is read.
TStream & theResultStream -The stream to which the result is written.

Return Value:

Returns the value indicating whether dispatching should continue.

Exceptions:

Throws TRemoteCallException(kBadCachedRequestIndex) if the request index cached by the caller is invalid. Throws TRemoteCallException(kRequestNotRegistered) if the request handling method for the request identifier is not registered. Catches all TStandardException instances and flattens them to theResultStream.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MRemoteDispatcher::ReturnSuccess

virtual void ReturnSuccess (TStream & theResultStream)

Interface Category:

API.

Purpose:

Signals that the request succeeded by writing a status value to theResultStream.

Calling Context:

Called by every request function to write a success status to theResultStream. Called by derived classes or users of derived classes.

Parameters:

TStream & theResultStream -The stream to which the success status is written.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function must be called after the processing of the request is complete and before the flattening of any results to theResultStream.

Member Function: MRemoteDispatcher::GetChildDirectory

TDispatcherChildDirectory * GetChildDirectory () const

Interface Category:

API.

Purpose:

Returns a pointer to the dispatcher's child directory, if any.

Calling Context:

Called to obtain a pointer to the dispatcher's child directory. Called by derived classes or users of derived classes.

Parameters:

Takes no parameters.

Return Value:

A pointer to the dispatcher's child directory. A NIL pointer is returned if there is no child directory.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MRemoteDispatcher::SetChildDirectory

void SetChildDirectory (TDispatcherChildDirectory * childDirectory)

Interface Category:

API.

Purpose:

Sets the dispatcher's child directory.

Calling Context:

Called to set the dispatcher's child directory. Called by derived classes or users of derived classes.

Parameters:

TDispatcherChildDirectory * childDirectory -The child directory to set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.