[apple/xnu.git] / iokit / IOKit / IOUserClient.h

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_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. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 * 
 * 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_OSREFERENCE_LICENSE_HEADER_END@
 */

/*
 * Changes to this API are expected.
 */

#ifndef _IOKIT_IOUSERCLIENT_H
#define _IOKIT_IOUSERCLIENT_H

#include <IOKit/IOTypes.h>
#include <IOKit/IOService.h>
#include <IOKit/OSMessageNotification.h>

#if IOKITSTATS
#include <IOKit/IOStatisticsPrivate.h>
#endif

#define _IOUSERCLIENT_SENDASYNCRESULT64WITHOPTIONS_		1

enum {
    kIOUCTypeMask	= 0x0000000f,
    kIOUCScalarIScalarO = 0,
    kIOUCScalarIStructO = 2,
    kIOUCStructIStructO = 3,
    kIOUCScalarIStructI = 4,

    kIOUCForegroundOnly = 0x00000010,
};

/*! @enum
    @abstract Constant to denote a variable length structure argument to IOUserClient.
    @constant kIOUCVariableStructureSize Use in the structures IOExternalMethod, IOExternalAsyncMethod, IOExternalMethodDispatch to specify the size of the structure is variable.
*/
enum {
    kIOUCVariableStructureSize = 0xffffffff
};


typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,
                                        void * p4, void * p5, void * p6 );

typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
                                        void * p1, void * p2, void * p3,
                                        void * p4, void * p5, void * p6 );

typedef IOReturn (IOService::*IOTrap)(void * p1, void * p2, void * p3,
                                      void * p4, void * p5, void * p6 );

struct IOExternalMethod {
    IOService *		object;
    IOMethod		func;
    IOOptionBits	flags;
    IOByteCount		count0;
    IOByteCount		count1;
};

struct IOExternalAsyncMethod {
    IOService *		object;
    IOAsyncMethod	func;
    IOOptionBits	flags;
    IOByteCount		count0;
    IOByteCount		count1;
};

struct IOExternalTrap {
    IOService *		object;
    IOTrap		func;
};

enum {
    kIOUserNotifyMaxMessageSize = 64
};

enum {
    kIOUserNotifyOptionCanDrop = 0x1 /* Fail if queue is full, rather than infinitely queuing. */
};

// keys for clientHasPrivilege
#define kIOClientPrivilegeAdministrator	"root"
#define kIOClientPrivilegeLocalUser	"local"
#define kIOClientPrivilegeForeground	"foreground"

/*! @enum
    @abstract Constants to specify the maximum number of scalar arguments in the IOExternalMethodArguments structure. These constants are documentary since the scalarInputCount, scalarOutputCount fields reflect the actual number passed.
    @constant kIOExternalMethodScalarInputCountMax The maximum number of scalars able to passed on input.
    @constant kIOExternalMethodScalarOutputCountMax The maximum number of scalars able to passed on output.
*/
enum {
    kIOExternalMethodScalarInputCountMax  = 16,
    kIOExternalMethodScalarOutputCountMax = 16,
};


struct IOExternalMethodArguments
{
    uint32_t		version;

    uint32_t		selector;

    mach_port_t           asyncWakePort;
    io_user_reference_t * asyncReference;
    uint32_t              asyncReferenceCount;

    const uint64_t *    scalarInput;
    uint32_t		scalarInputCount;

    const void *	structureInput;
    uint32_t		structureInputSize;

    IOMemoryDescriptor * structureInputDescriptor;
   
    uint64_t *		scalarOutput;
    uint32_t		scalarOutputCount;

    void *		structureOutput;
    uint32_t		structureOutputSize;

    IOMemoryDescriptor * structureOutputDescriptor;
    uint32_t		 structureOutputDescriptorSize;

    uint32_t		__reservedA;

    OSObject **         structureVariableOutputData;

    uint32_t		__reserved[30];
};

typedef IOReturn (*IOExternalMethodAction)(OSObject * target, void * reference, 
					    IOExternalMethodArguments * arguments);
