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