Class: TEventReceiverSurrogate

Declaration: Input.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TEventReceiverSurrogates are lightweight objects. They exist only to identify event receivers across tasks. Their protocol includes validity checks and identity comparisons to other surrogates. Additionally, TEventReceiverSurrogates have protocol for blocking until the event receiver that they represent has stopped. This is important if a client wants to ensure that an event receiver has shut down. Deleting the TEventReceiverHandle tells the event receiver to shut down at some unspecified point in the future. Clients who need to ensure that an event receiver has completely shut down before continuing must use the blocking WaitUntilInvalid protocol on this class.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TEventReceiverSurrogate::TEventReceiverSurrogate

TEventReceiverSurrogate ()
TEventReceiverSurrogate (const TEventReceiverHandle & handle)
TEventReceiverSurrogate (const TEventReceiverSurrogate & copy)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new event receiver surrogate for the specified event receiver.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Call this function directly.
Called to copy an object.

Parameters:

Takes no parameters.
const TEventReceiverHandle & handle -The event receiver for which the new surrogate is to be created.
const TEventReceiverSurrogate & copy -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::~TEventReceiverSurrogate

virtual ~ TEventReceiverSurrogate ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::operator=

TEventReceiverSurrogate & operator =(const TEventReceiverSurrogate & assign)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TEventReceiverSurrogate & assign -The object to be copied.

Return Value:

Returns a const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::operator==

bool operator ==(const TEventReceiverSurrogate & other) const

Interface Category:

API.

Purpose:

Determines whether this surrogate is equal to the specified event receiver surrogate. Surrogates are equal if and only if their identifiers are equal; that is, they are surrogates for the same event receiver.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TEventReceiverSurrogate & other -The object to be compared to this TEventReceiverSurrogate object.

Return Value:

Returns true if the two objects are equal; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::operator!=

bool operator != (const TEventReceiverSurrogate & other) const

Interface Category:

API.

Purpose:

Determines whether this surrogate is not equal to the specified event receiver surrogate. Surrogates are not equal if their identifiers are not equal; that is, they are surrogates for different event receivers.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TEventReceiverSurrogate & other -The object to be compared to this one.

Return Value:

Returns true if the two objects are not equal; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::Compare

virtual EComparisonResult Compare (const TEventReceiverSurrogate & other) const

Interface Category:

API.

Purpose:

Determines whether this surrogate is equal to the specified TEventReceiverSurrogate object. Surrogates are not equal if their identifiers are not equal; that is, they are surrogates for different event receivers.

Calling Context:

Call this function directly.

Parameters:

const TEventReceiverSurrogate & other -The surrogate to be compared to this one.

Return Value:

Returns kEqual if the two objects are equal; otherwise, returns kNotEqual if the two objects are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::GetHash

virtual HashResult GetHash () const

Interface Category:

API.

Purpose:

Returns the hash value that uniquely identifies this object within its type. Hash values are used to build dictionaries of objects.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the hash value that uniquely identifies this object within its type.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::operator>>=

virtual TStream & operator >>=(TStream & writeTo) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & writeTo -The stream to which the object streams itself out.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::operator<<=

virtual TStream & operator <<= (TStream & readFrom)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & readFrom -The stream from which the object streams itself in.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws a TInvalidVersionError if the version of the object on the stream is unknown to the version of the shared library that is installed.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::IsValid

bool IsValid () const

Interface Category:

API.

Purpose:

Determines whether the event receiver associated with this surrogate is valid. A valid event receiver is one that exists.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the event receiver associated with this surrogate is valid; otherwise. returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventReceiverSurrogate::WaitUntilInvalid

void WaitUntilInvalid () const

Interface Category:

API.

Purpose:

Waits until the event receiver associated with this surrogate is deleted. Deleting the TEventReceiverHandle tells the event receiver to shut down at some unspecified point in the future. Clients use this function to ensure that an event receiver is completely shut down.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

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.