struct IOExternalMethodDispatch
{
    IOExternalMethodAction function;
    uint32_t		   checkScalarInputCount;
    uint32_t		   checkStructureInputSize;
    uint32_t		   checkScalarOutputCount;
    uint32_t		   checkStructureOutputSize;
};

enum {
#define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION	2
    kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
};


/*!
    @class IOUserClient
    @abstract   Provides a basis for communication between client applications and I/O Kit objects.
*/


class IOUserClient : public IOService
{
    OSDeclareAbstractStructors(IOUserClient)
#if IOKITSTATS
    friend class IOStatistics;
#endif

protected:
/*! @struct ExpansionData
    @discussion This structure will be used to expand the capablilties of this class in the future.
*/    
    struct ExpansionData {
#if IOKITSTATS
	    IOUserClientCounter *counter;
#else
	    void *iokitstatsReserved;
#endif
    };

/*! @var reserved
    Reserved for future use.  (Internal use only) 
*/
    ExpansionData * reserved;

    bool reserve();

#ifdef XNU_KERNEL_PRIVATE
public:
#else
private:
#endif
    OSSet * mappings;
    UInt8   sharedInstance;
    UInt8   __reservedA[3];
    void  * __reserved[7];

public:
   virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
					IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );

   virtual IOReturn registerNotificationPort(
					mach_port_t port, UInt32 type, io_user_reference_t refCon);

private:
#if __LP64__
    OSMetaClassDeclareReservedUnused(IOUserClient, 0);
    OSMetaClassDeclareReservedUnused(IOUserClient, 1);
#else
    OSMetaClassDeclareReservedUsed(IOUserClient, 0);
    OSMetaClassDeclareReservedUsed(IOUserClient, 1);
#endif
    OSMetaClassDeclareReservedUnused(IOUserClient, 2);
    OSMetaClassDeclareReservedUnused(IOUserClient, 3);
    OSMetaClassDeclareReservedUnused(IOUserClient, 4);
    OSMetaClassDeclareReservedUnused(IOUserClient, 5);
    OSMetaClassDeclareReservedUnused(IOUserClient, 6);
    OSMetaClassDeclareReservedUnused(IOUserClient, 7);
    OSMetaClassDeclareReservedUnused(IOUserClient, 8);
    OSMetaClassDeclareReservedUnused(IOUserClient, 9);
    OSMetaClassDeclareReservedUnused(IOUserClient, 10);
    OSMetaClassDeclareReservedUnused(IOUserClient, 11);
    OSMetaClassDeclareReservedUnused(IOUserClient, 12);
    OSMetaClassDeclareReservedUnused(IOUserClient, 13);
    OSMetaClassDeclareReservedUnused(IOUserClient, 14);
    OSMetaClassDeclareReservedUnused(IOUserClient, 15);

#ifdef XNU_KERNEL_PRIVATE
    /* Available within xnu source only */
public:
    static void initialize( void );
    static void destroyUserReferences( OSObject * obj );
    IOMemoryMap * mapClientMemory64( IOOptionBits type,
                                    task_t task,
                                    IOOptionBits mapFlags = kIOMapAnywhere,
				    mach_vm_address_t atAddress = 0 );
#endif

protected:
    static IOReturn sendAsyncResult(OSAsyncReference reference,
                                    IOReturn result, void *args[], UInt32 numArgs);
    static void setAsyncReference(OSAsyncReference asyncRef,
                                  mach_port_t wakePort,
                                  void *callback, void *refcon);

    static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
                                        IOReturn result, io_user_reference_t args[], UInt32 numArgs);

    /*! 
        @function sendAsyncResult64WithOptions
        @abstract Send a notification as with sendAsyncResult, but with finite queueing.
        @discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
                is not processing them in a timely fashion.  This variant will not, for simple
                handling of situations where clients may be expected to stop processing messages.
     */
    static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
                                        IOReturn result, io_user_reference_t args[], UInt32 numArgs, 
					IOOptionBits options);

    static void setAsyncReference64(OSAsyncReference64 asyncRef,
					mach_port_t wakePort,
					mach_vm_address_t callback, io_user_reference_t refcon);

    static void setAsyncReference64(OSAsyncReference64 asyncRef,
					mach_port_t wakePort,
					mach_vm_address_t callback, io_user_reference_t refcon,
                    task_t task);

