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