[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

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
};

// 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);
    static void setAsyncReference64(OSAsyncReference64 asyncRef,
					mach_port_t wakePort,
					mach_vm_address_t callback, io_user_reference_t refcon);
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

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 A	43
	44	enum {
	45	kIOUCTypeMask = 0x0000000f,
	46	kIOUCScalarIScalarO = 0,
	47	kIOUCScalarIStructO = 2,
	48	kIOUCStructIStructO = 3,
d1ecb069 A	49	kIOUCScalarIStructI = 4,
	50
	51	kIOUCForegroundOnly = 0x00000010,
1c79356b A	52	};
1c79356b A	53
2d21ac55 A	54	/*! @enum
	55	@abstract Constant to denote a variable length structure argument to IOUserClient.
	56	@constant kIOUCVariableStructureSize Use in the structures IOExternalMethod, IOExternalAsyncMethod, IOExternalMethodDispatch to specify the size of the structure is variable.
	57	*/
	58	enum {
	59	kIOUCVariableStructureSize = 0xffffffff
	60	};
	61
	62
1c79356b A	63	typedef IOReturn (IOService::IOMethod)(void p1, void * p2, void * p3,
	64	void * p4, void * p5, void * p6 );
	65
	66	typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
	67	void * p1, void * p2, void * p3,
	68	void * p4, void * p5, void * p6 );
	69
	70	typedef IOReturn (IOService::IOTrap)(void p1, void * p2, void * p3,
	71	void * p4, void * p5, void * p6 );
	72
	73	struct IOExternalMethod {
	74	IOService * object;
	75	IOMethod func;
	76	IOOptionBits flags;
	77	IOByteCount count0;
	78	IOByteCount count1;
	79	};
	80
	81	struct IOExternalAsyncMethod {
	82	IOService * object;
	83	IOAsyncMethod func;
	84	IOOptionBits flags;
	85	IOByteCount count0;
	86	IOByteCount count1;
	87	};
	88
	89	struct IOExternalTrap {
	90	IOService * object;
	91	IOTrap func;
	92	};
	93
	94	enum {
	95	kIOUserNotifyMaxMessageSize = 64
	96	};
	97
	98	// keys for clientHasPrivilege
	99	#define kIOClientPrivilegeAdministrator "root"
	100	#define kIOClientPrivilegeLocalUser "local"
d1ecb069	101	#define kIOClientPrivilegeForeground "foreground"
1c79356b	102
2d21ac55 A	103	/*! @enum
	104	@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.
	105	@constant kIOExternalMethodScalarInputCountMax The maximum number of scalars able to passed on input.
	106	@constant kIOExternalMethodScalarOutputCountMax The maximum number of scalars able to passed on output.
	107	*/
	108	enum {
	109	kIOExternalMethodScalarInputCountMax = 16,
	110	kIOExternalMethodScalarOutputCountMax = 16,
	111	};
	112
	113
	114	struct IOExternalMethodArguments
	115	{
	116	uint32_t version;
	117
	118	uint32_t selector;
	119
	120	mach_port_t asyncWakePort;
	121	io_user_reference_t * asyncReference;
	122	uint32_t asyncReferenceCount;
	123
	124	const uint64_t * scalarInput;
	125	uint32_t scalarInputCount;
	126
	127	const void * structureInput;
	128	uint32_t structureInputSize;
	129
	130	IOMemoryDescriptor * structureInputDescriptor;
	131
	132	uint64_t * scalarOutput;
	133	uint32_t scalarOutputCount;
	134
	135	void * structureOutput;
	136	uint32_t structureOutputSize;
	137
	138	IOMemoryDescriptor * structureOutputDescriptor;
	139	uint32_t structureOutputDescriptorSize;
	140
ebb1b9f4 A	141	uint32_t __reservedA;
	142
	143	OSObject ** structureVariableOutputData;
	144
	145	uint32_t __reserved[30];
2d21ac55 A	146	};
	147
	148	typedef IOReturn (IOExternalMethodAction)(OSObject target, void * reference,
	149	IOExternalMethodArguments * arguments);
	150	struct IOExternalMethodDispatch
	151	{
	152	IOExternalMethodAction function;
	153	uint32_t checkScalarInputCount;
	154	uint32_t checkStructureInputSize;
	155	uint32_t checkScalarOutputCount;
	156	uint32_t checkStructureOutputSize;
	157	};
	158
	159	enum {
ebb1b9f4	160	#define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION 2
2d21ac55 A	161	kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
	162	};
	163
	164
