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     UInt8   sharedInstance;
 114
 115     UInt8   __reservedA[3];
 116     void  * __reserved[7];
 117
 118 private:
 119     OSMetaClassDeclareReservedUnused(IOUserClient, 0);
 120     OSMetaClassDeclareReservedUnused(IOUserClient, 1);
 121     OSMetaClassDeclareReservedUnused(IOUserClient, 2);
 122     OSMetaClassDeclareReservedUnused(IOUserClient, 3);
 123     OSMetaClassDeclareReservedUnused(IOUserClient, 4);
 124     OSMetaClassDeclareReservedUnused(IOUserClient, 5);
 125     OSMetaClassDeclareReservedUnused(IOUserClient, 6);
 126     OSMetaClassDeclareReservedUnused(IOUserClient, 7);
 127     OSMetaClassDeclareReservedUnused(IOUserClient, 8);
 128     OSMetaClassDeclareReservedUnused(IOUserClient, 9);
 129     OSMetaClassDeclareReservedUnused(IOUserClient, 10);
 130     OSMetaClassDeclareReservedUnused(IOUserClient, 11);
 131     OSMetaClassDeclareReservedUnused(IOUserClient, 12);
 132     OSMetaClassDeclareReservedUnused(IOUserClient, 13);
 133     OSMetaClassDeclareReservedUnused(IOUserClient, 14);
 134     OSMetaClassDeclareReservedUnused(IOUserClient, 15);
 135
 136 protected:
 137     static IOReturn sendAsyncResult(OSAsyncReference reference,
 138                                     IOReturn result, void *args[], UInt32 numArgs);
 139     static void setAsyncReference(OSAsyncReference asyncRef,
 140                                   mach_port_t wakePort,
 141                                   void *callback, void *refcon);
 142 public:
 143
 144     static void initialize( void );
 145
 146     static void destroyUserReferences( OSObject * obj );
 147
 148     static IOReturn clientHasPrivilege( void * securityToken,
 149                                         const char * privilegeName );
 150
 151 #if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT))
 152     virtual bool init();
 153     virtual bool init( OSDictionary * dictionary );
 154 #endif
 155     // Currently ignores the all args, just passes up to IOService::init()
 156     virtual bool initWithTask(
 157                     task_t owningTask, void * securityToken, UInt32 type,
 158                     OSDictionary * properties);
 159
 160     virtual bool initWithTask(
 161                     task_t owningTask, void * securityToken, UInt32 type);
 162
 163     virtual void free();
 164
 165     virtual IOReturn clientClose( void );
 166     virtual IOReturn clientDied( void );
 167
 168     virtual IOService * getService( void );
 169
 170     virtual IOReturn registerNotificationPort(
 171                 mach_port_t port, UInt32 type, UInt32 refCon );
 172
 173     virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
 174                                     semaphore_t * semaphore );
 175
 176     virtual IOReturn connectClient( IOUserClient * client );
 177
 178     // memory will be released by user client when last map is destroyed
 179     virtual IOReturn clientMemoryForType( UInt32 type,
 180                                 IOOptionBits * options,
 181                                 IOMemoryDescriptor ** memory );
 182
 183     virtual IOMemoryMap * mapClientMemory( IOOptionBits type,
 184                                     task_t task,
 185                                     IOOptionBits mapFlags = kIOMapAnywhere,
 186                                     IOVirtualAddress atAddress = 0 );
 187
 188     /*!
 189         @function removeMappingForDescriptor
 190         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.
 191         @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
 192         @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.
 193     */
 194     IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
 195
 196     /*!
 197         @function exportObjectToClient
 198         Make an arbitrary OSObject available to the client task.
 199         @param task The task.
 200         @param obj The object we want to export to the client.
 201         @param clientObj Returned value is the client's port name.
 202     */
 203     virtual IOReturn exportObjectToClient(task_t task,
 204                                 OSObject *obj, io_object_t *clientObj);
 205
 206     // Old methods for accessing method vector backward compatiblility only
 207     virtual IOExternalMethod *
 208         getExternalMethodForIndex( UInt32 index );
 209     virtual IOExternalAsyncMethod *
 210         getExternalAsyncMethodForIndex( UInt32 index );
 211
 212     // Methods for accessing method vector.
 213     virtual IOExternalMethod *
 214         getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 215     virtual IOExternalAsyncMethod *
 216         getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
 217
 218     // Methods for accessing trap vector - old and new style
 219     virtual IOExternalTrap *
 220       getExternalTrapForIndex( UInt32 index );
 221     virtual IOExternalTrap *
 222       getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
 223 };
 224
 225 #endif /* ! _IOKIT_IOUSERCLIENT_H */
 226