/*
 * Copyright (c) 2002 - 2004 Apple 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@
 */

/*
 * BSDPClient.h
 * - BSDP client library functions
 */
/* 
 * Modification History
 *
 * February 25, 2002	Dieter Siegmund (dieter@apple.com)
 * - initial revision
 * April 29, 2002	Dieter Siegmund (dieter@apple.com)
 * - added image kind and made the whole 32-bit identifier the
 *   unique id, rather than just the 16-bit index
 * - deprecated IsInstall and Index values, which are still supplied
 *   but should not be used
 */

#ifndef _S_BSDPCLIENT_H
#define _S_BSDPCLIENT_H

#include <CoreFoundation/CFDictionary.h>
#include <CoreFoundation/CFString.h>
#include <CoreFoundation/CFNumber.h>

struct BSDPClient_s;
typedef struct BSDPClient_s * BSDPClientRef;

enum {
    kBSDPClientStatusOK = 0,
    kBSDPClientStatusUnsupportedFirmware = 1,
    kBSDPClientStatusNoSuchInterface = 2,
    kBSDPClientStatusInterfaceNotConfigured = 3,
    kBSDPClientStatusInvalidArgument = 4,
    kBSDPClientStatusAllocationError = 5,
    kBSDPClientStatusPermissionDenied = 6,
    kBSDPClientStatusOperationTimedOut = 7,
    kBSDPClientStatusTransmitFailed = 8,
    kBSDPClientStatusServerSentFailure = 9,
    kBSDPClientStatusLast = 9
};
typedef uint32_t BSDPClientStatus;

enum {
    kBSDPImageKindMacOS9 = 0,
    kBSDPImageKindMacOSX = 1,
    kBSDPImageKindMacOSXServer = 2,
};
typedef uint32_t BSDPImageKind;

static __inline__ const char *
BSDPClientStatusString(BSDPClientStatus status)
{
    static const char * msg[] = {
	"OK",
	"Unsupported firmware",
	"No such interface",
	"Interface not configured",
	"Invalid argument",
	"Allocation error",
	"Permission denied",
	"Operation timed out",
	"Transmit failed",
	"Server sent failure",
    };

    if (status >= kBSDPClientStatusOK && status <= kBSDPClientStatusLast) {
	return (msg[status]);
    }
    return ("<unknown>");
}

/* 
 * BSDP Image Description Dictionary
 *
 * Each BSDP image description dictionary contains the keys
 * "Name", "Identifier", and "Index".  An image description may 
 * optionally contain any or all of the keys "IsDefault", 
 * "IsSelected", and "IsInstall".
 *
 * Notes:
 * 1) If multiple servers report an image whose "Identifier" is not local to the
 *    server, and the "Identifier" values are equal, they can be treated as the
 *    same image.  See BSDPImageDescriptionIdentifierIsServerLocal()
 *    defined below.
 * 2) "IsDefault" means the image is the default for this server.
 * 3) "IsSelected" means the image is the image that the client currently
 *    has a binding for with this server. Usually, just a single server
 *    will report a single image with this property, but if a server that
 *    had been off the network for awhile is suddenly placed on the 
 *    network again, more than one server may report this.
 */
/* mandatory keys, will be present: */
#define kBSDPImageDescriptionName	CFSTR("Name") /* CFString */
#define kBSDPImageDescriptionIdentifier	CFSTR("Identifier") /* CFNumber (32-bit) */
/* optional keys, may or may not be present: */
#define kBSDPImageDescriptionIsDefault	CFSTR("IsDefault") /* CFBoolean */
#define kBSDPImageDescriptionIsSelected	CFSTR("IsSelected") /* CFBoolean */

/* deprecated: use BSDPImageDescriptionImageIsInstall() instead */
#define kBSDPImageDescriptionIsInstall	CFSTR("IsInstall") /* CFBoolean */

/* deprecated: use "Identifier" instead */
#define kBSDPImageDescriptionIndex	CFSTR("Index") /* CFNumber (16-bit) */

/* 
 * Function: BSDPImageDescriptionIndexIsServerLocal 
 * Purpose:
 *    NOTE: This function is deprecated, use
 *    BSDPImageDescriptionIdentifierIsServerLocal() instead.
 */
Boolean
BSDPImageDescriptionIndexIsServerLocal(CFNumberRef index);

/*
 * Function: BSDPImageDescriptionIdentifierIsServerLocal
 * 
 * Purpose:
 *   Given the CFNumberRef corresponding to the "Identifier" property
 *   from the image description dictionary, returns whether it is a
 *   server local image.
 *
 *   If the "Identifier" for an image is server local, the image must be
 *   presented as a unique item in the list presented to the user.  
 *   If the "Identifier" for an image is not server local, and more than
 *   one servers supply an image with same "Identifier", they may be
 *   presented as a single choice in the list presented to the user.
 */
Boolean
BSDPImageDescriptionIdentifierIsServerLocal(CFNumberRef identifier);

/*
 * Function: BSDPImageDescriptionIdentifierImageKind 
 * Purpose:
 *   Returns the BSDPImageKind for the given identifier.
  */
