iokit/IOKit/IOUserClient.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_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.  The rights granted to you under the
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30
  31 /*
  32  * Changes to this API are expected.
  33  */
  34
  35 #ifndef _IOKIT_IOUSERCLIENT_H
  36 #define _IOKIT_IOUSERCLIENT_H
  37
  38 #include <IOKit/IOTypes.h>
  39 #include <IOKit/IOService.h>
  40 #include <IOKit/OSMessageNotification.h>
  41
  42
  43 enum {
  44     kIOUCTypeMask       = 0x0000000f,
  45     kIOUCScalarIScalarO = 0,
  46     kIOUCScalarIStructO = 2,
  47     kIOUCStructIStructO = 3,
  48     kIOUCScalarIStructI = 4
  49 };
  50
  51 typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,
  52                                         void * p4, void * p5, void * p6 );
  53
  54 typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
  55                                         void * p1, void * p2, void * p3,
  56                                         void * p4, void * p5, void * p6 );
  57
  58 typedef IOReturn (IOService::*IOTrap)(void * p1, void * p2, void * p3,
  59                                       void * p4, void * p5, void * p6 );
  60
  61 struct IOExternalMethod {
  62     IOService *         object;
  63     IOMethod            func;
  64     IOOptionBits        flags;
  65     IOByteCount         count0;
  66     IOByteCount         count1;
  67 };
  68
  69 struct IOExternalAsyncMethod {
  70     IOService *         object;
  71     IOAsyncMethod       func;
  72     IOOptionBits        flags;
  73     IOByteCount         count0;
  74     IOByteCount         count1;
  75 };
  76
  77 struct IOExternalTrap {
  78     IOService *         object;
  79     IOTrap              func;
  80 };
  81
  82 enum {
  83     kIOUserNotifyMaxMessageSize = 64
  84 };
  85
  86 // keys for clientHasPrivilege
  87 #define kIOClientPrivilegeAdministrator "root"
  88 #define kIOClientPrivilegeLocalUser     "local"
  89
  90 /*!
  91     @class IOUserClient
  92     @abstract   Provides a basis for communication between client applications and I/O Kit objects.
  93 */
  94
  95
  96 class IOUserClient : public IOService
  97 {
  98     OSDeclareAbstractStructors(IOUserClient)
  99
 100 protected:
 101 /*! @struct ExpansionData
 102     @discussion This structure will be used to expand the capablilties of this class in the future.
 103 */
 104     struct ExpansionData { };
 105
 106 /*! @var reserved
 107     Reserved for future use.  (Internal use only)
 108 */
 109     ExpansionData * reserved;
 110
 111 public:
 112     OSSet * mappings;
 113     void  * __reserved[8];
 114
 115 private:
 116     OSMetaClassDeclareReservedUnused(IOUserClient, 0);
 117     OSMetaClassDeclareReservedUnused(IOUserClient, 1);
 118     OSMetaClassDeclareReservedUnused(IOUserClient, 2);
 119     OSMetaClassDeclareReservedUnused(IOUserClient, 3);
 120     OSMetaClassDeclareReservedUnused(IOUserClient, 4);
 121     OSMetaClassDeclareReservedUnused(IOUserClient, 5);
 122     OSMetaClassDeclareReservedUnused(IOUserClient, 6);
 123     OSMetaClassDeclareReservedUnused(IOUserClient, 7);
 124     OSMetaClassDeclareReservedUnused(IOUserClient, 8);
 125     OSMetaClassDeclareReservedUnused(IOUserClient, 9);
 126     OSMetaClassDeclareReservedUnused(IOUserClient, 10);
 127     OSMetaClassDeclareReservedUnused(IOUserClient, 11);
 128     OSMetaClassDeclareReservedUnused(IOUserClient, 12);
 129     OSMetaClassDeclareReservedUnused(IOUserClient, 13);
 130     OSMetaClassDeclareReservedUnused(IOUserClient, 14);
 131     OSMetaClassDeclareReservedUnused(IOUserClient, 15);
 132
 133 protected:
 134     static IOReturn sendAsyncResult(OSAsyncReference reference,
 135                                     IOReturn result, void *args[], UInt32 numArgs);
 136     static void setAsyncReference(OSAsyncReference asyncRef,
 137                                   mach_port_t wakePort,
 138                                   void *callback, void *refcon);
 139 public:
 140
 141     static void initialize( void );
 142
 143     static void destroyUserReferences( OSObject * obj );
 144
 145     static IOReturn clientHasPrivilege( void * securityToken,
 146                                         const char * privilegeName );
 147
 148     // Currently ignores the all args, just passes up to IOService::init()
 149     virtual bool initWithTask(
 150                     task_t owningTask, void * securityToken, UInt32 type,
 151                     OSDictionary * properties);
 152
 153     virtual bool initWithTask(
 154                     task_t owningTask, void * securityToken, UInt32 type);
 155
 156     virtual void free();
 157
 158     virtual IOReturn clientClose( void );
 159     virtual IOReturn clientDied( void );
 160
 161     virtual IOService * getService( void );
 162
 163     virtual IOReturn registerNotificationPort(
 164                 mach_port_t port, UInt32 type, UInt32 refCon );
 165
 166     virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
 167                                     semaphore_t * semaphore );
 168
 169     virtual IOReturn connectClient( IOUserClient * client );
 170
 171     // memory will be released by user client when last map is destroyed
 172     virtual IOReturn clientMemoryForType( UInt32 type,
 173                                 IOOptionBits * options,
 174                                 IOMemoryDescriptor ** memory );
 175
 176     virtual IOMemoryMap * mapClientMemory( IOOptionBits type,
 177                                     task_t task,
 178                                     IOOptionBits mapFlags = kIOMapAnywhere,
 179                                     IOVirtualAddress atAddress = 0 );
 180
 181     /*!
 182         @function removeMappingForDescriptor
 183         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.
 184         @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
 185         @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.
 186     */
 187     IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
 188
 189     /*!
 190         @function exportObjectToClient
 191         Make an arbitrary OSObject available to the client task.
 192         @param task The task.
 193         @param obj The object we want to export to the client.
 194         @param clientObj Returned value is the client's port name.
 195     */
 196     virtual IOReturn exportObjectToClient(task_t task,
 197                                 OSObject *obj, io_object_t *clientObj);
 198
 199     // Old methods for accessing method vector backward compatiblility only
 200     virtual IOExternalMethod *
 201         getExternalMethodForIndex( UInt32 index );
 202     virtual IOExternalAsyncMethod *
 203         getExternalAsyncMethodForIndex( UInt32 index );
 204
 205     // Methods for accessing method vector.
 206     virtual IOExternalMethod *
 207         getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 208     virtual IOExternalAsyncMethod *
 209         getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 210
 211     // Methods for accessing trap vector - old and new style
 212     virtual IOExternalTrap *
 213       getExternalTrapForIndex( UInt32 index );
 214     virtual IOExternalTrap *
 215       getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
 216 };
 217
 218 #endif /* ! _IOKIT_IOUSERCLIENT_H */
 219