ISignalMgr Class Reference

#include <isignalmgr.h>

Inheritance diagram for ISignalMgr:

Public Types
enum	{ kDefaultIID = IID_ISIGNALMGR }

Public Member Functions
virtual void	Init (ServiceID serviceID)=0
virtual void	Terminate ()=0
virtual ServiceID	GetServiceID () const =0
virtual int32	CountResponders () const =0
virtual int32	CountUnsignaledResponders () const =0
virtual ErrorCode	SignalNextResponder ()=0
virtual ErrorCode	SignalResponder (ClassID actionClassID)=0
virtual ErrorCode	SignalAllResponders (ServiceID serviceID, bool16 showProgress=kFalse)=0
Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0
virtual void	AddRef () const =0
virtual void	Release () const =0

Detailed Description

ISignalMgr is used to send a Signal.

The Signal/Responder protocol is used particularly for broadcasting model changes, but is used anytime the listener doesn't care what object changed, but is intererested in finding out about all changes of a certain class. ISignalMgr handles sending the message to the responders.

Responders implement a given ServiceID. The sender (usually a command) gets the signal mgr and sends the message. There is a single default implementation of ISignalMgr which is used to actually send the message; usually this is either attached to the command which is sending the message, or on a standalone boss. Either way works equally well.

To send a signal, typically you need code that does something like this:

#include "ISignalMgr.h"

InterfacePtr<ISignalMgr> signalMgr(this, UseDefaultIID());

signalMgr->Init(kMySignalServiceID);

signalMgr->SignalAllResponders(kMySignalServiceID);

If you have data you want to pass along in the signal, you can supply it as a data interface if necessary. But if you are signalling on a command, and attach the signalmgr to the command, then this is typically not necessary because the responder is passed the signalmgr and can use it to query for the command's data interface directly.

If you need to control the loop yourself, you can do this by iterating the responders and terminating the signalmgr yourself. Typically this is not necessary.

See Also

IResponder handles receiving signals.

Member Function Documentation

virtual int32 ISignalMgr::CountResponders ( ) const

pure virtual

Get the number of responders that will be called.

Returns

int32 the number of responders to signal

virtual int32 ISignalMgr::CountUnsignaledResponders ( ) const

pure virtual

Get the number of responders that are not yet signaled

Returns

int32 how many responders still need to be signalled

virtual ServiceID ISignalMgr::GetServiceID ( ) const

pure virtual

Get the ServiceID that this SignalMgr signals on. This is used so that client responders may have a single responder capable of handling more than one type of signal.

Returns

ServiceID what service this signal manager is signalling

virtual void ISignalMgr::Init ( ServiceID  serviceID )

pure virtual

Initialize the signal mgr (should only get called once)

Parameters

serviceID

this tells the SignalMgr what responders to call

virtual ErrorCode ISignalMgr::SignalAllResponders ( ServiceID  serviceID, bool16  showProgress = kFalse  )

pure virtual

Signal all responders. This initializes the SignalMgr, iterates through the responders, calling each one and aborting in case of error, then calls Terminate. It will optionally display a progress indicator.

Returns

ErrorCode kSuccess if no error, an error code otherwise.

virtual ErrorCode ISignalMgr::SignalNextResponder ( )

pure virtual

Send a signal to the next responder. Callers should check the error code, and abort iteration in case of error!

Returns

ErrorCode kSuccess if responder succeeded, the failure code otherwise

virtual ErrorCode ISignalMgr::SignalResponder ( ClassID  actionClassID )

pure virtual

Signal a specific responder. The responder may return an error. The error may be specific to the responder, but could also be either kUnknownResponderError or kResponderIsBusyError.

Returns

ErrorCode kSuccess if responder succeeded, the failure code otherwise

virtual void ISignalMgr::Terminate ( )

pure virtual

Call this when you are done with the SignalMgr. The Terminate function is used to handle errors. A responder may flag an error by setting the global error code. If a responder encounters an error, then iteration should be aborted, and Terminate should be called. Terminate will signal all the responders who have already been called, to let them know that an error occurred.