91447636 A	165	/*!
	166	@class IOUserClient
	167	@abstract Provides a basis for communication between client applications and I/O Kit objects.
	168	*/
	169
	170
1c79356b A	171	class IOUserClient : public IOService
	172	{
	173	OSDeclareAbstractStructors(IOUserClient)
6d2010ae A	174	#if IOKITSTATS
	175	friend class IOStatistics;
	176	#endif
1c79356b A	177
	178	protected:
	179	/*! @struct ExpansionData
	180	@discussion This structure will be used to expand the capablilties of this class in the future.
91447636	181	*/
6d2010ae A	182	struct ExpansionData {
	183	#if IOKITSTATS
	184	IOUserClientCounter *counter;
	185	#else
	186	void *iokitstatsReserved;
	187	#endif
	188	};
1c79356b A	189
1c79356b A	190	/*! @var reserved
91447636 A	191	Reserved for future use. (Internal use only)
91447636 A	192	*/
1c79356b A	193	ExpansionData * reserved;
1c79356b A	194
6d2010ae A	195	bool reserve();
6d2010ae A	196
b0d623f7	197	#ifdef XNU_KERNEL_PRIVATE
1c79356b	198	public:
b0d623f7 A	199	#else
	200	private:
	201	#endif
1c79356b	202	OSSet * mappings;
0c530ab8	203	UInt8 sharedInstance;
0c530ab8 A	204	UInt8 __reservedA[3];
0c530ab8 A	205	void * __reserved[7];
1c79356b	206
b0d623f7 A	207	public:
b0d623f7 A	208	virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
2d21ac55	209	IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
2d21ac55	210
b0d623f7 A	211	virtual IOReturn registerNotificationPort(
b0d623f7 A	212	mach_port_t port, UInt32 type, io_user_reference_t refCon);
2d21ac55	213
b0d623f7 A	214	private:
	215	#if __LP64__
	216	OSMetaClassDeclareReservedUnused(IOUserClient, 0);
1c79356b	217	OSMetaClassDeclareReservedUnused(IOUserClient, 1);
b0d623f7 A	218	#else
	219	OSMetaClassDeclareReservedUsed(IOUserClient, 0);
	220	OSMetaClassDeclareReservedUsed(IOUserClient, 1);
	221	#endif
1c79356b A	222	OSMetaClassDeclareReservedUnused(IOUserClient, 2);
	223	OSMetaClassDeclareReservedUnused(IOUserClient, 3);
	224	OSMetaClassDeclareReservedUnused(IOUserClient, 4);
	225	OSMetaClassDeclareReservedUnused(IOUserClient, 5);
	226	OSMetaClassDeclareReservedUnused(IOUserClient, 6);
	227	OSMetaClassDeclareReservedUnused(IOUserClient, 7);
	228	OSMetaClassDeclareReservedUnused(IOUserClient, 8);
	229	OSMetaClassDeclareReservedUnused(IOUserClient, 9);
	230	OSMetaClassDeclareReservedUnused(IOUserClient, 10);
	231	OSMetaClassDeclareReservedUnused(IOUserClient, 11);
	232	OSMetaClassDeclareReservedUnused(IOUserClient, 12);
	233	OSMetaClassDeclareReservedUnused(IOUserClient, 13);
	234	OSMetaClassDeclareReservedUnused(IOUserClient, 14);
	235	OSMetaClassDeclareReservedUnused(IOUserClient, 15);
	236
b0d623f7 A	237	#ifdef XNU_KERNEL_PRIVATE
	238	/* Available within xnu source only */
	239	public:
	240	static void initialize( void );
	241	static void destroyUserReferences( OSObject * obj );
	242	IOMemoryMap * mapClientMemory64( IOOptionBits type,
	243	task_t task,
	244	IOOptionBits mapFlags = kIOMapAnywhere,
	245	mach_vm_address_t atAddress = 0 );
	246	#endif
	247
1c79356b A	248	protected:
	249	static IOReturn sendAsyncResult(OSAsyncReference reference,
	250	IOReturn result, void *args[], UInt32 numArgs);
	251	static void setAsyncReference(OSAsyncReference asyncRef,
	252	mach_port_t wakePort,
	253	void callback, void refcon);
2d21ac55 A	254
	255	static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
	256	IOReturn result, io_user_reference_t args[], UInt32 numArgs);
	257	static void setAsyncReference64(OSAsyncReference64 asyncRef,
	258	mach_port_t wakePort,
	259	mach_vm_address_t callback, io_user_reference_t refcon);