public:

    static IOReturn clientHasPrivilege( void * securityToken,
                                        const char * privilegeName );

    /*!
        @function releaseAsyncReference64
	@abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
	@discussion The OSAsyncReference64 structure passed to async methods holds a reference to the wakeup mach port, which should be released to balance each async method call. Behavior is undefined if these calls are not correctly balanced.
        @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
        @result A return code.
    */
    static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
    /*!
        @function releaseNotificationPort
	@abstract Release the mach_port_t passed to registerNotificationPort().
	@discussion The mach_port_t passed to the registerNotificationPort() methods should be released to balance each call to registerNotificationPort(). Behavior is undefined if these calls are not correctly balanced.
        @param reference The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
        @result A return code.
    */
    static IOReturn releaseNotificationPort(mach_port_t port);

    virtual bool init();
    virtual bool init( OSDictionary * dictionary );
    // Currently ignores the all args, just passes up to IOService::init()
    virtual bool initWithTask(
                    task_t owningTask, void * securityToken, UInt32 type,
                    OSDictionary * properties);

    virtual bool initWithTask(
                    task_t owningTask, void * securityToken, UInt32 type);

    virtual void free();

    virtual IOReturn clientClose( void );
    virtual IOReturn clientDied( void );

    virtual IOService * getService( void );

    virtual IOReturn registerNotificationPort(
		mach_port_t port, UInt32 type, UInt32 refCon );

    virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
                                    semaphore_t * semaphore );

    virtual IOReturn connectClient( IOUserClient * client );

    // memory will be released by user client when last map is destroyed
    virtual IOReturn clientMemoryForType( UInt32 type,
			        IOOptionBits * options,
				IOMemoryDescriptor ** memory );

#if !__LP64__
private:
	APPLE_KEXT_COMPATIBILITY_VIRTUAL
	IOMemoryMap * mapClientMemory( IOOptionBits type,
                                    task_t task,
                                    IOOptionBits mapFlags = kIOMapAnywhere,
									IOVirtualAddress atAddress = 0 );
#endif

    static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
                                    IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
public:

    /*!
        @function removeMappingForDescriptor
        Remove the first mapping created from the memory descriptor returned by clientMemoryForType() from IOUserClient's list of mappings. If such a mapping exists, it is retained and the reference currently held by IOUserClient is returned to the caller.
        @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
        @result A reference to the first IOMemoryMap instance found in the list of mappings created by IOUserClient from that passed memory descriptor is returned, or zero if none exist. The caller should release this reference.
    */
    IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);

    /*!
        @function exportObjectToClient
        Make an arbitrary OSObject available to the client task.
        @param task The task.
        @param obj The object we want to export to the client.
        @param clientObj Returned value is the client's port name.
    */
    virtual IOReturn exportObjectToClient(task_t task,
				OSObject *obj, io_object_t *clientObj);

    // Old methods for accessing method vector backward compatiblility only
    virtual IOExternalMethod *
        getExternalMethodForIndex( UInt32 index )
	APPLE_KEXT_DEPRECATED;
    virtual IOExternalAsyncMethod *
        getExternalAsyncMethodForIndex( UInt32 index )
	APPLE_KEXT_DEPRECATED;

    // Methods for accessing method vector.
    virtual IOExternalMethod *
        getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
    virtual IOExternalAsyncMethod *
        getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );

    // Methods for accessing trap vector - old and new style
    virtual IOExternalTrap *
		getExternalTrapForIndex( UInt32 index )
	APPLE_KEXT_DEPRECATED;

    virtual IOExternalTrap *
      getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
};

