![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IONetworkInterface.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / network|
Return to IONetworkInterface.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / network |
1.1 ! root 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: * IONetworkInterface.h ! 26: * ! 27: * HISTORY ! 28: * 8-Jan-1999 Joe Liu (jliu) created. ! 29: */ ! 30: ! 31: #ifndef _IONETWORKINTERFACE_H ! 32: #define _IONETWORKINTERFACE_H ! 33: ! 34: #include <IOKit/IOService.h> ! 35: #include <libkern/c++/OSString.h> ! 36: #include <libkern/c++/OSData.h> ! 37: #include <libkern/c++/OSArray.h> ! 38: #include <libkern/c++/OSSet.h> ! 39: #include <IOKit/IOLocks.h> ! 40: #include <IOKit/network/IONetworkData.h> ! 41: #include <IOKit/network/IONetworkStats.h> ! 42: #include <IOKit/network/IONetworkMedium.h> ! 43: ! 44: struct mbuf; // forward declarations. ! 45: struct ifnet; ! 46: class IONetworkController; ! 47: class IONetworkStack; ! 48: ! 49: // Property table keys. ! 50: // ! 51: #define kIONetworkData "IONetworkData" // OSDictionary ! 52: #define kIOInterfaceType "IOInterfaceType" // OSNumber:8 ! 53: #define kIOMaxTransferUnit "IOMaxTransferUnit" // OSNumber:32 ! 54: #define kIOMediaAddressLength "IOMediaAddressLength" // OSNumber:8 ! 55: #define kIOMediaHeaderLength "IOMediaHeaderLength" // OSNumber:8 ! 56: #define kIOInterfaceFlags "IOInterfaceFlags" // OSNumber:16 ! 57: #define kIOInterfaceExtraFlags "IOInterfaceExtraFlags" // OSNumber:32 ! 58: ! 59: /*! @typedef IOOutputAction ! 60: @discussion Prototype for an output packet handler that will receive ! 61: all outbound packets sent to the interface from the network layer. ! 62: This handler is registered by calling registerOutputHandler(). ! 63: @param m A packet mbuf. */ ! 64: ! 65: typedef UInt32 (OSObject::*IOOutputAction)(struct mbuf * m); ! 66: ! 67: /*! @typedef BPF_FUNC ! 68: @discussion Prototype for the BPF tap handler. This will disappear ! 69: when the appropriate DLIL header file is included. */ ! 70: ! 71: typedef int (*BPF_FUNC)(struct ifnet *, struct mbuf *); ! 72: ! 73: /*! @enum IOFilterTapMode ! 74: @constant kIOFilterTapModeInternal The filter tap will automatically ! 75: tap into the packet stream inside the interface object for a given ! 76: direction (that matches the filter's direction). This is the default mode. ! 77: @constant kIOFilterTapModeExternal The filter tap will only receive ! 78: packets when the feedInputFilterTap() or feedOutputFilterTap() methods ! 79: are called (probably by a controller driver). This allows the filter ! 80: to tap at a place that is logically closer to the network media. */ ! 81: ! 82: typedef enum { ! 83: kIOFilterTapModeInternal, ! 84: kIOFilterTapModeExternal, ! 85: } IOFilterTapMode; ! 86: ! 87: // Network events. ! 88: // ! 89: enum { ! 90: /* A new network medium was selected by the controller */ ! 91: kIONetworkEventMediumChange = 0xff000001, ! 92: ! 93: /* A link change was detected */ ! 94: kIONetworkEventLinkChange = 0xff000002, ! 95: }; ! 96: ! 97: /*! @class IONetworkInterface ! 98: @abstract An IONetworkInterface object manages the connection ! 99: between an IONetworkController and the network layer (DLIL). ! 100: All interaction between the controller and DLIL must flow ! 101: through an interface object. Any data structures required by ! 102: the DLIL for a given "network interface" type is allocated and ! 103: mantained by the interface object. Just as IONetworkController ! 104: may be subclassed to satisfy the needs of a particular network ! 105: family (i.e. Ethernet), a corresponding IONetworkInterface ! 106: subclass should be created. ! 107: ! 108: Although most drivers will allocate a single interface object. ! 109: It is possible for multiple interfaces to be attached to a single ! 110: controller. The controller driver is responsible for arbitrating ! 111: requests among its interface clients. ! 112: ! 113: IONetworkInterface also maintains a dictionary of IONetworkData ! 114: objects containing statistics structures. Controller drivers can ! 115: ask for a particular data object by name and update the ! 116: statistics counters within directly. This dictionary is added to ! 117: the interface's property table and is visible outside of the kernel. ! 118: ! 119: The inbound and outbound packet flow through the interface may be ! 120: tapped by an external entity. By default, the interface will ! 121: manage the filter taps automatically. But a controller driver may ! 122: disable the default behavior to have a better control over when ! 123: and which packet are fed to the filter taps. ! 124: */ ! 125: ! 126: class IONetworkInterface : public IOService ! 127: { ! 128: OSDeclareAbstractStructors(IONetworkInterface) ! 129: ! 130: friend class IONetworkStack; ! 131: friend class IONetworkUserClient; ! 132: ! 133: private: ! 134: IONetworkController * _provider; ! 135: struct ifnet * _ifp; ! 136: IORecursiveLock * _ifLock; ! 137: OSSet * _clientSet; ! 138: bool _registered; ! 139: IOFilterTapMode _inputFilterTapMode; ! 140: IOFilterTapMode _outputFilterTapMode; ! 141: BPF_FUNC _inputFilterFunc; ! 142: BPF_FUNC _outputFilterFunc; ! 143: OSObject * _target; ! 144: IOOutputAction _outAction; ! 145: IOService * _client; ! 146: OSDictionary * _dataDict; ! 147: IOMediumType _bsdMediaType; ! 148: struct mbuf * inputQHead; ! 149: struct mbuf * inputQTail; ! 150: ! 151: bool _copyNetworkDataDictToPropertyTable(); ! 152: void _handleMediumAndLinkChangeEvent(); ! 153: bool _setFilterTapMode(IOFilterTapMode * modePtr, IOFilterTapMode mode); ! 154: bool _setInterfaceProperty(UInt32 value, ! 155: UInt32 mask, ! 156: UInt32 bytes, ! 157: void * addr, ! 158: char * name, ! 159: bool restrict); ! 160: ! 161: SInt syncSIOCSIFMEDIA(IONetworkController * ctlr, struct ifreq * ifr); ! 162: SInt syncSIOCGIFMEDIA(IONetworkController * ctlr, struct ifreq * ifr); ! 163: SInt syncSIOCSIFMTU(IONetworkController * ctlr, struct ifreq * ifr); ! 164: SInt syncPerformCommand(IONetworkController * ctlr, ! 165: UInt32 cmd, ! 166: void * arg0, ! 167: void * arg1); ! 168: ! 169: static int ioctl_shim(struct ifnet * ifp, u_long cmd, caddr_t data); ! 170: static int set_bpf_tap_shim(struct ifnet * ifp, int mode, BPF_FUNC func); ! 171: static int free_shim(struct ifnet * ifp); ! 172: static int output_shim(struct ifnet * ifp, struct mbuf *m); ! 173: static void null_shim(struct ifnet * ifp); ! 174: ! 175: public: ! 176: ! 177: /*! @function init ! 178: @abstract Initialize an IONetworkInterface instance. ! 179: @discussion Initialize instance variables, call getIfnet() to ! 180: get the ifnet structure allocated by a concrete subclass, ! 181: then call initIfnet() to initialize the ifnet structure. ! 182: @param properties A property dictionary. ! 183: @result true if initialized successfully, false otherwise. */ ! 184: ! 185: virtual bool init(OSDictionary * properties = 0); ! 186: ! 187: /*! @function isRegistered ! 188: @abstract Returns true if the interface has been registered with ! 189: the network layer. ! 190: @result true if registered, false if the network layer has no ! 191: knowledge or reference to this network interface. */ ! 192: ! 193: virtual bool isRegistered() const; ! 194: ! 195: /*! @function inputPacket ! 196: @abstract Handle a packet received by the controller. ! 197: @discussion Called by a controller to pass a received packet ! 198: to the network layer. Packets received by this method can ! 199: also be placed on a queue local to the interface, that the controller ! 200: can use to delay the packet handoff to the network layer, until all ! 201: received packets have been transferred to the queue. A subsequent call ! 202: of flushInputQueue(), or inputPacket() with the queue argument set to ! 203: false, will cause all queued packets (may be a single packet) to be ! 204: delivered to the network layer, by making a single dlil_input() call. ! 205: Additional methods that manipulate the input queue are flushInputQueue() ! 206: and clearInputQueue(). This queue, which is nothing more than a chain of ! 207: mbufs, is not protected by a lock since the controller is expected to ! 208: manipulate the input queue from a single thread. If the input filter ! 209: tap mode is set to kIOFilterTapModeInternal, then packets sent to ! 210: this method are also fed to the input filter tap. ! 211: @param m The packet mbuf containing the received frame. ! 212: @param length If non zero, the mbuf will be truncated to the ! 213: given length. If zero, then no truncation will take place. ! 214: @param queue If true, the only action performed is to queue the ! 215: input packet. Otherwise, the dlil_input() function is ! 216: called to handoff all queued packets (including the packet ! 217: passed in). ! 218: @result The number of packets submitted to the network layer. ! 219: Returns 0 if the packet was queued. */ ! 220: ! 221: virtual UInt32 inputPacket(struct mbuf * m, ! 222: UInt32 length = 0, ! 223: bool queue = false); ! 224: ! 225: /*! @function flushInputQueue ! 226: @abstract Deliver all packets in the input queue to the network layer. ! 227: @discussion Remove all packets from the input queue and ! 228: submit them to the network layer by calling dlil_input(). This ! 229: method should be used in connection with the inputPacket() method, ! 230: to flush the input queue after inputPacket() has queued up ! 231: all received packets. See inputPacket() and clearInputQueue(). ! 232: @result The number of packets submitted to the network layer. ! 233: May be zero if the queue is empty. */ ! 234: ! 235: virtual UInt32 flushInputQueue(); ! 236: ! 237: /*! @function clearInputQueue ! 238: @abstract Discard all packets in the input queue. ! 239: @discussion Remove all packets from the input queue and ! 240: release them back to the free buffer pool. The packets are not ! 241: delivered to the network layer. Also see flushInputQueue(). ! 242: @result The number of packets released. */ ! 243: ! 244: virtual UInt32 clearInputQueue(); ! 245: ! 246: /*! @function inputEvent ! 247: @abstract Deliver an event to the network layer. ! 248: @discussion Called by the controller driver to send a network event ! 249: to the network layer. Possible applications include: media changed ! 250: events, power management events, controller state change events. ! 251: @param eventType The event type. ! 252: @param arg An argument associated with the event. */ ! 253: ! 254: virtual void inputEvent(UInt32 eventType, void * arg); ! 255: ! 256: /*! @function registerOutputHandler ! 257: @abstract Register the output handler. ! 258: @discussion The interface will forward all output packets, sent ! 259: from the network layer, to the output handler registered through ! 260: this method. Until a handler is registered, handleClientOpen() ! 261: will refuse all client opens. The output handler cannot be changed ! 262: when the interface is registered. ! 263: @param target Target object that implements the output action. ! 264: @param action The action which handles output packets. ! 265: @result true if the handler provided was accepted, false otherwise. */ ! 266: ! 267: virtual bool registerOutputHandler(OSObject * target, ! 268: IOOutputAction action); ! 269: ! 270: /*! @function setInputFilterTapMode ! 271: @abstract Set the mode of the input packet tap ! 272: @discussion To specify how the filter tap will connect to the input packet ! 273: stream when the tap becomes enabled. See IOFilterTapMode enumeration for ! 274: a description of the modes. This method will refuse to change the mode ! 275: when the interface is registered. ! 276: @param The new mode. ! 277: @result true if the new mode was accepted, false otherwise. */ ! 278: ! 279: virtual bool setInputFilterTapMode(IOFilterTapMode mode); ! 280: ! 281: /*! @function setOutputFilterTapMode ! 282: @abstract Set the mode of the output packet tap ! 283: @discussion To specify how the filter tap will connect to the output packet ! 284: stream once the tap becomes enabled. See IOFilterTapMode enumeration for ! 285: a description of the modes. This method will refuse to change the mode ! 286: when the interface is registered. ! 287: @param The new mode. ! 288: @result true if the new mode was accepted, false otherwise. */ ! 289: ! 290: virtual bool setOutputFilterTapMode(IOFilterTapMode mode); ! 291: ! 292: /*! @function getInputFilterTapMode ! 293: @abstract Get the input filter tap mode. ! 294: @result Returns the current mode of the input packet tap. */ ! 295: ! 296: virtual IOFilterTapMode getInputFilterTapMode() const; ! 297: ! 298: /*! @function getOutputFilterTapMode ! 299: @abstract Get the output filter tap mode. ! 300: @result Returns the current mode of the input packet tap. */ ! 301: ! 302: virtual IOFilterTapMode getOutputFilterTapMode() const; ! 303: ! 304: /*! @function feedInputFilterTap ! 305: @abstract Feed a packet to the input filter tap. ! 306: @discussion ! 307: This method should not be called if the input filter tap mode is ! 308: set to kIOFilterTapModeInternal, since the tap would already ! 309: receive every input packet that flows through the interface. ! 310: A further call to feedInputFilterTap() would cause ! 311: the tap to receive multiple copies of the same input packet. ! 312: @param pkt The packet mbuf to pass to the input tap. The rcvif ! 313: field in the mbuf is modified by this method. */ ! 314: ! 315: virtual void feedInputFilterTap(struct mbuf * pkt); ! 316: ! 317: /*! @function feedOutputFilterTap ! 318: @abstract Feed a packet to the output filter tap. ! 319: @discussion ! 320: This method should not be called if the output filter tap mode is ! 321: set to kIOFilterTapModeInternal, since the tap would already ! 322: receive every output packet that flows through the interface. ! 323: A further call to feedOutputFilterTap() would cause ! 324: the tap to receive multiple copies of the same output packet. ! 325: @param pkt The packet mbuf to pass to the output tap. */ ! 326: ! 327: virtual void feedOutputFilterTap(struct mbuf * pkt); ! 328: ! 329: /*! @function getNamePrefix ! 330: @abstract Get a name prefix for the interface. ! 331: @discussion The name of the interface advertised to the network layer ! 332: is generated by concatenating the string returned by this method, ! 333: and an integer unit number assigned by an external entity. ! 334: A family specific subclass of IONetworkInterface must implement ! 335: this method to assign a consistent name for all interfaces that ! 336: are members of the same family. ! 337: ! 338: @result A pointer to a constant string. */ ! 339: ! 340: virtual const char * getNamePrefix() const = 0; ! 341: ! 342: /*! @function getInterfaceName ! 343: @discussion The if_name field in the ifnet structure is returned. ! 344: @result Pointer to a string containing the interface name. NULL ! 345: if a name has not yet been assigned. */ ! 346: ! 347: virtual const char * getInterfaceName() const; ! 348: ! 349: /*! @function getInterfaceType ! 350: @discussion The if_data.ifi_type field in the ifnet structure is returned. ! 351: @result The interface type that matches one of the types ! 352: defined in bsd/net/if_types.h. */ ! 353: ! 354: virtual UInt8 getInterfaceType() const; ! 355: ! 356: /*! @function getMaxTransferUnit ! 357: @discussion The if_data.ifi_mtu field in the ifnet structure is returned. ! 358: @result The interface MTU size. For Ethernet (not jumbo frames), this ! 359: should be 1500. */ ! 360: ! 361: virtual UInt32 getMaxTransferUnit() const; ! 362: ! 363: /*! @function getFlags ! 364: @discussion The if_flags field in the ifnet structure is returned. ! 365: @result The interface flags. */ ! 366: ! 367: virtual UInt16 getFlags() const; ! 368: ! 369: /*! @function getExtraFlags ! 370: @discussion The if_eflags field in the ifnet structure is returned. ! 371: @result The interface extra flags. */ ! 372: ! 373: virtual UInt32 getExtraFlags() const; ! 374: ! 375: /*! @function getMediaAddressLength ! 376: @discussion The if_data.ifi_addrlen field in the ifnet structure ! 377: is returned. ! 378: @result The size of the media or link address. For Ethernet, ! 379: this should be 6. */ ! 380: ! 381: virtual UInt8 getMediaAddressLength() const; ! 382: ! 383: /*! @function getMediaHeaderLength ! 384: @discussion The if_data.ifi_hdrlen field in the ifnet structure ! 385: is returned. ! 386: @result The media header length. For Ethernet, this should be 14. */ ! 387: ! 388: virtual UInt8 getMediaHeaderLength() const; ! 389: ! 390: /*! @function getUnitNumber ! 391: @discussion The if_unit field in the ifnet structure is returned. ! 392: @result The assigned interface unit number. */ ! 393: ! 394: virtual UInt16 getUnitNumber() const; ! 395: ! 396: /*! @function setInterfaceName ! 397: @discussion Update the if_name field in the ifnet structure. ! 398: @param name A new name for the interface. ! 399: @result true if the interface is unregistered ! 400: and the update was successful, false otherwise. */ ! 401: ! 402: virtual bool setInterfaceName(const char * name); ! 403: ! 404: /*! @function setInterfaceType ! 405: @discussion Update the if_data.ifi_type field in the ifnet structure. ! 406: @param type The type of the interface. See bsd/net/if_types.h for the ! 407: defined types. ! 408: @result true if the interface is unregistered ! 409: and the update was successful, false otherwise. */ ! 410: ! 411: virtual bool setInterfaceType(UInt8 type); ! 412: ! 413: /*! @function setMaxTransferUnit ! 414: @discussion Update the if_data.ifi_mtu field in the ifnet structure. ! 415: @param mtu The interface MTU size. ! 416: @result true if the interface is unregistered ! 417: and the update was successful, false otherwise. */ ! 418: ! 419: virtual bool setMaxTransferUnit(UInt32 mtu); ! 420: ! 421: /*! @function setFlags ! 422: @discussion Perform a read-modify-write operation on the if_flags ! 423: field in the ifnet structure. ! 424: @param flags The flag bits that should be set. ! 425: @param clear The flag bits that should be cleared. If 0, then non ! 426: of the flags are cleared and the result is formed by OR'ing the ! 427: original flags with the new flags. ! 428: @result true if the interface is unregistered ! 429: and the update was successful, false otherwise. */ ! 430: ! 431: virtual bool setFlags(UInt16 flags, UInt16 clear = 0); ! 432: ! 433: /*! @function setExtraFlags ! 434: @discussion Perform a read-modify-write operation on the if_eflags ! 435: field in the ifnet structure. ! 436: @param flags The flags that should be set. ! 437: @param clear The flags that should be cleared. If 0, then non ! 438: of the flags are cleared and the result is formed by OR'ing the ! 439: original flags with the new flags. ! 440: @result true if the interface is unregistered ! 441: and the update was successful, false otherwise. */ ! 442: ! 443: virtual bool setExtraFlags(UInt32 flags, UInt32 clear = 0); ! 444: ! 445: /*! @function setMediaAddressLength ! 446: @discussion Update the if_data.ifi_addrlen field in the ifnet structure. ! 447: @param length The new media address length. ! 448: @result true if the interface is unregistered ! 449: and the update was successful, false otherwise. */ ! 450: ! 451: virtual bool setMediaAddressLength(UInt8 length); ! 452: ! 453: /*! @function setMediaHeaderLength ! 454: @discussion Update the if_data.ifi_hdrlen field in the ifnet structure. ! 455: @param length The new media header length. ! 456: @result true if the interface is unregistered ! 457: and the update was successful, false otherwise. */ ! 458: ! 459: virtual bool setMediaHeaderLength(UInt8 length); ! 460: ! 461: /*! @function setUnitNumber ! 462: @discussion Update the if_unit field in the ifnet structure. ! 463: @param unit The unit number to assign to this interface. ! 464: @result true if the interface is unregistered ! 465: and the unit number was accepted, false otherwise. */ ! 466: ! 467: virtual bool setUnitNumber(UInt16 unit); ! 468: ! 469: /*! @function addNetworkData ! 470: @abstract Add an IONetworkData object to a dictionary kept by ! 471: the interface. ! 472: @param aData An IONetworkData object. ! 473: @result true if the data object was added successfully, false otherwise. */ ! 474: ! 475: virtual bool addNetworkData(IONetworkData * aData); ! 476: ! 477: /*! @function removeNetworkData ! 478: @abstract Remove an entry from the dictionary of IONetworkData ! 479: objects. ! 480: @param aKey An OSSymbol key for an IONetworkData entry in the ! 481: dictionary. ! 482: @result True if completed without errors, ! 483: false if the operation was aborted. */ ! 484: ! 485: virtual bool removeNetworkData(const OSSymbol * aKey); ! 486: ! 487: /*! @function removeNetworkData ! 488: @abstract Remove an entry from the dictionary of IONetworkData ! 489: objects. ! 490: @param aKey A C string key for an IONetworkData entry in the ! 491: dictionary. ! 492: @result True if completed without errors, ! 493: false if the operation was aborted. */ ! 494: ! 495: virtual bool removeNetworkData(const char * aKey); ! 496: ! 497: /*! @function getNetworkData ! 498: @abstract Get an entry from the dictionary of IONetworkData objects. ! 499: @discussion Perform a lookup of the dictionary kept by the interface, ! 500: and return an entry that matches the specified string key. ! 501: @param aKey Search for an entry with this string key. ! 502: @result The matching entry, or 0 if no match was found. */ ! 503: ! 504: virtual IONetworkData * getNetworkData(const char * aKey) const; ! 505: ! 506: /*! @function getNetworkData ! 507: @abstract Get an entry from the dictionary of IONetworkData objects. ! 508: @discussion Perform a lookup of the dictionary kept by the interface, ! 509: and return an entry that matches the specified OSSymbol key. ! 510: @param aKey Search for an entry with this OSSymbol key. ! 511: @result The matching entry, or 0 if no match was found. */ ! 512: ! 513: virtual IONetworkData * getNetworkData(const OSSymbol * aKey) const; ! 514: ! 515: // Compatibility method (to be removed) ! 516: inline IONetworkData * getParameter(const char * aKey) const ! 517: { return getNetworkData(aKey); } ! 518: ! 519: protected: ! 520: ! 521: /*! @function free ! 522: @abstract Free the IONetworkInterface instance. ! 523: @discussion Resource allocated during init are released, and ! 524: clearInputQueue() is called to make sure the input queue is clean. */ ! 525: ! 526: virtual void free(); ! 527: ! 528: /*! @function handleOpen ! 529: @abstract Handle a client open on the interface. ! 530: @discussion The open() method in ! 531: IOService calls this method with the arbitration lock held, and this ! 532: method must return true to accept the client open. This method will ! 533: in turn call handleClientOpen() and controllerDidOpen(). Subclasses ! 534: must not override this method. ! 535: @param client The client object that requested the open. ! 536: @param options Not used. See IOService. ! 537: @param argument Not used. See IOService. ! 538: @result true to accept the client open, false otherwise. */ ! 539: ! 540: virtual bool handleOpen(IOService * client, ! 541: IOOptionBits options, ! 542: void * argument); ! 543: ! 544: /*! @function handleClose ! 545: @abstract Handle a close by a client. ! 546: @discussion The close() method in ! 547: IOService calls this method with the arbitration lock held. This method ! 548: will in turn call handleClientClose() and controllerWillClose(). ! 549: Subclasses must not override this method. ! 550: @param client The client object that requested the close. ! 551: @param options Not used. See IOService. */ ! 552: ! 553: virtual void handleClose(IOService * client, IOOptionBits options); ! 554: ! 555: /*! @function handleIsOpen ! 556: @abstract Query a client that has an open on the controller. ! 557: @discussion This method is always called by IOService with the ! 558: arbitration lock held. Subclasses must not override this method. ! 559: @result true if the specified client, or any client if none is ! 560: specified, presently has an open on this object. */ ! 561: ! 562: virtual bool handleIsOpen(const IOService * client) const; ! 563: ! 564: /*! @function lock ! 565: @abstract Take the interface lock. ! 566: @discussion Take the recursive lock that protects the interface ! 567: data and state. All updates to the interface state and to the ! 568: ifnet structure fields are protected by this lock. */ ! 569: ! 570: virtual void lock(); ! 571: ! 572: /*! @function unlock ! 573: @abstract Release the interface lock. ! 574: @discussion Release the recursive lock that protects the interface ! 575: data and state. */ ! 576: ! 577: virtual void unlock(); ! 578: ! 579: /*! @function controllerDidOpen ! 580: @abstract Prepare the controller after it has been opened. ! 581: @discussion Called by handleOpen() to configure the controller after it ! 582: has just been opened. The open on the controller occurs after the ! 583: interface receives the initial open request from a client. Subclasses ! 584: can override this method and setup the controller before allowing the ! 585: client open. The implementation in the subclass must call the method in ! 586: super and check the return value. ! 587: @param controller The controller that was opened. ! 588: @result Must return true in order for handleOpen() to accept ! 589: the client open. If the return is false, then the controller will be ! 590: closed and the client open will be rejected. */ ! 591: ! 592: virtual bool controllerDidOpen(IONetworkController * controller); ! 593: ! 594: /*! @function controllerWillClose ! 595: @abstract Quiesce the controller before it is closed. ! 596: @discussion Called by handleClose() after receiving a close from the ! 597: last client, and just before the controller is closed. Subclasses ! 598: can override this method to perform any cleanup action before the ! 599: controller is closed. ! 600: @param controller The controller that will be closed. */ ! 601: ! 602: virtual void controllerWillClose(IONetworkController * controller); ! 603: ! 604: /*! @function performCommand ! 605: @abstract Handle commands from the network layer. ! 606: @discussion Handles generic socket ioctl commands sent to the interface. ! 607: IONetworkInterface handles commands that are common to all network ! 608: families. A subclass of IONetworkInterface may override this method ! 609: in order to handle the same command that is handled here, but in a ! 610: different manner, or (the more like case) to augment the command ! 611: handling to include additional commands, and call super for any ! 612: commands not handled in the subclass. ! 613: The ioctl commands handled by IONetworkInterface are ! 614: SIOCGIFMTU (Get interface MTU size), ! 615: SIOCSIFMTU (Set interface MTU size), ! 616: SIOCSIFMEDIA (Set media), and ! 617: SIOCGIFMEDIA (Get media and link status). ! 618: @param controller The controller object. ! 619: @param cmd The command code. ! 620: @param arg0 Command argument. ! 621: @param arg1 Command argument. ! 622: @result A BSD return code defined in bsd/sys/errno.h. */ ! 623: ! 624: virtual SInt performCommand(IONetworkController * controller, ! 625: UInt32 cmd, ! 626: void * arg0, ! 627: void * arg1); ! 628: ! 629: /*! @function getIfnet ! 630: @abstract Get the ifnet structure allocated by the interface object. ! 631: @discussion Request an interface to reveal its ifnet structure. ! 632: A concrete subclass must allocate an ifnet structure when the ! 633: object is initialized, and return a pointer to the ifnet structure ! 634: when this method is called. ! 635: @result Pointer to an ifnet structure allocated by a concrete ! 636: interface subclass. */ ! 637: ! 638: virtual struct ifnet * getIfnet() const = 0; ! 639: ! 640: /*! @function initIfnet ! 641: @abstract Initialize the ifnet structure. ! 642: @discussion Subclasses must override ! 643: this method and initialize the ifnet structure given in a family specific ! 644: manner. Subclasses may use the "setter" methods such as setFlags() to ! 645: initialize the ifnet fields. The implementation in the subclass must call ! 646: the version in super before it returns, to allow IONetworkInterface to ! 647: complete the initialization. ! 648: @param ifp Pointer to an ifnet structure obtained earlier through the ! 649: getIfnet() call. ! 650: @result true on success, false otherwise. */ ! 651: ! 652: virtual bool initIfnet(struct ifnet * ifp); ! 653: ! 654: /*! @function handleClientOpen ! 655: @abstract Handle a client open. ! 656: @discussion Called by handleOpen() to qualify a client object that ! 657: is attempting to open the interface. ! 658: @param controller The controller object (provider). ! 659: @param client The client object. ! 660: @result true to accept the client open, false to refuse the open. */ ! 661: ! 662: virtual bool handleClientOpen(IONetworkController * controller, ! 663: IOService * client); ! 664: ! 665: /*! @function handleClientClose ! 666: @abstract Handle a client close. ! 667: @discussion Called by handleOpen() to notify that a client object has ! 668: closed the interface. ! 669: @param controller The controller object (provider). ! 670: @param client The client object. */ ! 671: ! 672: virtual void handleClientClose(IONetworkController * controller, ! 673: IOService * client); ! 674: ! 675: /*! @function newUserClient ! 676: @abstract Create a new user client. ! 677: @discussion Create a new IOUserClient to handle userspace client requests. ! 678: The default implementation will create an IONetworkUserClient instance ! 679: if the type given is kIONUCType. ! 680: @param owningTask See IOService. ! 681: @param security_id See IOService. ! 682: @param type See IOService. ! 683: @param handler See IOService. ! 684: @result kIOReturnSuccess if an IONetworkUserClient was created. */ ! 685: ! 686: virtual IOReturn newUserClient(task_t owningTask, ! 687: void * security_id, ! 688: UInt32 type, ! 689: IOUserClient ** handler); ! 690: ! 691: /*! @function setInterfaceNameInt ! 692: @discussion Update the if_name field in the ifnet structure. ! 693: @param name A new name for the interface. ! 694: @result true if the update was successful, false otherwise. */ ! 695: ! 696: virtual bool setInterfaceNameInt(const char * name); ! 697: ! 698: /*! @function setInterfaceTypeInt ! 699: @discussion Update the if_data.ifi_type field in the ifnet structure. ! 700: @param type The type of the interface. See bsd/net/if_types.h for the ! 701: defined types. ! 702: @result true if the update was successful, false otherwise. */ ! 703: ! 704: virtual bool setInterfaceTypeInt(UInt8 type); ! 705: ! 706: /*! @function setMaxTransferUnitInt ! 707: @discussion Update the if_data.ifi_mtu field in the ifnet structure. ! 708: @param mtu The interface MTU size. ! 709: @result true if the update was successful, false otherwise. */ ! 710: ! 711: virtual bool setMaxTransferUnitInt(UInt32 mtu); ! 712: ! 713: /*! @function setFlagsInt ! 714: @discussion Perform a read-modify-write operation on the if_flags ! 715: field in the ifnet structure. ! 716: @param flags The flag bits that should be set. ! 717: @param clear The flag bits that should be cleared. If 0, then non ! 718: of the flags are cleared and the result is formed by OR'ing the ! 719: original flags with the new flags. ! 720: @result true if the update was successful, false otherwise. */ ! 721: ! 722: virtual bool setFlagsInt(UInt16 flags, UInt16 clear = 0); ! 723: ! 724: /*! @function setExtraFlagsInt ! 725: @discussion Perform a read-modify-write operation on the if_eflags ! 726: field in the ifnet structure. ! 727: @param flags The flags that should be set. ! 728: @param clear The flags that should be cleared. If 0, then non ! 729: of the flags are cleared and the result is formed by OR'ing the ! 730: original flags with the new flags. ! 731: @result true if the update was successful, false otherwise. */ ! 732: ! 733: virtual bool setExtraFlagsInt(UInt32 flags, UInt32 clear = 0); ! 734: ! 735: /*! @function setMediaAddressLengthInt ! 736: @discussion Update the if_data.ifi_addrlen field in the ifnet structure. ! 737: @param length The new media address length. ! 738: @result true if the field was updated, false otherwise. */ ! 739: ! 740: virtual bool setMediaAddressLengthInt(UInt8 length); ! 741: ! 742: /*! @function setMediaHeaderLengthInt ! 743: @discussion Update the if_data.ifi_hdrlen field in the ifnet structure. ! 744: @param length The new media header length. ! 745: @result true if the update was successful, false otherwise. */ ! 746: ! 747: virtual bool setMediaHeaderLengthInt(UInt8 length); ! 748: ! 749: /*! @function setUnitNumberInt ! 750: @discussion Update the if_unit field in the ifnet structure. ! 751: @param unit The unit number to assign to this interface. ! 752: @result true if the unit number was accepted, false otherwise. */ ! 753: ! 754: virtual bool setUnitNumberInt(UInt16 unit); ! 755: }; ! 756: ! 757: #endif /* !_IONETWORKINTERFACE_H */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.