iokit/IOKit/network/IONetworkUserClient.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, 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  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
  24  *
  25  * HISTORY
  26  *
  27  */
  28
  29 #ifndef _IONETWORKUSERCLIENT_H
  30 #define _IONETWORKUSERCLIENT_H
  31
  32 // IONetworkUserClient type ID.
  33 //
  34 #define kIONetworkUserClientTypeID   0xff000001
  35 #define kIONUCType                   0xff000001  // FIXME
  36
  37 // IONetworkUserClient call structure definitions.
  38 //
  39 enum {
  40         kIONUCResetNetworkDataIndex          = 0,
  41 #define kIONUCResetNetworkDataInputs           1
  42 #define kIONUCResetNetworkDataOutputs          0
  43 #define kIONUCResetNetworkDataFlags            kIOUCScalarIScalarO
  44
  45         kIONUCWriteNetworkDataIndex          = 1,
  46 #define kIONUCWriteNetworkDataInput0           0xffffffff
  47 #define kIONUCWriteNetworkDataInput1           0xffffffff
  48 #define kIONUCWriteNetworkDataFlags            kIOUCScalarIStructI
  49
  50         kIONUCReadNetworkDataIndex           = 2,
  51 #define kIONUCReadNetworkDataInputs            1
  52 #define kIONUCReadNetworkDataOutputs           0xffffffff
  53 #define kIONUCReadNetworkDataFlags             kIOUCScalarIStructO
  54
  55         kIONUCGetNetworkDataCapacityIndex    = 3,
  56 #define kIONUCGetNetworkDataCapacityInputs     1
  57 #define kIONUCGetNetworkDataCapacityOutputs    1
  58 #define kIONUCGetNetworkDataCapacityFlags      kIOUCScalarIScalarO
  59
  60         kIONUCGetNetworkDataHandleIndex      = 4,
  61 #define kIONUCGetNetworkDataHandleInputs       0xffffffff
  62 #define kIONUCGetNetworkDataHandleOutputs      0xffffffff
  63 #define kIONUCGetNetworkDataHandleFlags        kIOUCStructIStructO
  64
  65         kIONUCLastIndex
  66 };
  67
  68 #ifdef KERNEL
  69
  70 #include <IOKit/IOUserClient.h>
  71
  72 class IONetworkInterface;
  73
  74 /*! @class IONetworkUserClient
  75     @abstract An IOUserClient created by an IONetworkInterface to
  76     manage user space requests. */
  77
  78 class IONetworkUserClient : public IOUserClient
  79 {
  80     OSDeclareDefaultStructors( IONetworkUserClient )
  81
  82 protected:
  83     IONetworkInterface *   _owner;
  84     task_t                 _task;
  85     IOExternalMethod       _methods[kIONUCLastIndex];
  86
  87 /*! @function
  88     @abstract Free the IONetworkUserClient object. */
  89
  90     virtual void free();
  91
  92 public:
  93
  94 /*! @function withTask
  95     @abstract Factory method that performs allocation and initialization
  96     of an IONetworkUserClient object.
  97     @param owningTask See IOUserClient.
  98     @result An IONetworkUserClient on success, 0 otherwise. */
  99
 100     static IONetworkUserClient * withTask(task_t owningTask);
 101
 102 /*! @function start
 103     @abstract Start the IONetworkUserClient.
 104     @discussion Open the provider, must be an IONetworkInterface object,
 105     and initialize the IOExternalMethod array.
 106     @result true on success, false otherwise. */
 107
 108     virtual bool start(IOService * provider);
 109
 110 /*! @function clientClose
 111     @abstract Handle a client close.
 112     @discussion Close and detach from our owner (provider).
 113     @result kIOReturnSuccess. */
 114
 115     virtual IOReturn clientClose();
 116
 117 /*! @function clientDied
 118     @abstract Handle client death.
 119     @discussion Close and detach from our owner (provider).
 120     @result kIOReturnSuccess. */
 121
 122     virtual IOReturn clientDied();
 123
 124 /*! @function getExternalMethodForIndex
 125     @abstract Look up a method entry from the method array.
 126     @discussion Called by IOUserClient to fetch the method entry,
 127     described by an IOExternalMethod structure, that correspond to
 128     the index provided.
 129     @param index The method index.
 130     @result A pointer to an IOExternalMethod structure containing the
 131     method definition for the given index. */
 132
 133     virtual IOExternalMethod * getExternalMethodForIndex(UInt32 index);
 134
 135 protected:
 136
 137 /*! @function resetNetworkData
 138     @abstract Fill the data buffer in an IONetworkData object with zeroes.
 139     @param key An OSSymbol key associated with an IONetworkData object.
 140     @result kIOReturnSuccess on success, kIOReturnBadArgument if an
 141     argument is invalid, or an error from IONetworkData::reset(). */
 142
 143     virtual IOReturn resetNetworkData(OSSymbol * key);
 144
 145 /*! @function writeNetworkData
 146     @abstract Write to the data buffer in an IONetworkData object with
 147     data from a source buffer provided by the caller.
 148     @param key The OSSymbol key associated with an IONetworkData object.
 149     @param srcBuffer The source buffer provided by the caller.
 150     @param srcBufferSize The size of the source buffer.
 151     @result kIOReturnSuccess on success, kIOReturnBadArgument if an
 152     argument is invalid, or an error from IONetworkData::write(). */
 153
 154     virtual IOReturn writeNetworkData(OSSymbol *   key,
 155                                       void *       srcBuffer,
 156                                       IOByteCount  srcBufferSize);
 157
 158 /*! @function readNetworkData
 159     @abstract Read the data buffer in an IONetworkData object and copy
 160     this data to a destination buffer provided by the caller.
 161     @param key The OSSymbol key associated with an IONetworkData object.
 162     @param dstBuffer The destination buffer provided by the caller.
 163     @param dstBufferSize Pointer to an integer that the caller must
 164     initialize to hold the size of the destination buffer. This method
 165     will overwrite it with the actual number of bytes written.
 166     @result kIOReturnSuccess on success, kIOReturnBadArgument if an
 167     argument is invalid, or an error from IONetworkData::read(). */
 168
 169     virtual IOReturn readNetworkData(OSSymbol *    key,
 170                                      void *        dstBuffer,
 171                                      IOByteCount * dstBufferSize);
 172
 173 /*! @function getNetworkDataCapacity
 174     @abstract Get the capacity of an IONetworkData object, described
 175     by the size of its data buffer.
 176     @param key The OSSymbol key of an IONetworkData object.
 177     @param capacity A pointer to the capacity value returned by this
 178     method.
 179     @result kIOReturnSuccess on success, kIOReturnBadArgument if an
 180     argument is invalid. */
 181
 182     virtual IOReturn getNetworkDataCapacity(OSSymbol * key,
 183                                             UInt32 *   capacity);
 184
 185 /*! @function getNetworkDataHandle
 186     @abstract Return an opaque handle to a provider's IONetworkData object.
 187     @discussion Called to obtain an unique handle that maps to an IONetworkData
 188     object. This handle can be later passed to other methods defined in this
 189     class to refer to the same object.
 190     @param name A C string with the name of the IONetworkData object.
 191     @param handle If an IONetworkData object with the given name is found,
 192     then its associated OSSymbol object is written to this address.
 193     @param nameSize The size of the name string, including the final
 194     terminating null character.
 195     @param handleSizeP The size of the buffer allocated by the caller
 196     to store the handle. This should be 4 bytes.
 197     @result kIOReturnSuccess on success, kIOReturnBadArgument if an
 198     argument is invalid, or kIOReturnNoMemory if unable to allocate memory. */
 199
 200     virtual IOReturn getNetworkDataHandle(char *         name,
 201                                           OSSymbol **    handle,
 202                                           IOByteCount    nameSize,
 203                                           IOByteCount *  handleSizeP);
 204 };
 205
 206 #endif /* KERNEL */
 207
 208 #endif /* !_IONETWORKUSERCLIENT_H */