1c79356b A	260	public:
1c79356b A	261
1c79356b A	262	static IOReturn clientHasPrivilege( void * securityToken,
	263	const char * privilegeName );
	264
b0d623f7 A	265	/*!
	266	@function releaseAsyncReference64
	267	@abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
	268	@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.
	269	@param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
	270	@result A return code.
	271	*/
	272	static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
	273	/*!
	274	@function releaseNotificationPort
	275	@abstract Release the mach_port_t passed to registerNotificationPort().
	276	@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.
	277	@param reference The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
	278	@result A return code.
	279	*/
	280	static IOReturn releaseNotificationPort(mach_port_t port);
	281
0c530ab8 A	282	virtual bool init();
0c530ab8 A	283	virtual bool init( OSDictionary * dictionary );
1c79356b A	284	// Currently ignores the all args, just passes up to IOService::init()
	285	virtual bool initWithTask(
	286	task_t owningTask, void * securityToken, UInt32 type,
	287	OSDictionary * properties);
	288
	289	virtual bool initWithTask(
	290	task_t owningTask, void * securityToken, UInt32 type);
	291
	292	virtual void free();
	293
	294	virtual IOReturn clientClose( void );
	295	virtual IOReturn clientDied( void );
	296
	297	virtual IOService * getService( void );
	298
	299	virtual IOReturn registerNotificationPort(
	300	mach_port_t port, UInt32 type, UInt32 refCon );
	301
	302	virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
	303	semaphore_t * semaphore );
	304
	305	virtual IOReturn connectClient( IOUserClient * client );
	306
	307	// memory will be released by user client when last map is destroyed
	308	virtual IOReturn clientMemoryForType( UInt32 type,
	309	IOOptionBits * options,
	310	IOMemoryDescriptor ** memory );
	311
b0d623f7 A	312	#if !__LP64__
	313	private:
	314	APPLE_KEXT_COMPATIBILITY_VIRTUAL
	315	IOMemoryMap * mapClientMemory( IOOptionBits type,
1c79356b A	316	task_t task,
1c79356b A	317	IOOptionBits mapFlags = kIOMapAnywhere,
b0d623f7 A	318	IOVirtualAddress atAddress = 0 );
b0d623f7 A	319	#endif
483a1d10	320
b0d623f7	321	public:
2d21ac55	322
483a1d10 A	323	/*!
	324	@function removeMappingForDescriptor
	325	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.
	326	@param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
	327	@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.
	328	*/
	329	IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
	330
1c79356b A	331	/*!
	332	@function exportObjectToClient
	333	Make an arbitrary OSObject available to the client task.
91447636 A	334	@param task The task.
	335	@param obj The object we want to export to the client.
	336	@param clientObj Returned value is the client's port name.
1c79356b A	337	*/
	338	virtual IOReturn exportObjectToClient(task_t task,
	339	OSObject obj, io_object_t clientObj);
	340
	341	// Old methods for accessing method vector backward compatiblility only
	342	virtual IOExternalMethod *
b0d623f7 A	343	getExternalMethodForIndex( UInt32 index )
b0d623f7 A	344	APPLE_KEXT_DEPRECATED;
1c79356b	345	virtual IOExternalAsyncMethod *
b0d623f7 A	346	getExternalAsyncMethodForIndex( UInt32 index )
b0d623f7 A	347	APPLE_KEXT_DEPRECATED;
1c79356b A	348
	349	// Methods for accessing method vector.
	350	virtual IOExternalMethod *
	351	getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
	352	virtual IOExternalAsyncMethod *
	353	getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
	354
	355	// Methods for accessing trap vector - old and new style
	356	virtual IOExternalTrap *
b0d623f7 A	357	getExternalTrapForIndex( UInt32 index )
	358	APPLE_KEXT_DEPRECATED;
	359
1c79356b A	360	virtual IOExternalTrap *
	361	getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
	362	};
	363
	364	#endif /* ! _IOKIT_IOUSERCLIENT_H */
	365