iokit/IOKit/IOUserClient.h

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