Class: TEventSender

Declaration: Input.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

A hardware deviceÕs communication link to the Input system. It serves to define the lifetime of a device to the Input system. By definition, there is a one-to-one correspondence between the number of TEventSender objects in existence in the entire system and the number of input devices active on that system. Thus, when a program instantiates a TEventSender, the program becomes an input device. When that TEventSender is deleted, the program ceases to be an input device. TEventSender is used by any program that sends events. Because the communication linkage is very generic, the primary clients of TEventSender are other frameworks that define input device types, such as a keyboard framework or mouse framework. These frameworks will likely provide higher-level semantics on event sending than that provided by TEventSender. For example, a mouse framework can define protocol for sending a mouse-down event, allowing the client to specify the point at which the click occurred. The framework would package that into a stream of data which it would ask its TEventSender implementation to send. TEventSenders can be identified across tasks by TEventSenderSurrogates. TEventSenderSurrogates are lightweight objects whose sole purpose to is identify event senders across tasks. TEventSender has protocol for (1) registering and deregistering input devices with the Input system; and (2) sending a message to a deviceÕs TInputDevice object in a target application. TEventSender is a concrete class, and it is not intended to be derived. As such, it is designed so that clients can delegate to an instance of TEventSender rather than inheriting from it. This stems from the basic concept of TEventSender as a communication link; TEventSender generally doesn't know what information is being passed through it, just that information is flowing through it. This allows the device writer to determine the content of a message it passes from objects in a driver task to an TInputDevice object in an application task. Similarly, TEventSender is not streamable because its defined function has no persistent state.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

TEventSender is not intended to be derived from.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TEventSender::TEventSender

TEventSender (TInputDevice * adoptInputDevice)
TEventSender (const TInputDevice & copyInputDevice)

Interface Category:

API.

Purpose:

Creates a new event sender that adopts the specified input device. This constructor registers the new event sender with the Input system.
Creates a new event sender that adopts a copy of the specified input device. This constructor registers the new event sender with the Input system.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

TInputDevice * adoptInputDevice -The input device to be adopted.
const TInputDevice & copyInputDevice -The input device whose copy is to be adopted.

Return Value:

None.

Exceptions:

These constructors can indirectly cause an assertion during registration. An assertion is caused if the input device is NIL, or if the input device is already registered; in either case, registration does not take place.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEventSender::~TEventSender

virtual ~ TEventSender ()

Interface Category:

API.

Purpose:

Destructor. This destructor deregisters the event sender with the Input system.

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: TEventSender::SendEvent

virtual void SendEvent (TRandomAccessStream & message, ESyncLevel =kNormal)
virtual void SendEvent (TRandomAccessStream & message, const TEventReceiverSurrogate & target, ESyncLevel =kNormal )
virtual void SendEvent (TRandomAccessStream & message, TEventReceiverTargetter & target, ESyncLevel =kNormal )

Interface Category:

API.

Purpose:

Sends the event specified in the random access stream to the Input system.
Sends the event specified in the random access stream to the specified event receiver.
Sends the event specified in the random access stream to the specified event receiver targeter.

Calling Context:

Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

TRandomAccessStream & message -The event to be sent.
ESyncLevel =kNormal -Specifies that the synchronization level is normal so that the caller blocks for the correct amount of time.
TRandomAccessStream & message -The event to be sent.
const TEventReceiverSurrogate & target -The event receiver to which the event is to be sent.
ESyncLevel =kNormal -Specifies that the synchronization level is normal so that the caller blocks for the correct amount of time.
TRandomAccessStream & message -The event to be sent.
TEventReceiverTargetter & target -The event receiver targeter to which the event is to be sent.
ESyncLevel =kNormal -Specifies that the synchronization level is normal so that the caller blocks for the correct amount of time.

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.