#endif /* ! _IOKIT_IOUSERCLIENT_H */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b	5	*
2d21ac55 A	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. The rights granted to you under the License
	10	* may not be used to create, or enable the creation or redistribution of,
	11	* unlawful or unlicensed copies of an Apple operating system, or to
	12	* circumvent, violate, or enable the circumvention or violation of, any
	13	* terms of an Apple operating system software license agreement.
8f6c56a5	14	*
2d21ac55 A	15	* Please obtain a copy of the License at
	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
	17	*
	18	* The Original Code and all software distributed under the License are
	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
	24	* limitations under the License.
8f6c56a5	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b A	27	*/
	28
	29	/*
	30	* Changes to this API are expected.
	31	*/
	32
	33	#ifndef _IOKIT_IOUSERCLIENT_H
	34	#define _IOKIT_IOUSERCLIENT_H
	35
	36	#include <IOKit/IOTypes.h>
	37	#include <IOKit/IOService.h>
	38	#include <IOKit/OSMessageNotification.h>
	39
6d2010ae A	40	#if IOKITSTATS
	41	#include <IOKit/IOStatisticsPrivate.h>
	42	#endif
1c79356b	43
39236c6e A	44	#define _IOUSERCLIENT_SENDASYNCRESULT64WITHOPTIONS_ 1
39236c6e A	45
1c79356b A	46	enum {
	47	kIOUCTypeMask = 0x0000000f,
	48	kIOUCScalarIScalarO = 0,
	49	kIOUCScalarIStructO = 2,
	50	kIOUCStructIStructO = 3,
d1ecb069 A	51	kIOUCScalarIStructI = 4,
	52
	53	kIOUCForegroundOnly = 0x00000010,
1c79356b A	54	};
1c79356b A	55
2d21ac55 A	56	/*! @enum
	57	@abstract Constant to denote a variable length structure argument to IOUserClient.
	58	@constant kIOUCVariableStructureSize Use in the structures IOExternalMethod, IOExternalAsyncMethod, IOExternalMethodDispatch to specify the size of the structure is variable.
	59	*/
	60	enum {
	61	kIOUCVariableStructureSize = 0xffffffff
	62	};
	63
	64
1c79356b A	65	typedef IOReturn (IOService::IOMethod)(void p1, void * p2, void * p3,
	66	void * p4, void * p5, void * p6 );
	67
	68	typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
	69	void * p1, void * p2, void * p3,
	70	void * p4, void * p5, void * p6 );
	71
	72	typedef IOReturn (IOService::IOTrap)(void p1, void * p2, void * p3,
	73	void * p4, void * p5, void * p6 );
	74
	75	struct IOExternalMethod {
	76	IOService * object;
	77	IOMethod func;
	78	IOOptionBits flags;
	79	IOByteCount count0;
	80	IOByteCount count1;
	81	};
	82
	83	struct IOExternalAsyncMethod {
	84	IOService * object;
	85	IOAsyncMethod func;
	86	IOOptionBits flags;
	87	IOByteCount count0;
	88	IOByteCount count1;
	89	};
	90
	91	struct IOExternalTrap {
	92	IOService * object;
	93	IOTrap func;
	94	};
	95
	96	enum {
	97	kIOUserNotifyMaxMessageSize = 64
	98	};
	99
39236c6e A	100	enum {
	101	kIOUserNotifyOptionCanDrop = 0x1 /* Fail if queue is full, rather than infinitely queuing. */
	102	};
	103
1c79356b A	104	// keys for clientHasPrivilege
	105	#define kIOClientPrivilegeAdministrator "root"
	106	#define kIOClientPrivilegeLocalUser "local"
