1/* 2 * Copyright (c) 2002 - 2004 Apple Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24/* 25 * BSDPClient.h 26 * - BSDP client library functions 27 */ 28/* 29 * Modification History 30 * 31 * February 25, 2002 Dieter Siegmund (dieter@apple.com) 32 * - initial revision 33 * April 29, 2002 Dieter Siegmund (dieter@apple.com) 34 * - added image kind and made the whole 32-bit identifier the 35 * unique id, rather than just the 16-bit index 36 * - deprecated IsInstall and Index values, which are still supplied 37 * but should not be used 38 */ 39 40#ifndef _S_BSDPCLIENT_H 41#define _S_BSDPCLIENT_H 42 43#include <CoreFoundation/CFDictionary.h> 44#include <CoreFoundation/CFString.h> 45#include <CoreFoundation/CFNumber.h> 46 47struct BSDPClient_s; 48typedef struct BSDPClient_s * BSDPClientRef; 49 50enum { 51 kBSDPClientStatusOK = 0, 52 kBSDPClientStatusUnsupportedFirmware = 1, 53 kBSDPClientStatusNoSuchInterface = 2, 54 kBSDPClientStatusInterfaceNotConfigured = 3, 55 kBSDPClientStatusInvalidArgument = 4, 56 kBSDPClientStatusAllocationError = 5, 57 kBSDPClientStatusPermissionDenied = 6, 58 kBSDPClientStatusOperationTimedOut = 7, 59 kBSDPClientStatusTransmitFailed = 8, 60 kBSDPClientStatusServerSentFailure = 9, 61 kBSDPClientStatusLast = 9 62}; 63typedef uint32_t BSDPClientStatus; 64 65enum { 66 kBSDPImageKindMacOS9 = 0, 67 kBSDPImageKindMacOSX = 1, 68 kBSDPImageKindMacOSXServer = 2, 69}; 70typedef uint32_t BSDPImageKind; 71 72static __inline__ const char * 73BSDPClientStatusString(BSDPClientStatus status) 74{ 75 static const char * msg[] = { 76 "OK", 77 "Unsupported firmware", 78 "No such interface", 79 "Interface not configured", 80 "Invalid argument", 81 "Allocation error", 82 "Permission denied", 83 "Operation timed out", 84 "Transmit failed", 85 "Server sent failure", 86 }; 87 88 if (status >= kBSDPClientStatusOK && status <= kBSDPClientStatusLast) { 89 return (msg[status]); 90 } 91 return ("<unknown>"); 92} 93 94/* 95 * BSDP Image Description Dictionary 96 * 97 * Each BSDP image description dictionary contains the keys 98 * "Name", "Identifier", and "Index". An image description may 99 * optionally contain any or all of the keys "IsDefault", 100 * "IsSelected", and "IsInstall". 101 * 102 * Notes: 103 * 1) If multiple servers report an image whose "Identifier" is not local to the 104 * server, and the "Identifier" values are equal, they can be treated as the 105 * same image. See BSDPImageDescriptionIdentifierIsServerLocal() 106 * defined below. 107 * 2) "IsDefault" means the image is the default for this server. 108 * 3) "IsSelected" means the image is the image that the client currently 109 * has a binding for with this server. Usually, just a single server 110 * will report a single image with this property, but if a server that 111 * had been off the network for awhile is suddenly placed on the 112 * network again, more than one server may report this. 113 */ 114/* mandatory keys, will be present: */ 115#define kBSDPImageDescriptionName CFSTR("Name") /* CFString */ 116#define kBSDPImageDescriptionIdentifier CFSTR("Identifier") /* CFNumber (32-bit) */ 117/* optional keys, may or may not be present: */ 118#define kBSDPImageDescriptionIsDefault CFSTR("IsDefault") /* CFBoolean */ 119#define kBSDPImageDescriptionIsSelected CFSTR("IsSelected") /* CFBoolean */ 120 121/* deprecated: use BSDPImageDescriptionImageIsInstall() instead */ 122#define kBSDPImageDescriptionIsInstall CFSTR("IsInstall") /* CFBoolean */ 123 124/* deprecated: use "Identifier" instead */ 125#define kBSDPImageDescriptionIndex CFSTR("Index") /* CFNumber (16-bit) */ 126 127/* 128 * Function: BSDPImageDescriptionIndexIsServerLocal 129 * Purpose: 130 * NOTE: This function is deprecated, use 131 * BSDPImageDescriptionIdentifierIsServerLocal() instead. 132 */ 133Boolean 134BSDPImageDescriptionIndexIsServerLocal(CFNumberRef index); 135 136/* 137 * Function: BSDPImageDescriptionIdentifierIsServerLocal 138 * 139 * Purpose: 140 * Given the CFNumberRef corresponding to the "Identifier" property 141 * from the image description dictionary, returns whether it is a 142 * server local image. 143 * 144 * If the "Identifier" for an image is server local, the image must be 145 * presented as a unique item in the list presented to the user. 146 * If the "Identifier" for an image is not server local, and more than 147 * one servers supply an image with same "Identifier", they may be 148 * presented as a single choice in the list presented to the user. 149 */ 150Boolean 151BSDPImageDescriptionIdentifierIsServerLocal(CFNumberRef identifier); 152 153/* 154 * Function: BSDPImageDescriptionIdentifierImageKind 155 * Purpose: 156 * Returns the BSDPImageKind for the given identifier. 157 */ 158BSDPImageKind 159BSDPImageDescriptionIdentifierImageKind(CFNumberRef identifier); 160 161/* 162 * Function: BSDPImageDescriptionIdentifierIsInstall 163 * Purpose: 164 * Returns whether the identifier refers to an install image or not. 165 */ 166Boolean 167BSDPImageDescriptionIdentifierIsInstall(CFNumberRef identifier); 168 169 170/* 171 * Type: BSDPClientListCallBack 172 * 173 * Purpose: 174 * The prototype for the List operation callback function. 175 * The function is called when new image information is 176 * available, and is provided with an array of image description 177 * dictionaries. This array must NOT be released. 178 * See the "BSDP Image Description Dictionary" discussion above. 179 * 180 * Parameters: 181 * client the BSDPClientRef allocated using Create 182 * status the status of the List operation 183 * list an array of image description dictionaries, 184 * must NOT be CFRelease()'d 185 * info the caller-supplied opaque handle supplied to BSDPClientList() 186 * 187 * Note: 188 * It's possible that duplicate responses may be received due to loops 189 * in the network. It is the caller's responsibility to update 190 * its accumulated list appropriately in this case. One simple strategy 191 * is to remove any existing image description dictionaries with the 192 * given ServerAddress before accumulating any new ones. 193 */ 194typedef void (*BSDPClientListCallBack)(BSDPClientRef client, 195 BSDPClientStatus status, 196 CFStringRef ServerAddress, 197 CFNumberRef ServerPriority, 198 CFArrayRef list, 199 void *info); 200 201/* 202 * Type: BSDPClientSelectCallBack 203 * 204 * Purpose: 205 * The prototype for the Select operation callback. 206 * This function is called when the Select operation either 207 * succeeds or fails. 208 * 209 * Parameters: 210 * client the BSDPClientRef created using BSDPClientCreate() 211 * status the status of the Select operation 212 * info the caller-supplied opaque handle supplied to BSDPClientSelect() 213 */ 214typedef void (*BSDPClientSelectCallBack)(BSDPClientRef client, 215 BSDPClientStatus status, 216 void *info); 217 218/* 219 * Function: BSDPClientCreate 220 * 221 * Purpose: 222 * Allocate and initialize a BSDPClientRef for the default interface. 223 * The BSDPClientRef is used with BSDPClientList() and BSDPClientSelect(). 224 * 225 * Returns: 226 * A non-NULL BSDPClientRef if successful, NULL otherwise. 227 * The status is returned in *status_p. 228 */ 229BSDPClientRef 230BSDPClientCreate(BSDPClientStatus * status_p); 231 232/* 233 * Function: BSDPClientCreateWithInterface 234 * 235 * Purpose: 236 * Allocate and initialize a BSDPClientRef for the specified interface. 237 * The BSDPClientRef is used with BSDPClientList() and BSDPClientSelect(). 238 * 239 * Returns: 240 * A non-NULL BSDPClientRef if successful, NULL otherwise. 241 * The status is returned in *status_p. 242 */ 243BSDPClientRef 244BSDPClientCreateWithInterface(BSDPClientStatus * status_p, 245 const char * ifname); 246/* 247 * Function: BSDPClientFree 248 * Purpose: 249 * Release resources allocated during the use of the BSDPClientRef. 250 */ 251void 252BSDPClientFree(BSDPClientRef * client_p); 253 254/* 255 * Function: BSDPClientList 256 * 257 * Purpose: 258 * Send a BSDP List request, and wait for responses. If no responses 259 * appear, retry the request, doubling the timeout. 260 * 261 * When a response arrives, decode it and build an array of BSDP image 262 * description dictionaries (see discussion above), and pass it to the 263 * callback. 264 * 265 * If no responses arrive after 1 minute of trying, or some other 266 * error occurs, the callback is called with the appropriate status. 267 * 268 * Parameters: 269 * client The client handle created using BSDPClientCreate(). 270 * callback The function to call when image information is 271 * available, or when an error occurs. 272 * info The caller-supplied argument to pass to the callback. 273 * 274 * Returns: 275 * kBSDPClientStatusOK if List process started successfully. 276 * If an error occurred, some other status is returned. 277 */ 278BSDPClientStatus 279BSDPClientList(BSDPClientRef client, BSDPClientListCallBack callback, 280 void * info); 281 282/* 283 * Function: BSDPClientSelect 284 * 285 * Purpose: 286 * Once the user has made a selection, this function is called to 287 * create a binding with a particular server/image. 288 * 289 * Parameters: 290 * client The client handle created using BSDPClientCreate(). 291 * ServerAddress The ServerAddress value suppled to the list 292 * callback function. 293 * Identifier The value of the kBSDPImageDescriptionIdentifier property 294 * from the selected BSDP Image Description dictionary. 295 * callback The function to call when status is available. 296 * info The caller-supplied argument to pass to the callback. 297 */ 298BSDPClientStatus 299BSDPClientSelect(BSDPClientRef client, 300 CFStringRef ServerAddress, 301 CFNumberRef Identifier, 302 BSDPClientSelectCallBack callback, void * info); 303 304#endif /* _S_BSDPCLIENT_H */ 305 306