Notification

Links to the SunView Programmer's Guide.

Client Events

Delivery Times

Client Defined Signals

Handler Registration

This section presents the programming interface to the N otifier that clients use to register event handlers and receive notifications.

Only those areas not covered in the

Notifier

chapter of the

SunView

Programmer's Guide

are presented. In particular,

input pending

refers to the sec-tion in the other manual.

The two Notifier chapters are different in that the

Sun View Programmer's Guide

considers the Notifier in relation to Sun View; thus, for example, in it notifier events are SunView Input Events, so their type is Event

*.

In this chapter, event is the more general type Notify_event.

This section describes how

client events

are handled by the Notifier. From the Notifier's point of view, client events are defined and generated by the client.

Client events are not interpreted by the Notifier in any way. The Notifier doesn't detect client events, it just detects UNIX-related events. The Notifier is responsi-ble for dispatching client events to the client's event handler after the event has been

posted

with the Notifier by application code (see the section entitled

Post-ing

below).

The Notifier nonnally sends client event notifications when it is

safe

to do so.

This may involve some delay between when an event is posted and when it is delivered. However, a client may ask to always be

immediately

notified of the posting of a client event (see

Posting,

below).

The immediate client event notification mechanism should be viewed as an extension of the UNIX signaling mechanism in which events are client defined signals. However, clients are strongly encouraged to only use safe client event handlers.

To register a client event handler call:

Notify_func

notify_set_event_func(client, event func, when) Notify_client client;

Notify_func event_func;

Notify_event_type when;

enum notify_event_type { NOTIFY_SAFE=O,

NOTIFY_IMMEDIATE=l,

} i

typedef enum notify_event_type Notify_event_typei

when indicates whether the event handler will accept notifications only when it is safe (NOTIFY_SAFE) or at less restrictive times (NOTIFY_IMMEDIATE).16

16 For a rundown of the basics of registering event handlers see the section on Event Handling in the Notifier chapter of the SunView Programmer's Guide.

Revision A, of March 27,1990

The Event Handler

SunView Usage

Output Completed Events

Chapter 8 - Advanced Notifier Usage 53

The calling sequence of a client event handler is:

Notify_value

event_func(client, event, arg, when)

Notify_client client;

Notify_event event;

Notify_arg arg;

Notify_event_type when;

typedef caddr_t Notify_argi

in which client is the client that called notify _set_event_func ( ).

event is passed through from noti fy _post_event ( ) (see

Posting,

below). arg is an additional argument whose type is dependent on the value of event and is completely defined by the client, like event. when is the actual situation in which even t is being delivered (NOTI FY _ SAFE or

NOTIFY_IMMEDIATE) and may be different from when_hint of notify _post_event ( ). The return value is one of NOTIFY_DONE or NOTIFY IGNORED.

You will almost certainly not need to directly register your own client event handler when using SunView. Window objects do this for themselves when they are created. However, note the following:

D A window has a client event handler that you may want to interpose in front of. See the section entitled

Monitoring and Modifying Window Behavior

in the

Notijier

chapter in the

SunView Programmer's Guide.

D Sun View client event handlers are normally registered with when equal to NOT! FY SAFE.

D The Agent reads input events from a window's file descriptor and posts them to the client via the win_post_ event ( ) call. See the section titled

Notifications From the Agent

in

The Agent

&

Tiles

chapter.

Notifications for output completed notifications are similar to input pending notifications, covered in the chapter on the N otifier in the

Sun View

Programmer's Guide.

Notify_func

notify_set_output_func(client, output_func, fd) Notify_client client;

Notify_func output_func;

int fd;

Notify_value

output_func(client, fd) Notify_client client;

int fd;

Revision A, of March 27,1990

Exception Occurred Events

Getting an Event Handler

Exception occurred notifications are similar to input pending notifications. The only known devices that generate exceptions at this time are stream-based socket connections when an out-of-band byte is available. Thus, a SIGURG signal catcher is set up by the Notifier, much like SIGIO for asynchronous input.

Notify_func

notify_set_exception_func(client, exception_func, fd) Notify_client client;

Notify_func exception_func;

int fd;

Notify_value

exception_func(client, fd) Notify_client client;

int fd;

Here is the list of routines that allow you to retrieve the value of a client' s event handler. The arguments to each notify _get_ * _func ( ) function parallel the associated notify _set_* _func ( ) function described elsewhere except for the absence of the event handler function pointer. Thus, we don't describe the arguments in detail here. Refer back to the associated

Doti fy _set _ * _ func ( ) descriptions for details. 17

A return value of NOTIFY FUNC NULL _{- -} indicates an error. If client is unknown then notify _errno is set to NOTIFY_UNKNOWN_CLIENT. Ifno event handler is registered for the specified event then notify _ errno is set to NOTIFY_NO_CONDITION. Other values of notify_err no are possible, depending on the event, e.g., NOTIFY_BAD _ FD if an invalid file descriptor is specified (see the associated notify _set_

*

^{_func (}

».

Here is a list of event handler retrieval routines:

Notify_func

notify_get_input_func(client, fd) Notify_client client;

int fd;

Notify_func

notify_get_event_func(client, when)

Notify_client client;

Notify_event_type when;

Notify_func

notify_get_output_func(client, fd) Notify_client client;

int fd;

17 It is recommended that you use the Notifier's interposition mechanism instead of trying to do interposition yourse]fusing these notify _get_ * _ func ( ) routines.

sun

Revision A, of March 27,1990

microsystems

Dans le document System Programmer's Guide sun® (Page 68-71)