d1ecb069	107	#define kIOClientPrivilegeForeground "foreground"
1c79356b	108
2d21ac55 A	109	/*! @enum
	110	@abstract Constants to specify the maximum number of scalar arguments in the IOExternalMethodArguments structure. These constants are documentary since the scalarInputCount, scalarOutputCount fields reflect the actual number passed.
	111	@constant kIOExternalMethodScalarInputCountMax The maximum number of scalars able to passed on input.
	112	@constant kIOExternalMethodScalarOutputCountMax The maximum number of scalars able to passed on output.
	113	*/
	114	enum {
	115	kIOExternalMethodScalarInputCountMax = 16,
	116	kIOExternalMethodScalarOutputCountMax = 16,
	117	};
	118
	119
	120	struct IOExternalMethodArguments
	121	{
	122	uint32_t version;
	123
	124	uint32_t selector;
	125
	126	mach_port_t asyncWakePort;
	127	io_user_reference_t * asyncReference;
	128	uint32_t asyncReferenceCount;
	129
	130	const uint64_t * scalarInput;
	131	uint32_t scalarInputCount;
	132
	133	const void * structureInput;
	134	uint32_t structureInputSize;
	135
	136	IOMemoryDescriptor * structureInputDescriptor;
	137
	138	uint64_t * scalarOutput;
	139	uint32_t scalarOutputCount;
	140
	141	void * structureOutput;
	142	uint32_t structureOutputSize;
	143
	144	IOMemoryDescriptor * structureOutputDescriptor;
	145	uint32_t structureOutputDescriptorSize;
	146
ebb1b9f4 A	147	uint32_t __reservedA;
	148
	149	OSObject ** structureVariableOutputData;
	150
	151	uint32_t __reserved[30];
2d21ac55 A	152	};
	153
	154	typedef IOReturn (IOExternalMethodAction)(OSObject target, void * reference,
	155	IOExternalMethodArguments * arguments);
	156	struct IOExternalMethodDispatch
	157	{
	158	IOExternalMethodAction function;
	159	uint32_t checkScalarInputCount;
	160	uint32_t checkStructureInputSize;
	161	uint32_t checkScalarOutputCount;
	162	uint32_t checkStructureOutputSize;
	163	};
	164
	165	enum {
ebb1b9f4	166	#define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION 2
2d21ac55 A	167	kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
	168	};
	169
	170
91447636 A	171	/*!
	172	@class IOUserClient
	173	@abstract Provides a basis for communication between client applications and I/O Kit objects.
	174	*/
	175
	176
