Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

xpc_events(3)            BSD Library Functions Manual            xpc_events(3)

NAME
     xpc_events -- launch-on-demand for high-level events

SYNOPSIS
     #include <xpc/xpc.h>

     void
     xpc_set_event_stream_handler(const char *name, dispatch_queue_t targetq, xpc_handler_t handler);

DESCRIPTION
     XPC provides a mechanism by which launchd jobs may launch on-demand for certain higher-level events,
     such as IOKit events or BSD Notifications. These events are delivered to the job through a handler that
     is set early in its execution. The period between when the event is delivered to the job and when a
     handler is set is race-free, and any pending events will be queued up for consumption by the job. An
     event is consumed when it is delivered to the handler.

EVENT STREAMS
     Providers of events are known as streams. Two example event streams are the IOKit stream and the BSD
     Notifications stream. Streams are denoted by a reverse-DNS naming scheme. For the aforementioned exam-ples, examples,
     ples, the stream names are "com.apple.iokit.matching" and "com.apple.notifyd.matching", respectively.
     These are currently the only two supported event streams.

EVENT NAMES
     A launchd job may be interested in multiple events from different event streams.  Each of these events
     has a name provided by the job in the launchd.plist(5).

     The occurrence of any of these events will launch the job on-demand if it is not already running.

PLIST SCHEMA
     Events are specified through the launchd.plist(5) with the LaunchEvents key. The value for this key is
     a dictionary. Each value of this dictionary is itself a dictionary corresponding to an event stream.
     The values of this inner dictionary are events that may cause the job to be launched on-demand.

           <key>LaunchEvents</key>
           <dict>
                   <key>com.apple.iokit.matching</key>
                   <dict>
                           <key>com.apple.device-attach</key>
                           <dict>
                                   <key>idProduct</key>
                                   <integer>2794</integer>
                                   <key>idVendor</key>
                                   <integer>725</integer>
                                   <key>IOProviderClass</key>
                                   <string>IOUSBDevice</string>
                                   <key>IOMatchLaunchStream</key>
                                   <true/>
                           </dict>
                   </dict>
                   <key>com.apple.notifyd.matching</key>
                   <dict>
                           <key>com.apple.interesting-notification</key>
                           <dict>
                                   <key>Notification</key>
                                   <string>com.apple.interesting-notification</string>
                           </dict>
                   </dict>
           </dict>

     The above specifies that the job will be launched when a node matching the given matching dictionary
     appears in the IORegistry or when a notification named "com.apple.interesting-notification" is posted
     using notify_post(3).

     NOTE: The IOMatchLaunchStream key is required to be present and be a Boolean set to true for use with
     XPC Events. It will be filtered out of the rest of the dictionary when given to IOKit to match. The
     reasons for this are historical and not applicable to other event streams.

     Each event stream has a different plist schema.

EVENT CONSUMPTION
     Events are consumed with the xpc_set_event_stream_handler() API. The stream argument specifies from
     which event stream the given handler will receive events. The targetq parameter specifies on which
     queue the handler will be synchronized.  The handler will only ever receive dictionaries. Each dictio-nary dictionary
     nary is guaranteed to have the XPC_EVENT_KEY_NAME key set. The value for this key is the string that
     was given as the name for the event in the launchd.plist(5).  So if the IOKit event in the above exam-ple example
     ple was received, the value of this key would be "com.apple.device-attach".

     In addition to the standard payload, events from the IOKit stream also have the "IOMatchLaunchServi-ceID" "IOMatchLaunchServiceID"
     ceID" key set to a uint64_t which specifies the unique IORegistry ID of the node which matched the
     given dictionary as obtained by IORegistryEntryGetRegistryEntryID().  This value may be given to
     IORegistryEntryIDMatching() to obtain the registry entry which caused the event to fire.

     BSD Notfication events have no additional payload.

           xpc_set_event_stream_handler("com.apple.iokit.matching", q, ^(xpc_object_t event) {
                   const char *name = xpc_dictionary_get_string(event, XPC_EVENT_KEY_NAME);
                   uint64_t id = xpc_dictionary_get_uint64(event, "IOMatchLaunchServiceID");

                   CFMutableDictionaryRef matching = IORegistryEntryIDMatching(id);
                   // Pass to IOServiceGetMatchingServices() or IOServiceAddNotification().
           });

     IMPORTANT: xpc_set_event_stream_handler() is NOT shareable. Two different subsystems in a process can-not cannot
     not safely both register for events from the same event stream. Therefore, libraries and frameworks
     should NEVER call this API.

SEE ALSO
     xpc_object(3), xpc_dictionary_create(3), xpc_array_create(3), notify(3)

Darwin                           1 July, 2011                           Darwin