/* usb/reference.h
 *
 * (c) 2002 Simtec Electronics
 *
 * Ben Dooks
 *
 * reference count routines
 *
 * $Id: reference.h,v 1.7 2003/08/06 15:56:11 ben Exp $
 *
 * This Library file is part of the Simtec Electronics USB stack development
 *   suite.
 * Specific licence is granted to use this file by third parties for the
 *   development of USB device drivers.
 *
 */

#ifndef __USB_REFERENCE_H
#define __USB_REFERENCE_H "$Id: reference.h,v 1.7 2003/08/06 15:56:11 ben Exp $"

/** De-register reference to a structure
@param structure_to_unprotect Structure to unprotect.
@param reference_type Type of de-reference.
@return result
@see SWI_USB_ReferenceDeregister
@see USB_REFERENCE_ENDPOINT
@see USB_REFERENCE_DEVICE
@see USB_REFERENCE_CONTROLLER
*/
extern int usb_reference_deregister(void *structure_to_unprotect,
				    int reference_type);

/**  find an object, or enumerate current objects
This call can either be used to find a specific object given a base to
start from, or can be used to enumerate all objects of a specific type.

When used with USB_FIND_NEXT_OBJECT the system will keep returning objects
until the full set is enumerated. search_result is used to keep track of
where the search is currently, and it should be initialised to NULL.

object_tag provides a filter for the objects when searching, or the
value of the specific object when finding. The type of object_tag is
dependant on the object type, USB_REFERENCE_ENDPOINT takes the endpoint
number, USB_REFERENCE_DEVICE takes the device number, and
USB_REFERENCE_CONTROLLER takes a pointer to the controller name.

result points to a integer to place the result of the search in
and returns a pointer to the item if result == USB_RESULT_OK

The returned object's reference count will have been incremented before
it is returned. You will need to call usb_object_deregister() once you
have finished with the object.

@memo  find an object, or enumerate current objects
@param master_structure
@param object_tag
@param reference_type
@param behaviour_control
@param result_tag
@param result
@see SWI_USB_FindObject
@see USB_FIND_KEEP_REFERENCE
@see USB_FIND_NEXT_OBJECT
@see USB_REFERENCE_ENDPOINT
@see USB_REFERENCE_DEVICE
@see USB_REFERENCE_CONTROLLER
@see usb_reference_deregister
*/
extern void* usb_find_object(void *master_structure,
			     unsigned long object_tag,
			     int reference_type,
			     unsigned long behaviour_control,
			     unsigned long *result_tag,
			     int *result);

#endif /* __USB_REFERENCE_H */
