/* * Copyright (c) 2005 Apple Computer, Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ /* File: CFNetwork/CFNetServices.h Contains: CoreFoundation Network Net Services header Copyright: © 2001-2005 by Apple Computer, Inc., all rights reserved Warning: *** APPLE INTERNAL USE ONLY *** This file may contain unreleased API's BuildInfo: Built by: anonymous On: Wed Apr 27 10:45:36 2005 With Interfacer: 3.0d46 (Mac OS X for PowerPC) From: CFNetServices.i Revision: 1.10 Dated: 2004/12/11 03:13:02 Last change by: jwyld Last comment: 3907571 Clean up header comments regarding CFNetServiceCreateDictionaryWithTXTData Bugs: Report bugs to Radar component "System Interfaces", "Latest" List the version information (from above) in the Problem Description. */ #ifndef __CFNETSERVICES__ #define __CFNETSERVICES__ #ifndef __CFNETWORKDEFS__ #include <CFNetwork/CFNetworkDefs.h> #endif #ifndef __CFBASE__ #include <CoreFoundation/CFBase.h> #endif #ifndef __CFSTREAM__ #include <CoreFoundation/CFStream.h> #endif #include <AvailabilityMacros.h> #if PRAGMA_ONCE #pragma once #endif #ifdef __cplusplus extern "C" { #endif #pragma options align=mac68k #if PRAGMA_ENUM_ALWAYSINT #pragma enumsalwaysint on #endif /* * CFNetServiceRef * * Discussion: * This is the type of a reference to a service. It may be used for * registering or for resolving. */ typedef struct __CFNetService* CFNetServiceRef; /* * CFNetServiceMonitorRef * * Discussion: * This is the type of a reference to a service monitor. It may be * used for watching record changes on a CFNetServiceRef. */ typedef struct __CFNetServiceMonitor* CFNetServiceMonitorRef; /* * CFNetServiceBrowserRef * * Discussion: * This is the type of a reference to a service or domain browser. * It may be used for discovering services or domains. */ typedef struct __CFNetServiceBrowser* CFNetServiceBrowserRef; /* * kCFStreamErrorDomainMach * * Discussion: * Errors reported by mach. See <mach/error.h> * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern const SInt32 kCFStreamErrorDomainMach AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * kCFStreamErrorDomainNetServices * * Discussion: * Errors listed below or reported by the Service Discovery API's. * See <dns_sd.h>. The Service Discovery errors will only be * returned when using the new, Mac OS X 10.4-based API's or * CFNetServiceBrowser. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern const SInt32 kCFStreamErrorDomainNetServices AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServicesError * * Discussion: * Errors from the kCFStreamErrorDomainNetServices domain. */ enum CFNetServicesError { /* * An error of unknown type has occured. */ kCFNetServicesErrorUnknown = -72000L, /* * The given registration has had a name collision. Registration * should be cancelled and should try again probably with a different * name. */ kCFNetServicesErrorCollision = -72001L, /* * Not used */ kCFNetServicesErrorNotFound = -72002L, /* * There is already a register, resolve, browse, or monitor in * progress on the given object. */ kCFNetServicesErrorInProgress = -72003L, /* * Not used */ kCFNetServicesErrorBadArgument = -72004L, /* * The register, resolve, or browse on the object has been cancelled. */ kCFNetServicesErrorCancel = -72005L, /* * The given CFNetServiceBrowser or CFNetServiceMonitor has already * been invalidated and can no longer be used. */ kCFNetServicesErrorInvalid = -72006L, /* * The given CFNetServiceResolveWithTimeout has hit the timeout * before a successful resolve. */ kCFNetServicesErrorTimeout = -72007L }; typedef enum CFNetServicesError CFNetServicesError; /* * CFNetServiceMonitorType * * Discussion: * Record type specifier in order to inform CFNetServiceMonitor to * watch for certain record changes. */ enum CFNetServiceMonitorType { /* * Watch for TXT record changes. */ kCFNetServiceMonitorTXT = 1 }; typedef enum CFNetServiceMonitorType CFNetServiceMonitorType; /* * CFNetService flags * * Discussion: * Bit flags to be used for registration of a service with CFNetServiceRegisterWithOptions. */ enum { kCFNetServiceFlagNoAutoRename = 1 /* Indicate that registration should not auto-rename the service to prevent name conflicts.*/ }; /* * CFNetServiceBrowser flags * * Discussion: * Result bit flags passed to CFNetServiceBrowserClientCallBack. */ enum { kCFNetServiceFlagMoreComing = 1, /* Client will get another callback briefly and shouldn't do costly screen updates (or such).*/ kCFNetServiceFlagIsDomain = 2, /* If off, the result is a service.*/ kCFNetServiceFlagIsDefault = 4, /* The result domain is the default domain for the given domain browse type (registration or browse).*/ kCFNetServiceFlagIsRegistrationDomain = 4, /* Same as the previous but incorrectly named. Kept for compatibility.*/ kCFNetServiceFlagRemove = 8 /* The result item should be removed and not added.*/ }; /* * CFNetServiceClientContext * * Discussion: * Structure containing the user-defined data and callbacks for * CFNetService and CFNetServiceBrowser objects. */ struct CFNetServiceClientContext { /* * The version number of the structure type being passed in as a * parameter to the CFNetService, Browser, or Monitor client * function. The current version number is 0. */ CFIndex version; /* * An arbitrary pointer to client-defined data, which can be * associated with the service/browser and is passed to the callbacks. */ void * info; /* * The callback used to add a retain for the service/browser on the * info pointer for the life of the service/browser, and may be used * for temporary references the service/browser needs to take. This * callback returns the actual info pointer to store in the * service/browser, almost always just the pointer passed as the * parameter. */ CFAllocatorRetainCallBack retain; /* * The callback used to remove a retain previously added for the * service/browser on the info pointer. */ CFAllocatorReleaseCallBack release; /* * The callback used to create a descriptive string representation of * the info pointer (or the data pointed to by the info pointer) for * debugging purposes. This is used by the CFCopyDescription() * function. */ CFAllocatorCopyDescriptionCallBack copyDescription; }; typedef struct CFNetServiceClientContext CFNetServiceClientContext; /* * CFNetServiceClientCallBack * * Discussion: * Callback function which is called upon error or completion of * resolve or register. If resolving with the deprecated API's, the * callback may be called multiple times, once for each resolved * address. * * Parameters: * * theService: * Service receiving the event. * * error: * Reference to an error structure if the event is a failure. * * info: * Client's info reference which was passed into the client * context. */ typedef CALLBACK_API_C( void , CFNetServiceClientCallBack )(CFNetServiceRef theService, CFStreamError *error, void *info); /* * CFNetServiceMonitorClientCallBack * * Discussion: * Callback function which is called as the monitored record changes. * * Parameters: * * theMonitor: * CFNetServiceMonitor receiving the event. * * theService: * Service receiving the event. * * typeInfo: * The information type which changed. * * rdata: * The contents of the record that changed. * * error: * Reference to an error structure if the event is a failure. * * info: * Client's info reference which was passed into the client * context. */ typedef CALLBACK_API_C( void , CFNetServiceMonitorClientCallBack )(CFNetServiceMonitorRef theMonitor, CFNetServiceRef theService, CFNetServiceMonitorType typeInfo, CFDataRef rdata, CFStreamError *error, void *info); /* * CFNetServiceBrowserClientCallBack * * Discussion: * Callback function which is called upon error or upon successful * discovery of services or domains. * * Parameters: * * browser: * CFNetServiceBrowser receiving the event. * * flags: * Bitwise flags indicating the event or further information about * the event. * * domainOrService: * If searching for domains, a CFStringRef indicating the domain * which was found or is going away. If searching for services, * the service which was found or is going away. * * error: * Reference to an error structure if the event is a failure. * * info: * Client's info reference which was passed into the client * context. */ typedef CALLBACK_API_C( void , CFNetServiceBrowserClientCallBack )(CFNetServiceBrowserRef browser, CFOptionFlags flags, CFTypeRef domainOrService, CFStreamError *error, void *info); /* * CFNetServiceGetTypeID() * * Discussion: * Returns the type identifier of all CFNetService instances. * * Mac OS X threading: * Thread safe * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFTypeID CFNetServiceGetTypeID(void) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceMonitorGetTypeID() * * Discussion: * Returns the type identifier of all CFNetServiceMonitor instances. * * Mac OS X threading: * Thread safe * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFTypeID CFNetServiceMonitorGetTypeID(void) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceBrowserGetTypeID() * * Discussion: * Returns the type identifier of all CFNetServiceBrowser instances. * * Mac OS X threading: * Thread safe * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFTypeID CFNetServiceBrowserGetTypeID(void) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceCreate() * * Discussion: * Creates an instance of a Network Service. * * Mac OS X threading: * Thread safe * * Parameters: * * alloc: * The CFAllocator which should be used to allocate memory for the * service and its storage for values. If this reference is not a * valid CFAllocator, the behavior is undefined. * * domain: * The network domain in which it is registered or will be * registered. This value must be non-NULL. * * serviceType: * The type of service being registered or resolved on the * network. The service type consists of the application protocol * name followed by the transport protocol name, separated by a * dot (e.g. "_ftp._tcp"). The application protocol name should * be 14 characters or less, and should only contain lower-case * letters, digits, and hyphens. New service types should be * registered at <htp://www.dns-sd.org/ServiceTypes.html>. This * value must be non-NULL. * * name: * The name of the machine or application advertising the service. * If this value is not unique, registering will eventually fail. * This value must be non-NULL. This value is usually displayed * in a browser for the user. * * port: * The port on which the service is listening. This must be * non-zero for services which are to be registered. * * Result: * A valid CFNetService which may now be registered or resolved, or * NULL if unsuccessful. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFNetServiceRef CFNetServiceCreate( CFAllocatorRef alloc, CFStringRef domain, CFStringRef serviceType, CFStringRef name, UInt32 port) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceCreateCopy() * * Discussion: * Creates a new CFNetService object as a copy of service argument. * * Mac OS X threading: * Thread safe * * Parameters: * * alloc: * The CFAllocator which should be used to allocate memory for the * new service. If this reference is not a valid CFAllocator, the * behavior is undefined. * * service: * A CFNetServiceRef representing the original service. Must be * non-NULL. If this If this reference is not a valid * CFNetServiceRef, the behavior is undefined. * * Result: * Returns a valid CFNetServiceRef which contains a copy of all * previously resolved data from the original. NULL is returned in * the case of failure. * * Availability: * Mac OS X: in version 10.3 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFNetServiceRef CFNetServiceCreateCopy( CFAllocatorRef alloc, CFNetServiceRef service) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER; /* * CFNetServiceGetDomain() * * Discussion: * Query a Network Service for its domain. * * Mac OS X threading: * Thread safe * The function gets the data in a thread-safe manner, but the * resulting data is not safe. Since it is returned as a matter of * a get opposed to a copy, the data is not safe if the service is * being altered from another thread. * * Parameters: * * theService: * The Network Service to be queried. Must be non-NULL. * * Result: * CFStringRef which is the service's domain. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFStringRef CFNetServiceGetDomain(CFNetServiceRef theService) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceGetType() * * Discussion: * Query a Network Service for its type. * * Mac OS X threading: * Thread safe * The function gets the data in a thread-safe manner, but the * resulting data is not safe. Since it is returned as a matter of * a get opposed to a copy, the data is not safe if the service is * being altered from another thread. * * Parameters: * * theService: * The Network Service to be queried. Must be non-NULL. * * Result: * CFStringRef which is the service's service type. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFStringRef CFNetServiceGetType(CFNetServiceRef theService) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceGetName() * * Discussion: * Query a Network Service for its name. * * Mac OS X threading: * Thread safe * The function gets the data in a thread-safe manner, but the * resulting data is not safe. Since it is returned as a matter of * a get opposed to a copy, the data is not safe if the service is * being altered from another thread. * * Parameters: * * theService: * The Network Service to be queried. Must be non-NULL. * * Result: * CFStringRef which is the service's name. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFStringRef CFNetServiceGetName(CFNetServiceRef theService) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceRegisterWithOptions() * * Discussion: * Registers the entity on the network. This requires that the * service has a domain, a type, a name, and a port. The service is * registered on the network until this function returns or is * cancelled by calling CFNetServiceCancel. In synchronous mode, * this function will block until there is an error or it is * cancelled from another thread. In asynchronous mode, this * function returns immediately and the underlying network * registration process will start. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The Network Service to register on the network. Must be * non-NULL. * * options: * A set of bit options used to instruct the registration process. * Current supported option is kCFNetServiceFlagNoAutoRename. * * error: * A reference to an error struct which will be set to the error * and domain of the error should one occur. If the value of * error is not desired, set to NULL. * * Result: * Returns FALSE if domain, type, name or port is NULL. In * synchronous mode, it will always return FALSE as a result of the * error or the cancellation. In asynchronous mode, it will return * TRUE if the registration process could start. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern Boolean CFNetServiceRegisterWithOptions( CFNetServiceRef theService, CFOptionFlags options, CFStreamError * error) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceResolveWithTimeout() * * Discussion: * Resolves the information related to this service. It will * resolve the target host, the addresses, and the first TXT record * associated with the service. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The CFNetServiceRef which should be resolved. Must be non-NULL. * If this reference is not a valid CFNetServiceRef, the behavior * is undefined. * * timeout: * CFTimeInterval representing the maximum amount of time to take * to perform the resolve. If the resolve can not be performed * within this timeout, the function or callback will recieve a * timeout error. Values less than or equal to zero indicate an * infinite timeout. * * error: * A reference to a CFStreamError structure which will be filled * with any error information should an error occur. May be set * to NULL if error information is not wanted. * * Result: * Returns TRUE on success and FALSE on failure. In asynchronous * mode, this function will return immediately. In synchronous * mode, it will block until the resolve has completed or until the * resolve is cancelled. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern Boolean CFNetServiceResolveWithTimeout( CFNetServiceRef theService, CFTimeInterval timeout, CFStreamError * error) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceCancel() * * Discussion: * Cancels an outstanding request for registration or resolution. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The Network Service which is active. Must be non-NULL. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceCancel(CFNetServiceRef theService) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceGetTargetHost() * * Discussion: * Query a Network Service for its resolve target. * * Mac OS X threading: * Thread safe * The function gets the data in a thread-safe manner, but the * resulting data is not safe. Since it is returned as a matter of * a get opposed to a copy, the data is not safe if the service is * being altered from another thread. * * Parameters: * * theService: * The Network Service to be queried. Must be non-NULL. * * Result: * Returns The target hostname of the machine providing the service, * or NULL if the entity's target is not known (has not been * resolved). * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFStringRef CFNetServiceGetTargetHost(CFNetServiceRef theService) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceGetAddressing() * * Discussion: * Query a Network Service for its addressing. * * Mac OS X threading: * Thread safe * The function gets the data in a thread-safe manner, but the * resulting data is not safe. Since it is returned as a matter of * a get opposed to a copy, the data is not safe if the service is * being altered from another thread. * * Parameters: * * theService: * The Network Service to be queried. Must be non-NULL. * * Result: * Returns NULL if the entity's addressing is not known (has not * been resolved). The array will contain a CFDataRef for each * address resolved. Each CFDataRef contains a struct sockaddr * representing the address of the service. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFArrayRef CFNetServiceGetAddressing(CFNetServiceRef theService) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceGetTXTData() * * Discussion: * Query a Network Service for its TXT record contents. * * Mac OS X threading: * Thread safe * The function gets the data in a thread-safe manner, but the * resulting data is not safe. Since it is returned as a matter of * a get opposed to a copy, the data is not safe if the service is * being altered from another thread. * * Parameters: * * theService: * The Network Service to be queried. Must be non-NULL. * * Result: * Returns NULL if the entity's TXT is not known (has not been * resolved). The result will contain the contents of the TXT * record. This is suitable to pass to * CFNetServiceCreateDictionaryWithTXTData. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFDataRef CFNetServiceGetTXTData(CFNetServiceRef theService) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceSetTXTData() * * Discussion: * Sets the TXT record for the service. If the service is currently * registered on the network, the record will be broadcast. Setting * the TXT record on a resolving service is not allowed. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The Network Service to receive the new record. Must be * non-NULL. * * txtRecord: * The contents of the TXT record. This should not exceed a * length of 1450 bytes. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern Boolean CFNetServiceSetTXTData( CFNetServiceRef theService, CFDataRef txtRecord) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceCreateDictionaryWithTXTData() * * Discussion: * Parses the given TXT record data into a set of key/value pairs as * a CFDictionary where keys are CFStringRefs and values are * CFDataRefs. If the given record can not be parsed, NULL will be * returned. READ THE COMMENTS FOR * CFNetServiceCreateTXTDataWithDictionary TO FULLY UNDERSTAND THE * USE AND RESULTS OF THIS FUNCTION. * * Mac OS X threading: * Thread safe * * Parameters: * * alloc: * CFAllocatorRef to be used for the creation of the result. * * txtRecord: * The TXT record data as returned by CFNetServiceGetInfo. * * Result: * CFDictionaryRef containing the key/value pairs parsed from the * record. It will return NULL if the record could not be parsed. * Keys in the dictionary are CFStringRef's. Values are CFDataRef's. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFDictionaryRef CFNetServiceCreateDictionaryWithTXTData( CFAllocatorRef alloc, CFDataRef txtRecord) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceCreateTXTDataWithDictionary() * * Discussion: * Flattens a set of key/value pairs into a CFDataRef suitable to * pass into CFNetServiceSetTXTData. This function will properly * format the data for TXT record usage. THIS IS NOT A GENERAL * CFDictionaryRef FLATTENING ROUTINE. CFDictionaryRef keys should * be CFStringRef's and values should be CFDataRef's. For * convenience, values that are CFStringRef's will be converted to * CFDataRef's representing the flattened UTF-8 bytes of the string. * The types of the values are not encoded in the CFDataRef's, * therefore CFStringRef's will be flattened into CFDataRef's, and * they will come out of CFNetServiceCreateDictionaryWithTXTData as * CFDataRef's. * * Mac OS X threading: * Thread safe * * Parameters: * * alloc: * CFAllocatorRef to be used for the creation of the result. * * keyValuePairs: * CFDictionaryRef containing keys and values to be placed into * the TXT record. The keys must be CFStringRef's. The values * should be CFDataRef's (CFStringRef's are permitted for * convenience). Any other types will cause a failure. The * length of a key and its value should not exceed 255. * * Result: * CFDataRef containing the flattened form of the keys and values. * If the dictionary could not be flattend, NULL will be returned. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFDataRef CFNetServiceCreateTXTDataWithDictionary( CFAllocatorRef alloc, CFDictionaryRef keyValuePairs) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceSetClient() * * Discussion: * Sets up the service to be used in asynchronous mode. * Notification of registration failure or resolution completion * will occur through the given callback. Once the client is set, * the service must be scheduled on a runloop. The client callback * will be triggered via one of the scheduled run loops; It is the * caller's responsibility to ensure that at least one of the * scheduled run loops is being run. This call must be performed * before calling CFNetServiceRegister or CFNetServiceResolve, * otherwise it will return FALSE. TRUE will be returned if the * client could be set. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The service to set up for asynchronous mode. Must be non-NULL. * * clientCB: * Function pointer will be called upon registration failure or * upon resolution completion. In the case of resolution, this * callback may be called multiple times if there is more than one * address for a service. Passing NULL will remove the client * from the entity and cancel any outstanding activity. * * clientContext: * Client contextual information to be used when calling clientCB. * Passing NULL will remove the client from the entity and cancel * any outstanding activity. * * Result: * Returns FALSE if the client could not be set, TRUE otherwise. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern Boolean CFNetServiceSetClient( CFNetServiceRef theService, CFNetServiceClientCallBack clientCB, /* can be NULL */ CFNetServiceClientContext * clientContext) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceScheduleWithRunLoop() * * Discussion: * Schedule the given service on the given run loop and mode. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The service which is set up for asynchronous mode. Must be * non-NULL. * * runLoop: * A reference to a runloop on which the service should be * scheduled. Must be non-NULL. * * runLoopMode: * The mode on which to schedule the service. Must be non-NULL. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceScheduleWithRunLoop( CFNetServiceRef theService, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceUnscheduleFromRunLoop() * * Discussion: * Unschedule the given service from the given run loop and mode. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The service which is set up for asynchronous mode. Must be * non-NULL. * * runLoop: * A reference to a runloop from which the service should be * unscheduled. Must be non-NULL. * * runLoopMode: * The mode from which to unschedule the service. Must be * non-NULL. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceUnscheduleFromRunLoop( CFNetServiceRef theService, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceMonitorCreate() * * Discussion: * Creates an instance of an object suitable for watching for * CFNetService record changes on the network. * * Mac OS X threading: * Thread safe * * Parameters: * * alloc: * The CFAllocator which should be used to allocate memory for the * monitor and its storage for values. If this reference is not a * valid CFAllocator, the behavior is undefined. * * theService: * The CFNetService to be monitored for record changes. * * clientCB: * Function pointer that will be called as record changes occur. * Must be non-NULL. * * clientContext: * Client contextual information to be used when calling clientCB. * Must be non-NULL. * * Result: * Returns a new instance of a CFNetServiceMonitor, or NULL if the * object could not be created. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFNetServiceMonitorRef CFNetServiceMonitorCreate( CFAllocatorRef alloc, CFNetServiceRef theService, CFNetServiceMonitorClientCallBack clientCB, CFNetServiceClientContext * clientContext) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceMonitorInvalidate() * * Discussion: * Invalidates the given monitor object so that it may no longer be * scheduled and callback never be called. This will also stop any * monitors currently in progress. * * Mac OS X threading: * Thread safe * * Parameters: * * monitor: * CFNetServiceMonitor to invalidate. Must be non-NULL. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceMonitorInvalidate(CFNetServiceMonitorRef monitor) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceMonitorStart() * * Discussion: * Starts monitoring for record changes on a service. It watches * for changes of the given record type. If there is already an * outstanding monitor, it will return FALSE. In synchronous mode, * this call blocks until the monitor is stopped. It will return * FALSE if there is an error performing the monitor or if there is * some other error. It will return TRUE otherwise. In * asynchronous mode, this call will return TRUE or FALSE depending * if the underlying network query could be instantiated. * * Mac OS X threading: * Thread safe * * Parameters: * * monitor: * CFNetServiceMonitor to perform the watch. * * recordType: * CFNetServiceMonitorType indicating the record type to watch. * * error: * A reference to an error struct which will be set to the error * and domain of the error should one occur. If the value of * error is not desired, set to NULL. * * Result: * Returns FALSE if an error occurs during a synchronous monitor or * if the monitor could not start. It returns TRUE otherwise. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern Boolean CFNetServiceMonitorStart( CFNetServiceMonitorRef monitor, CFNetServiceMonitorType recordType, CFStreamError * error) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceMonitorStop() * * Discussion: * Stops an outstanding monitor. * * Mac OS X threading: * Thread safe * * Parameters: * * monitor: * CFNetServiceMonitor with an active monitor. Must be non-NULL. * * error: * Error value to be returned in "error" in * CFNetServiceMonitorStart if monitor is being performed in * synchronous mode. In this case, a non-zero of the error field * of the struct will cause CFNetServiceMonitorStart to return * FALSE. In asynchronous mode, the client call back will be * called with this error. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceMonitorStop( CFNetServiceMonitorRef monitor, CFStreamError * error) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceMonitorScheduleWithRunLoop() * * Discussion: * Schedules the monitor on a run loop and mode. Use this to place * the given monitor into asynchronous mode. The client callback * will be triggered via one of the scheduled run loops; It is the * caller's responsibility to ensure that at least one of the * scheduled run loops is being run. * * Mac OS X threading: * Thread safe * * Parameters: * * monitor: * CFNetServiceMonitor to schedule. Must be non-NULL. * * runLoop: * A reference to a runloop on which the monitor should be * scheduled. Must be non-NULL. * * runLoopMode: * The mode on which to schedule the monitor. Must be non-NULL. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceMonitorScheduleWithRunLoop( CFNetServiceMonitorRef monitor, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceMonitorUnscheduleFromRunLoop() * * Discussion: * Unschedules the browser from a run loop and mode. * * Mac OS X threading: * Thread safe * * Parameters: * * monitor: * CFNetServiceMonitor to unschedule. Must be non-NULL. * * runLoop: * A reference to a runloop from which the monitor should be * unscheduled. Must be non-NULL. * * runLoopMode: * The mode from which to unschedule the monitor. Must be * non-NULL. * * Availability: * Mac OS X: in version 10.4 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceMonitorUnscheduleFromRunLoop( CFNetServiceMonitorRef monitor, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER; /* * CFNetServiceBrowserCreate() * * Discussion: * Creates an instance of a browser object. * * Mac OS X threading: * Thread safe * * Parameters: * * alloc: * The CFAllocator which should be used to allocate memory for the * browser and its storage for values. If this reference is not a * valid CFAllocator, the behavior is undefined. * * clientCB: * Function pointer that will be called as domains or services are * found on the network. Must be non-NULL. * * clientContext: * Client contextual information to be used when calling clientCB. * Must be non-NULL. * * Result: * Returns a new instance of a browser, or NULL if the instance * could not be created. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFNetServiceBrowserRef CFNetServiceBrowserCreate( CFAllocatorRef alloc, CFNetServiceBrowserClientCallBack clientCB, CFNetServiceClientContext * clientContext) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceBrowserInvalidate() * * Discussion: * Invalidates the given browser object so that it may no longer be * scheduled and callback never be called. This will also stop any * searches currently in progress. * * Parameters: * * browser: * Network Service Browser to invalidate. Must be non-NULL. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceBrowserInvalidate(CFNetServiceBrowserRef browser) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceBrowserSearchForDomains() * * Discussion: * Starts a search for domains. The browser will either try to find * "Browse" domains or will search for "Registration" domains. If * there is already an outstanding search, it will return FALSE. In * syncronous mode, this call blocks until the search is stopped. * It will return FALSE if there is an error performing the search. * It will return TRUE otherwise. In asynchronous mode, this call * will return TRUE or FALSE depending if the underlying network * search could be started. * * Mac OS X threading: * Thread safe * * Parameters: * * browser: * Network Service Browser to perform the search. Must be * non-NULL. * * registrationDomains: * FALSE if "Browse" domains are to be discovered. TRUE if only * "Registration" domains are to be discovered. * * error: * A reference to an error struct which will be set to the error * and domain of the error should one occur. If the value of * error is not desired, set to NULL. * * Result: * Returns FALSE if an error occurs during a synchronous search or * if the search could not start. It returns TRUE otherwise. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern Boolean CFNetServiceBrowserSearchForDomains( CFNetServiceBrowserRef browser, Boolean registrationDomains, CFStreamError * error) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceBrowserSearchForServices() * * Discussion: * Starts a search for a service type on the given domain. If there * is already an outstanding search, it will return FALSE. In * syncronous mode, this call blocks until the search is stopped. * It will return FALSE if there is an error performing the search * or if there is some other error. It will return TRUE otherwise. * In asynchronous mode, this call will return TRUE or FALSE * depending if the underlying network search could be instantiated. * * Mac OS X threading: * Thread safe * * Parameters: * * browser: * Network Service Browser to perform the search. Must be * non-NULL. * * domain: * Network domain to search in order to find the service. Must be * non-NULL. * * serviceType: * Service type for which to search. Must be non-NULL. * * error: * A reference to an error struct which will be set to the error * and domain of the error should one occur. If the value of * error is not desired, set to NULL. * * Result: * Returns FALSE if an error occurs during a synchronous search or * if the search could not start. It returns TRUE otherwise. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern Boolean CFNetServiceBrowserSearchForServices( CFNetServiceBrowserRef browser, CFStringRef domain, CFStringRef serviceType, CFStreamError * error) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceBrowserStopSearch() * * Discussion: * Stops an outstanding browser search. * * Mac OS X threading: * Thread safe * * Parameters: * * browser: * Network Service Browser performing the search. Must be * non-NULL. * * error: * Error value to be returned in "error" in * CFNetServiceBrowserStartServiceSearch if search is being * performed in synchronous mode. In this case, a non-zero of the * error field of the struct will cause * CFNetServiceBrowserStartServiceSearch to return FALSE. In * asynchronous mode, the client call back will be called with * this error. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceBrowserStopSearch( CFNetServiceBrowserRef browser, CFStreamError * error) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceBrowserScheduleWithRunLoop() * * Discussion: * Schedules the browser on a run loop and mode. Use this to place * the given browser into asynchronous mode. The client callback * will be triggered via one of the scheduled run loops; It is the * caller's responsibility to ensure that at least one of the * scheduled run loops is being run. * * Mac OS X threading: * Thread safe * * Parameters: * * browser: * Network Service Browser to schedule. Must be non-NULL. * * runLoop: * A reference to a runloop on which the browser should be * scheduled. Must be non-NULL. * * runLoopMode: * The mode on which to schedule the browser. Must be non-NULL. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceBrowserScheduleWithRunLoop( CFNetServiceBrowserRef browser, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceBrowserUnscheduleFromRunLoop() * * Discussion: * Unschedules the browser from a run loop and mode. * * Mac OS X threading: * Thread safe * * Parameters: * * browser: * Network Service Browser to unschedule. Must be non-NULL. * * runLoop: * A reference to a runloop from which the browser should be * unscheduled. Must be non-NULL. * * runLoopMode: * The mode from which to unschedule the browser. Must be * non-NULL. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceBrowserUnscheduleFromRunLoop( CFNetServiceBrowserRef browser, CFRunLoopRef runLoop, CFStringRef runLoopMode) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER; /* * CFNetServiceRegister() *** DEPRECATED *** * * Discussion: * Registers the entity on the network. This requires that the * service has a domain, a type, a name, and a port. The service is * registered on the network until this function returns or is * cancelled by calling CFNetServiceCancel. In synchronous mode, * this function will block until there is an error or it is * cancelled from another thread. In asynchronous mode, this * function returns immediately and the underlying network * registration process will start. * * As a result of new, better performing API's in Service Discovery, * users should now call CFNetServiceRegisterWithOptions. Using the * new calls will allow your application to perform better on the * network. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The Network Service to register on the network. Must be * non-NULL. * * error: * A reference to an error struct which will be set to the error * and domain of the error should one occur. If the value of * error is not desired, set to NULL. * * Result: * Returns FALSE if domain, type, name or port is NULL. In * synchronous mode, it will always return FALSE as a result of the * error or the cancellation. In asynchronous mode, it will return * TRUE if the registration process could start. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework but deprecated in 10.4 * CarbonLib: not available * Non-Carbon CFM: not available */ extern Boolean CFNetServiceRegister( CFNetServiceRef theService, CFStreamError * error) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4; /* * CFNetServiceResolve() *** DEPRECATED *** * * Discussion: * Resolves the addressing for the given service. This requires * that the service has a domain, a type, and a name. The service * is resolved on the network until this function returns or is * cancelled by calling CFNetServiceCancel. In synchronous mode, * this function will block until there is an error or it is * cancelled from another thread. In asynchronous mode, this * function returns immediately and the underlying network * resolution process will start. * * As a result of new, better performing API's in Service Discovery, * users should now call CFNetServiceResolveWithTimeout. If needing * to monitor TXT record changes, users should use the new * CFNetServiceMonitor object. Using the new calls will allow your * application to perform better on the network. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The Network Service to resolve on the network. Must be * non-NULL. * * error: * A reference to an error struct which will be set to the error * and domain of the error should one occur. If the value of * error is not desired, set to NULL. * * Result: * Returns FALSE if domain, type, or name is NULL. In synchronous * mode, it will return FALSE as a result of an error or a * cancellation. It will return TRUE if the resolution does * succeed. In asynchronous mode, it will return TRUE if the * resolution process could start. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework but deprecated in 10.4 * CarbonLib: not available * Non-Carbon CFM: not available */ extern Boolean CFNetServiceResolve( CFNetServiceRef theService, CFStreamError * error) /* can be NULL */ AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4; /* * CFNetServiceGetProtocolSpecificInformation() *** DEPRECATED *** * * Discussion: * Query a Network Service for its protocol specific information. * * * As a result of new, better performing API's in Service Discovery, * users should now call CFNetServiceGetTXTData. If needing to * monitor TXT record changes, users should use the new * CFNetServiceMonitor object. Using the new calls will allow your * application to perform better on the network. * * Mac OS X threading: * Thread safe * The function gets the data in a thread-safe manner, but the * resulting data is not safe. Since it is returned as a matter of * a get opposed to a copy, the data is not safe if the service is * being altered from another thread. * * Parameters: * * theService: * The Network Service to be queried. Must be non-NULL. * * Result: * Returns NULL if a resolve has not been performed or if * CFNetServiceSetProtocolSpecificInformation has not been called. * It will return a CFStringRef containing the specific information * if there is some. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework but deprecated in 10.4 * CarbonLib: not available * Non-Carbon CFM: not available */ extern CFStringRef CFNetServiceGetProtocolSpecificInformation(CFNetServiceRef theService) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4; /* * CFNetServiceSetProtocolSpecificInformation() *** DEPRECATED *** * * Discussion: * Set a Network Service's protocol specific information. * * As a result of new, better performing API's in Service Discovery, * users should now call CFNetServiceSetTXTData. Using the new * calls will allow your application to perform better on the * network. * * Mac OS X threading: * Thread safe * * Parameters: * * theService: * The Network Service to be queried. Must be non-NULL. * * theInfo: * The protocol specific information to be added. Pass NULL to * remove the information from the service. * * Availability: * Mac OS X: in version 10.2 and later in CoreServices.framework but deprecated in 10.4 * CarbonLib: not available * Non-Carbon CFM: not available */ extern void CFNetServiceSetProtocolSpecificInformation( CFNetServiceRef theService, CFStringRef theInfo) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_4; #if PRAGMA_ENUM_ALWAYSINT #pragma enumsalwaysint reset #endif #pragma options align=reset #ifdef __cplusplus } #endif #endif /* __CFNETSERVICES__ */