ADC Home > Reference Library > Reference > Darwin > Miscellaneous User Space API Reference

 


notify.h

Includes:
<sys/cdefs.h>
<stdint.h>
<mach/message.h>
<mach/port.h>
<mach/message.h>
<mach/ndr.h>

Introduction

These routines allow processes to exchange stateless notification events.

Notifications are associated with names in a namespace shared by all clients of the system. Clients may post notifications for names, and may monitor names for posted notifications. Clients may request notification delivery by a number of different methods.

Clients desiring to monitor names in the notification system must register with the system, providing a name and other information required for the desired notification delivery method. Clients are given an integer token representing the registration.

Notification delivery is provided on a best-effort basis, but is not reliable. Limitations in the service may cause some notifications to be dropped, particularly under heavily loaded conditions.

Notifications may be coalesced in some cases. Multiple events posted for a name in rapid succession may result in a single notification sent to clients registered for notification for that name. Clients checking for changes using the notify_check() routine cannot determine if more than one event pas been posted since a previous call to notify_check() for that name.

"False positives" may occur in notify_check() when used with a token generated by notify_register_check() due to implementation constraints. This behavior may vary in future releases.



Functions

notify_cancel
notify_check
notify_post
notify_register_check
notify_register_mach_port
notify_register_signal

notify_cancel


uint32_t notify_cancel(
    int token);  
Parameters
token
(input) notification token
Return Value

Returns status.

Discussion

Cancel notification and free resources associated with a notification token. Mach ports and file descriptor associated with a token are released (deallocated or closed) when all registration tokens associated with the port or file descriptor have been cancelled.


notify_check


uint32_t notify_check(
    int token,
    int *check);  
Parameters
token
(input)notification token
check
(output) true/false indication
Return Value

Returns status.

Discussion

Check if any notifications have been posted.

Output parameter check is set to 0 for false, 1 for true. Returns status. check is set to true the first time notify_check is called for a token. Subsequent calls set check to true when notifications have been posted for the name associated with the notification token. This routine is independent of notify_post(). That is, check will be true if an application calls notify_post() for a name and then calls notify_check() for a token associated with that name.


notify_post


uint32_t notify_post(
    const char *name);  
Discussion

Post a notification for a name.

This is the only call that is required for a notification producer. Returns status.


notify_register_check


uint32_t notify_register_check(
    const char *name,
    int *out_token);  
Parameters
name
(input) notification name
out_token
(output) registration token
Return Value

Returns status.

Discussion

Creates a registration token be used with notify_check(), but no active notifications will be delivered.


notify_register_mach_port


uint32_t notify_register_mach_port(
    const char *name,
    mach_port_t *notify_port,
    int flags,
    int *out_token);  
Parameters
name
(input) notification name
out_token
(output) notification token
notify_port
(input/output) pointer to a mach port
Return Value

Returns status.

Discussion

Request notification by mach message.

Notifications are delivered by an empty message sent to a mach port. By default, a new port is allocated and a pointer to it is returned as the value of "notify_port". A mach port previously returned by a call to this routine may be used for notifications if a pointer to that port is passed in to the routine and NOTIFY_REUSE is set in the flags parameter. The notification service must be able to extract send rights to the port.

Note that the kernel limits the size of the message queue for any port. If it is important that notifications should not be lost due to queue overflow, clients should service messages quickly, and be careful about using the same port for notifications for more than one name.

A notification message has an empty message body. The msgh_id field in the mach message header will have the value of the notification token. If a port is reused for multiple notification registrations, the msgh_id value may be used to determine which name generated the notification.


notify_register_signal


uint32_t notify_register_signal(
    const char *name,
    int sig,
    int *out_token);  
Parameters
name
(input) notification name
sig
(input) signal number (see signal(3))
out_token
(output) notification token
Return Value

Returns status.

Discussion

Request notification delivery by UNIX signal.

A client may request signal notification for multiple names. After a signal is delivered, the notify_check() routine may be called with each notification token to determine which name (if any) generated the signal notification.

#defines


NOTIFY_REUSE


#define NOTIFY_REUSE 0x00000001 
Discussion

Flag bits used for registration.


NOTIFY_STATUS_FAILED


See Also:
Status Codes
#define NOTIFY_STATUS_FAILED 1000000 
Discussion

Status codes returned by the API.


NOTIFY_STATUS_INVALID_FILE


See Also:
Status Codes
#define NOTIFY_STATUS_INVALID_FILE 4 
Discussion

Status codes returned by the API.


NOTIFY_STATUS_INVALID_NAME


See Also:
Status Codes
#define NOTIFY_STATUS_INVALID_NAME 1 
Discussion

Status codes returned by the API.


NOTIFY_STATUS_INVALID_PORT


See Also:
Status Codes
#define NOTIFY_STATUS_INVALID_PORT 3 
Discussion

Status codes returned by the API.


NOTIFY_STATUS_INVALID_REQUEST


See Also:
Status Codes
#define NOTIFY_STATUS_INVALID_REQUEST 6 
Discussion

Status codes returned by the API.


NOTIFY_STATUS_INVALID_SIGNAL


See Also:
Status Codes
#define NOTIFY_STATUS_INVALID_SIGNAL 5 
Discussion

Status codes returned by the API.


NOTIFY_STATUS_INVALID_TOKEN


See Also:
Status Codes
#define NOTIFY_STATUS_INVALID_TOKEN 2 
Discussion

Status codes returned by the API.


NOTIFY_STATUS_NOT_AUTHORIZED


See Also:
Status Codes
#define NOTIFY_STATUS_NOT_AUTHORIZED 7 
Discussion

Status codes returned by the API.


NOTIFY_STATUS_OK


See Also:
Status Codes
#define NOTIFY_STATUS_OK 0 
Discussion

Status codes returned by the API.


Status Codes


See Also:
NOTIFY_STATUS_OK
NOTIFY_STATUS_INVALID_NAME
NOTIFY_STATUS_INVALID_TOKEN
NOTIFY_STATUS_INVALID_PORT
NOTIFY_STATUS_INVALID_FILE
NOTIFY_STATUS_INVALID_SIGNAL
NOTIFY_STATUS_INVALID_REQUEST
NOTIFY_STATUS_NOT_AUTHORIZED
NOTIFY_STATUS_FAILED
#define NOTIFY_STATUS_OK 0
#define NOTIFY_STATUS_INVALID_NAME 1
#define NOTIFY_STATUS_INVALID_TOKEN 2
#define NOTIFY_STATUS_INVALID_PORT 3
#define NOTIFY_STATUS_INVALID_FILE 4
#define NOTIFY_STATUS_INVALID_SIGNAL 5
#define NOTIFY_STATUS_INVALID_REQUEST 6
#define NOTIFY_STATUS_NOT_AUTHORIZED 7
#define NOTIFY_STATUS_FAILED 1000000
Discussion

Status codes returned by the API.

Feedback
Last Updated: 2006-06-20