BSDPImageKind
BSDPImageDescriptionIdentifierImageKind(CFNumberRef identifier);

/*
 * Function: BSDPImageDescriptionIdentifierIsInstall
 * Purpose:
 *   Returns whether the identifier refers to an install image or not.
 */
Boolean
BSDPImageDescriptionIdentifierIsInstall(CFNumberRef identifier);


/*
 * Type: BSDPClientListCallBack
 *
 * Purpose:
 *   The prototype for the List operation callback function.
 *   The function is called when new image information is
 *   available, and is provided with an array of image description
 *   dictionaries.  This array must NOT be released.
 *   See the "BSDP Image Description Dictionary" discussion above.
 *
 * Parameters:
 *   client	the BSDPClientRef allocated using Create
 *   status	the status of the List operation
 *   list	an array of image description dictionaries,
 *              must NOT be CFRelease()'d
 *   info	the caller-supplied opaque handle supplied to BSDPClientList()
 *
 * Note:
 *   It's possible that duplicate responses may be received due to loops
 *   in the network.  It is the caller's responsibility to update
 *   its accumulated list appropriately in this case.  One simple strategy
 *   is to remove any existing image description dictionaries with the
 *   given ServerAddress before accumulating any new ones.
 */    
typedef void (*BSDPClientListCallBack)(BSDPClientRef client, 
				       BSDPClientStatus status,
				       CFStringRef ServerAddress,
				       CFNumberRef ServerPriority,
				       CFArrayRef list,
				       void *info);

/*
 * Type: BSDPClientSelectCallBack
 *
 * Purpose:
 *   The prototype for the Select operation callback.
 *   This function is called when the Select operation either
 *   succeeds or fails.
 *
 * Parameters:
 *   client	the BSDPClientRef created using BSDPClientCreate()
 *   status	the status of the Select operation
 *   info	the caller-supplied opaque handle supplied to BSDPClientSelect()
 */    
typedef void (*BSDPClientSelectCallBack)(BSDPClientRef client,
					 BSDPClientStatus status, 
					 void *info);

/*
 * Function: BSDPClientCreate
 *
 * Purpose:
 *   Allocate and initialize a BSDPClientRef for the default interface.
 *   The BSDPClientRef is used with BSDPClientList() and BSDPClientSelect().
 *
 * Returns:
 *   A non-NULL BSDPClientRef if successful, NULL otherwise.
 *   The status is returned in *status_p.
 */
BSDPClientRef
BSDPClientCreate(BSDPClientStatus * status_p);

/*
 * Function: BSDPClientCreateWithInterface
 *
 * Purpose:
 *   Allocate and initialize a BSDPClientRef for the specified interface.
 *   The BSDPClientRef is used with BSDPClientList() and BSDPClientSelect().
 *
 * Returns:
 *   A non-NULL BSDPClientRef if successful, NULL otherwise.
 *   The status is returned in *status_p.
 */
BSDPClientRef
BSDPClientCreateWithInterface(BSDPClientStatus * status_p,
			      const char * ifname);
/*
 * Function: BSDPClientFree
 * Purpose:
 *   Release resources allocated during the use of the BSDPClientRef.
 */
void
BSDPClientFree(BSDPClientRef * client_p);

/*
 * Function: BSDPClientList
 *
 * Purpose:
 *   Send a BSDP List request, and wait for responses.  If no responses
 *   appear, retry the request, doubling the timeout.
 *
 *   When a response arrives, decode it and build an array of BSDP image
 *   description dictionaries (see discussion above), and pass it to the
 *   callback.
 *
 *   If no responses arrive after 1 minute of trying, or some other
 *   error occurs, the callback is called with the appropriate status.
 *
 * Parameters:
 *   client		The client handle created using BSDPClientCreate().
 *   callback		The function to call when image information is
 *  			available, or when an error occurs.
 *   info		The caller-supplied argument to pass to the callback.
 *
 * Returns:
 *   kBSDPClientStatusOK if List process started successfully.
 *   If an error occurred, some other status is returned.
 */
BSDPClientStatus
BSDPClientList(BSDPClientRef client, BSDPClientListCallBack callback, 
	       void * info);

/*
 * Function: BSDPClientSelect
 *
 * Purpose:
 *   Once the user has made a selection, this function is called to
 *   create a binding with a particular server/image.
 *
 * Parameters:
 *   client		The client handle created using BSDPClientCreate().
 *   ServerAddress	The ServerAddress value suppled to the list 
 *                      callback function.
 *   Identifier		The value of the kBSDPImageDescriptionIdentifier property
 *			from the selected BSDP Image Description dictionary.
 *   callback		The function to call when status is available.
 *   info		The caller-supplied argument to pass to the callback.
 */
BSDPClientStatus
BSDPClientSelect(BSDPClientRef client, 
		 CFStringRef ServerAddress,
		 CFNumberRef Identifier,
		 BSDPClientSelectCallBack callback, void * info);
		      
#endif /* _S_BSDPCLIENT_H */