1/* 2 * Copyright (c) 1998-2008 Apple Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * The contents of this file constitute Original Code as defined in and 7 * are subject to the Apple Public Source License Version 1.1 (the 8 * "License"). You may not use this file except in compliance with the 9 * License. Please obtain a copy of the License at 10 * http://www.apple.com/publicsource and read it before using this file. 11 * 12 * This Original Code and all software distributed under the License are 13 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 14 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 15 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 16 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the 17 * License for the specific language governing rights and limitations 18 * under the License. 19 * 20 * @APPLE_LICENSE_HEADER_END@ 21 */ 22 23#ifndef _IONETWORKUSERCLIENT_H 24#define _IONETWORKUSERCLIENT_H 25 26// IONetworkUserClient type ID. 27// 28#define kIONetworkUserClientTypeID 0xff000001 29#define kIONUCType 0xff000001 // FIXME 30 31// IONetworkUserClient call structure definitions. 32// 33enum { 34 kIONUCResetNetworkDataIndex = 0, 35 kIONUCWriteNetworkDataIndex = 1, 36 kIONUCReadNetworkDataIndex = 2, 37 kIONUCGetNetworkDataCapacityIndex = 3, 38 kIONUCGetNetworkDataHandleIndex = 4, 39 kIONUCLastIndex 40}; 41 42#ifdef KERNEL 43 44#include <IOKit/IOUserClient.h> 45 46class IONetworkInterface; 47 48/*! @class IONetworkUserClient 49 @abstract An IOUserClient created by an IONetworkInterface to 50 manage user space requests. */ 51 52class IONetworkUserClient : public IOUserClient 53{ 54 OSDeclareDefaultStructors( IONetworkUserClient ) 55 56protected: 57 IONetworkInterface * _owner; 58 task_t _task; 59 OSArray * _handleArray; 60 IOLock * _handleLock; 61 62/*! @function 63 @abstract Free the IONetworkUserClient object. */ 64 65 virtual void free(void); 66 67public: 68 69/*! @function withTask 70 @abstract Factory method that performs allocation and initialization 71 of an IONetworkUserClient object. 72 @param owningTask See IOUserClient. 73 @result An IONetworkUserClient on success, 0 otherwise. */ 74 75 static IONetworkUserClient * withTask(task_t owningTask); 76 77/*! @function start 78 @abstract Start the IONetworkUserClient. 79 @discussion Open the provider, must be an IONetworkInterface object, 80 and initialize the IOExternalMethod array. 81 @result true on success, false otherwise. */ 82 83 virtual bool start(IOService * provider); 84 85/*! @function clientClose 86 @abstract Handle a client close. 87 @discussion Close and detach from our owner (provider). 88 @result kIOReturnSuccess. */ 89 90 virtual IOReturn clientClose(void); 91 92/*! @function clientDied 93 @abstract Handle client death. 94 @discussion Close and detach from our owner (provider). 95 @result kIOReturnSuccess. */ 96 97 virtual IOReturn clientDied(void); 98 99 virtual IOReturn externalMethod( 100 uint32_t selector, 101 IOExternalMethodArguments * arguments, 102 IOExternalMethodDispatch * dispatch = 0, 103 OSObject * target = 0, 104 void * reference = 0 ); 105 106protected: 107 108/*! @function resetNetworkData 109 @abstract Fill the data buffer in an IONetworkData object with zeroes. 110 @param dataHandle The handle associated with an IONetworkData object. 111 @result kIOReturnSuccess on success, kIOReturnBadArgument if an 112 argument is invalid, or an error from IONetworkData::reset(). */ 113 114 IOReturn resetNetworkData(uint32_t dataHandle); 115 116/*! @function writeNetworkData 117 @abstract Write to the data buffer in an IONetworkData object with 118 data from a source buffer provided by the caller. 119 @param dataHandle The handle associated with an IONetworkData object. 120 @param srcBuffer The source buffer provided by the caller. 121 @param srcBufferSize The size of the source buffer. 122 @result kIOReturnSuccess on success, kIOReturnBadArgument if an 123 argument is invalid, or an error from IONetworkData::write(). */ 124 125 IOReturn writeNetworkData(uint32_t dataHandle, 126 void * srcBuffer, 127 uint32_t srcBufferSize); 128 129/*! @function readNetworkData 130 @abstract Read the data buffer in an IONetworkData object and copy 131 this data to a destination buffer provided by the caller. 132 @param dataHandle The handle associated with an IONetworkData object. 133 @param dstBuffer The destination buffer provided by the caller. 134 @param dstBufferSize Pointer to an integer that the caller must 135 initialize to hold the size of the destination buffer. This method 136 will overwrite it with the actual number of bytes written. 137 @result kIOReturnSuccess on success, kIOReturnBadArgument if an 138 argument is invalid, or an error from IONetworkData::read(). */ 139 140 IOReturn readNetworkData(uint32_t dataHandle, 141 void * dstBuffer, 142 uint32_t * dstBufferSize); 143 144/*! @function getNetworkDataCapacity 145 @abstract Get the capacity of an IONetworkData object, described 146 by the size of its data buffer. 147 @param dataHandle The handle of an IONetworkData object. 148 @param capacity A pointer to the capacity value returned by this 149 method. 150 @result kIOReturnSuccess on success, kIOReturnBadArgument if an 151 argument is invalid. */ 152 153 IOReturn getNetworkDataCapacity(uint32_t dataHandle, 154 uint64_t * capacity); 155 156/*! @function getNetworkDataHandle 157 @abstract Return an opaque handle to a provider's IONetworkData object. 158 @discussion Called to obtain an unique handle that maps to an IONetworkData 159 object. This handle can be later passed to other methods defined in this 160 class to refer to the same object. 161 @param name A C string with the name of the IONetworkData object. 162 @param dataHandle If an IONetworkData object with the given name is found, 163 then a handle is written to this address. 164 @param nameSize The size of the name string, including the final 165 terminating null character. 166 @param handleSizeP The size of the buffer allocated by the caller 167 to store the handle. This should be 4 bytes. 168 @result kIOReturnSuccess on success, kIOReturnBadArgument if an 169 argument is invalid, or kIOReturnNoMemory if unable to allocate memory. */ 170 171 IOReturn getNetworkDataHandle(const char * name, 172 uint32_t * dataHandle, 173 uint32_t nameSize, 174 uint32_t * handleSizeP); 175 176/*! @function setProperties 177 @abstract Handle a request to set properties from non-kernel clients. 178 This call is propagated to our provider. 179 @param properties An OSObject subclass that describes one or more 180 properties. 181 @result The return value from the invocation of this method in our 182 provider is returned. */ 183 184 virtual IOReturn setProperties(OSObject * properties); 185 186/*! @function getService 187 @abstract Get the IOService which is the provider of this user client. 188 @result Returns the IONetworkInterface that created the user client. */ 189 190 virtual IOService * getService(); 191}; 192 193#endif /* KERNEL */ 194 195#endif /* !_IONETWORKUSERCLIENT_H */ 196