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