1c79356b A	177	class IOUserClient : public IOService
	178	{
	179	OSDeclareAbstractStructors(IOUserClient)
6d2010ae A	180	#if IOKITSTATS
	181	friend class IOStatistics;
	182	#endif
1c79356b A	183
	184	protected:
	185	/*! @struct ExpansionData
	186	@discussion This structure will be used to expand the capablilties of this class in the future.
91447636	187	*/
6d2010ae A	188	struct ExpansionData {
	189	#if IOKITSTATS
	190	IOUserClientCounter *counter;
	191	#else
	192	void *iokitstatsReserved;
	193	#endif
	194	};
1c79356b A	195
1c79356b A	196	/*! @var reserved
91447636 A	197	Reserved for future use. (Internal use only)
91447636 A	198	*/
1c79356b A	199	ExpansionData * reserved;
1c79356b A	200
6d2010ae A	201	bool reserve();
6d2010ae A	202
b0d623f7	203	#ifdef XNU_KERNEL_PRIVATE
1c79356b	204	public:
b0d623f7 A	205	#else
	206	private:
	207	#endif
1c79356b	208	OSSet * mappings;
0c530ab8	209	UInt8 sharedInstance;
0c530ab8 A	210	UInt8 __reservedA[3];
0c530ab8 A	211	void * __reserved[7];
1c79356b	212
b0d623f7 A	213	public:
b0d623f7 A	214	virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
2d21ac55	215	IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
2d21ac55	216
b0d623f7 A	217	virtual IOReturn registerNotificationPort(
b0d623f7 A	218	mach_port_t port, UInt32 type, io_user_reference_t refCon);
2d21ac55	219
b0d623f7 A	220	private:
	221	#if __LP64__
	222	OSMetaClassDeclareReservedUnused(IOUserClient, 0);
1c79356b	223	OSMetaClassDeclareReservedUnused(IOUserClient, 1);
b0d623f7 A	224	#else
	225	OSMetaClassDeclareReservedUsed(IOUserClient, 0);
	226	OSMetaClassDeclareReservedUsed(IOUserClient, 1);
	227	#endif
1c79356b A	228	OSMetaClassDeclareReservedUnused(IOUserClient, 2);
	229	OSMetaClassDeclareReservedUnused(IOUserClient, 3);
	230	OSMetaClassDeclareReservedUnused(IOUserClient, 4);
	231	OSMetaClassDeclareReservedUnused(IOUserClient, 5);
	232	OSMetaClassDeclareReservedUnused(IOUserClient, 6);
	233	OSMetaClassDeclareReservedUnused(IOUserClient, 7);
	234	OSMetaClassDeclareReservedUnused(IOUserClient, 8);
	235	OSMetaClassDeclareReservedUnused(IOUserClient, 9);
	236	OSMetaClassDeclareReservedUnused(IOUserClient, 10);
	237	OSMetaClassDeclareReservedUnused(IOUserClient, 11);
	238	OSMetaClassDeclareReservedUnused(IOUserClient, 12);
	239	OSMetaClassDeclareReservedUnused(IOUserClient, 13);
	240	OSMetaClassDeclareReservedUnused(IOUserClient, 14);
	241	OSMetaClassDeclareReservedUnused(IOUserClient, 15);
	242
b0d623f7 A	243	#ifdef XNU_KERNEL_PRIVATE
	244	/* Available within xnu source only */
	245	public:
	246	static void initialize( void );
	247	static void destroyUserReferences( OSObject * obj );
	248	IOMemoryMap * mapClientMemory64( IOOptionBits type,
	249	task_t task,
	250	IOOptionBits mapFlags = kIOMapAnywhere,
	251	mach_vm_address_t atAddress = 0 );
	252	#endif
	253
1c79356b A	254	protected:
	255	static IOReturn sendAsyncResult(OSAsyncReference reference,
	256	IOReturn result, void *args[], UInt32 numArgs);
	257	static void setAsyncReference(OSAsyncReference asyncRef,
	258	mach_port_t wakePort,
	259	void callback, void refcon);
2d21ac55 A	260
	261	static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
	262	IOReturn result, io_user_reference_t args[], UInt32 numArgs);
39236c6e A	263
	264	/*!
	265	@function sendAsyncResult64WithOptions
	266	@abstract Send a notification as with sendAsyncResult, but with finite queueing.
	267	@discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
	268	is not processing them in a timely fashion. This variant will not, for simple
	269	handling of situations where clients may be expected to stop processing messages.
	270	*/
	271	static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
	272	IOReturn result, io_user_reference_t args[], UInt32 numArgs,
	273	IOOptionBits options);
	274
2d21ac55 A	275	static void setAsyncReference64(OSAsyncReference64 asyncRef,
	276	mach_port_t wakePort,
	277	mach_vm_address_t callback, io_user_reference_t refcon);
39236c6e A	278
	279	static void setAsyncReference64(OSAsyncReference64 asyncRef,
	280	mach_port_t wakePort,
	281	mach_vm_address_t callback, io_user_reference_t refcon,
	282	task_t task);
	283
1c79356b A	284	public:
1c79356b A	285
1c79356b A	286	static IOReturn clientHasPrivilege( void * securityToken,
	287	const char * privilegeName );
	288
b0d623f7 A	289	/*!
	290	@function releaseAsyncReference64
	291	@abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
	292	@discussion The OSAsyncReference64 structure passed to async methods holds a reference to the wakeup mach port, which should be released to balance each async method call. Behavior is undefined if these calls are not correctly balanced.
	293	@param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
	294	@result A return code.
	295	*/
	296	static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
	297	/*!
	298	@function releaseNotificationPort
	299	@abstract Release the mach_port_t passed to registerNotificationPort().
	300	@discussion The mach_port_t passed to the registerNotificationPort() methods should be released to balance each call to registerNotificationPort(). Behavior is undefined if these calls are not correctly balanced.
	301	@param reference The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
	302	@result A return code.
	303	*/
	304	static IOReturn releaseNotificationPort(mach_port_t port);
	305
0c530ab8 A	306	virtual bool init();
0c530ab8 A	307	virtual bool init( OSDictionary * dictionary );
1c79356b A	308	// Currently ignores the all args, just passes up to IOService::init()
	309	virtual bool initWithTask(
	310	task_t owningTask, void * securityToken, UInt32 type,
	311	OSDictionary * properties);
	312
	313	virtual bool initWithTask(
	314	task_t owningTask, void * securityToken, UInt32 type);
	315
	316	virtual void free();
	317
	318	virtual IOReturn clientClose( void );
	319	virtual IOReturn clientDied( void );
	320
	321	virtual IOService * getService( void );
	322
	323	virtual IOReturn registerNotificationPort(
	324	mach_port_t port, UInt32 type, UInt32 refCon );
	325
	326	virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
	327	semaphore_t * semaphore );
	328
	329	virtual IOReturn connectClient( IOUserClient * client );
	330
	331	// memory will be released by user client when last map is destroyed
	332	virtual IOReturn clientMemoryForType( UInt32 type,
	333	IOOptionBits * options,
	334	IOMemoryDescriptor ** memory );
	335
b0d623f7 A	336	#if !__LP64__
	337	private:
	338	APPLE_KEXT_COMPATIBILITY_VIRTUAL
	339	IOMemoryMap * mapClientMemory( IOOptionBits type,
1c79356b A	340	task_t task,
1c79356b A	341	IOOptionBits mapFlags = kIOMapAnywhere,
b0d623f7 A	342	IOVirtualAddress atAddress = 0 );
b0d623f7 A	343	#endif
483a1d10	344
39236c6e A	345	static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
39236c6e A	346	IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
b0d623f7	347	public:
2d21ac55	348
483a1d10 A	349	/*!
	350	@function removeMappingForDescriptor
	351	Remove the first mapping created from the memory descriptor returned by clientMemoryForType() from IOUserClient's list of mappings. If such a mapping exists, it is retained and the reference currently held by IOUserClient is returned to the caller.
	352	@param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
	353	@result A reference to the first IOMemoryMap instance found in the list of mappings created by IOUserClient from that passed memory descriptor is returned, or zero if none exist. The caller should release this reference.
	354	*/
	355	IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
	356
1c79356b A	357	/*!
	358	@function exportObjectToClient
	359	Make an arbitrary OSObject available to the client task.
91447636 A	360	@param task The task.
	361	@param obj The object we want to export to the client.
	362	@param clientObj Returned value is the client's port name.
1c79356b A	363	*/
	364	virtual IOReturn exportObjectToClient(task_t task,
	365	OSObject obj, io_object_t clientObj);
	366
	367	// Old methods for accessing method vector backward compatiblility only
	368	virtual IOExternalMethod *
b0d623f7 A	369	getExternalMethodForIndex( UInt32 index )
b0d623f7 A	370	APPLE_KEXT_DEPRECATED;
1c79356b	371	virtual IOExternalAsyncMethod *
b0d623f7 A	372	getExternalAsyncMethodForIndex( UInt32 index )
b0d623f7 A	373	APPLE_KEXT_DEPRECATED;
1c79356b A	374
	375	// Methods for accessing method vector.
	376	virtual IOExternalMethod *
	377	getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
	378	virtual IOExternalAsyncMethod *
	379	getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
	380
	381	// Methods for accessing trap vector - old and new style
	382	virtual IOExternalTrap *
b0d623f7 A	383	getExternalTrapForIndex( UInt32 index )
	384	APPLE_KEXT_DEPRECATED;
	385
1c79356b A	386	virtual IOExternalTrap *
	387	getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
	388	};
	389
	390	#endif /* ! _IOKIT_IOUSERCLIENT_H */
	391