From 3f3689bb79f1fa6e5bf21e925e17463016c3372e Mon Sep 17 00:00:00 2001 From: Waldemar Kornewald Date: Tue, 1 Jun 2004 15:01:01 +0000 Subject: [PATCH] Finished doxygen comments for the PPP API. Minor changes to simplify PAP authenticator. git-svn-id: file:///srv/svn/repos/haiku/trunk/current@7730 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- .../kernel/network/ppp/pap/Protocol.cpp | 34 ------ src/add-ons/kernel/network/ppp/pap/Protocol.h | 7 -- .../ppp/shared/libkernelppp/KPPPDevice.cpp | 4 +- .../ppp/shared/libkernelppp/KPPPInterface.cpp | 27 +++-- .../ppp/shared/libkernelppp/KPPPLCP.cpp | 28 +++-- .../shared/libkernelppp/KPPPLCPExtension.cpp | 44 ++++++- .../ppp/shared/libkernelppp/KPPPLayer.cpp | 2 +- .../shared/libkernelppp/KPPPOptionHandler.cpp | 112 +++++++++++++++++- .../ppp/shared/libkernelppp/KPPPProtocol.cpp | 63 ++++++++++ .../shared/libkernelppp/KPPPReportManager.cpp | 29 +++++ .../shared/libkernelppp/KPPPStateMachine.cpp | 107 +++++++++++++++-- .../ppp/shared/libkernelppp/KPPPUtils.cpp | 4 +- .../shared/libkernelppp/headers/KPPPDevice.h | 10 +- .../libkernelppp/headers/KPPPInterface.h | 4 +- .../ppp/shared/libkernelppp/headers/KPPPLCP.h | 2 +- .../libkernelppp/headers/KPPPLCPExtension.h | 4 +- .../shared/libkernelppp/headers/KPPPManager.h | 1 + .../libkernelppp/headers/KPPPOptionHandler.h | 25 ++-- .../libkernelppp/headers/KPPPProtocol.h | 34 +++++- .../libkernelppp/headers/KPPPReportManager.h | 1 + .../libkernelppp/headers/KPPPStateMachine.h | 11 +- .../libkernelppp/headers/LockerHelper.h | 26 ++-- .../shared/libkernelppp/headers/PPPControl.h | 23 +++- .../ppp/shared/libkernelppp/headers/PPPDefs.h | 20 ++-- .../libkernelppp/headers/PPPReportDefs.h | 6 +- .../ppp/shared/libppp/PPPInterface.cpp | 96 ++++++++++++++- .../shared/libppp/PPPInterfaceListener.cpp | 51 +++++++- .../network/ppp/shared/libppp/PPPManager.cpp | 97 +++++++++++++++ .../libppp/headers/PPPInterfaceListener.h | 8 +- 29 files changed, 741 insertions(+), 139 deletions(-) diff --git a/src/add-ons/kernel/network/ppp/pap/Protocol.cpp b/src/add-ons/kernel/network/ppp/pap/Protocol.cpp index 698e79b591..7bebc028fa 100644 --- a/src/add-ons/kernel/network/ppp/pap/Protocol.cpp +++ b/src/add-ons/kernel/network/ppp/pap/Protocol.cpp @@ -56,27 +56,6 @@ PAPHandler::AddToRequest(KPPPConfigurePacket& request) } -status_t -PAPHandler::ParseNak(const KPPPConfigurePacket& nak) -{ - return B_OK; -} - - -status_t -PAPHandler::ParseReject(const KPPPConfigurePacket& reject) -{ - return B_OK; -} - - -status_t -PAPHandler::ParseAck(const KPPPConfigurePacket& ack) -{ - return B_OK; -} - - status_t PAPHandler::ParseRequest(const KPPPConfigurePacket& request, int32 index, KPPPConfigurePacket& nak, KPPPConfigurePacket& reject) @@ -95,19 +74,6 @@ PAPHandler::ParseRequest(const KPPPConfigurePacket& request, } -status_t -PAPHandler::SendingAck(const KPPPConfigurePacket& ack) -{ - return B_OK; -} - - -void -PAPHandler::Reset() -{ -} - - // PAP PAP::PAP(KPPPInterface& interface, driver_parameter *settings) : KPPPProtocol("PAP", PPP_AUTHENTICATION_PHASE, PAP_PROTOCOL, PPP_PROTOCOL_LEVEL, diff --git a/src/add-ons/kernel/network/ppp/pap/Protocol.h b/src/add-ons/kernel/network/ppp/pap/Protocol.h index e3122bf85d..5fee22b1db 100644 --- a/src/add-ons/kernel/network/ppp/pap/Protocol.h +++ b/src/add-ons/kernel/network/ppp/pap/Protocol.h @@ -38,15 +38,8 @@ class PAPHandler : public KPPPOptionHandler { { return fOwner; } virtual status_t AddToRequest(KPPPConfigurePacket& request); - virtual status_t ParseNak(const KPPPConfigurePacket& nak); - virtual status_t ParseReject(const KPPPConfigurePacket& reject); - virtual status_t ParseAck(const KPPPConfigurePacket& ack); - virtual status_t ParseRequest(const KPPPConfigurePacket& request, int32 index, KPPPConfigurePacket& nak, KPPPConfigurePacket& reject); - virtual status_t SendingAck(const KPPPConfigurePacket& ack); - - virtual void Reset(); private: PAP& fOwner; diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPDevice.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPDevice.cpp index bbd5af1b90..7d8914bc26 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPDevice.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPDevice.cpp @@ -8,7 +8,7 @@ /*! \class KPPPDevice \brief Represents a device at the lowest level of the communcation stack. - A device may be, for example: Modem, PPPoE, PPTP.\n + A device may be, for example: Modem, PPPoE, PPTP. \n It encapsulates the packet and sends it over a line to the other end. The device is the first layer that receives a packet. */ @@ -101,7 +101,7 @@ KPPPDevice::Receive(struct mbuf *packet, uint16 protocolNumber) /*! \brief Report that device is going up. - Called by Up().\n + Called by Up(). \n From now on, the connection attempt can may be aborted by calling Down(). \return diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPInterface.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPInterface.cpp index be8c3ec5b6..88799cabf1 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPInterface.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPInterface.cpp @@ -9,14 +9,14 @@ \brief The kernel representation of a PPP interface. This class is never created by the programmer directly. Instead, the PPP manager - kernel module should be used.\n + kernel module should be used. \n KPPPInterface handles all interface-specific commands from userspace and it passes packets to their receiver or sends them to the device. Additionally, it contains the KPPPLCP object with represents the LCP protocol and the - KPPPStateMachine object which represents the state machine.\n - All PPP modules are loaded from here.\n + KPPPStateMachine object which represents the state machine. \n + All PPP modules are loaded from here. \n Protocols and encapsulators should be added to this class. LCP-specific extensions - belong to the KPPPLCP object.\n + belong to the KPPPLCP object. \n Multilink support is distributed between KPPPInterface and KPPPStateMachine. */ @@ -57,7 +57,7 @@ // - add missing settings support (DialRetryDelay, etc.) -// needed for redial: +//! Private structure needed for redialing. typedef struct redial_info { KPPPInterface *interface; thread_id *thread; @@ -614,6 +614,7 @@ KPPPInterface::SetDevice(KPPPDevice *device) /*! \brief Adds a new protocol to this interface. + NOTE: You can only add protocols in \c PPP_DOWN_PHASE. \n A protocol add-on should call this method to register itself. The best place to do this is in your module's \c add_to() function. @@ -687,8 +688,9 @@ KPPPInterface::AddProtocol(KPPPProtocol *protocol) /*! \brief Removes a protocol from this interface. + NOTE: You can only remove protocols in \c PPP_DOWN_PHASE. \n A protocol add-on should call this method to remove itself explicitly from the - interface.\n + interface. \n Normally, this method is called in KPPPProtocol's destructor. Do not call it yourself unless you know what you do! @@ -945,7 +947,7 @@ KPPPInterface::SetPFCOptions(uint8 pfcOptions) /*! \brief Brings this interface up. - \c Down() overrides all \c Up() requests.\n + \c Down() overrides all \c Up() requests. \n This blocks until the connection process is finished. \return \c true if successful or \c false otherwise. @@ -1143,7 +1145,7 @@ KPPPInterface::Up() /*! \brief Brings this interface down. - \c Down() overrides all \c Up() requests.\n + \c Down() overrides all \c Up() requests. \n This blocks until diconnecting finished. \return \c true if successful or \c false otherwise. @@ -1342,7 +1344,7 @@ KPPPInterface::IsAllowedToSend() const /*! \brief Sends a packet to the device. This brings the interface up if dial-on-demand is enabled and we are not - connected.\n + connected. \n PFC encoding is handled here. \param packet The packet. @@ -1450,7 +1452,7 @@ KPPPInterface::Send(struct mbuf *packet, uint16 protocolNumber) Encapsulation protocols may use this method to pass encapsulated packets to the PPP interface. Packets will be handled as if they were raw packets that came - directly from the device via \c ReceiveFromDevice().\n + directly from the device via \c ReceiveFromDevice(). \n If no handler could be found in this interface the parent's \c Receive() method is called. @@ -1527,7 +1529,7 @@ KPPPInterface::Receive(struct mbuf *packet, uint16 protocolNumber) /*! \brief Receives a base PPP packet from the device. - KPPPDevice should call this method when it receives a packet.\n + KPPPDevice should call this method when it receives a packet. \n PFC decoding is handled here. \param packet The packet. @@ -1682,7 +1684,7 @@ KPPPInterface::StackControl(uint32 op, void *data) } -// used by ControlEachHandler() +//! Utility class used by ControlEachHandler(). template class CallStackControl { public: @@ -1845,6 +1847,7 @@ redial_thread(void *data) // ---------------------------------- // Function: interface_deleter_thread // ---------------------------------- +//! Private class. class KPPPInterfaceAccess { public: KPPPInterfaceAccess() {} diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLCP.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLCP.cpp index 0b12e84baa..f85fb93e4d 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLCP.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLCP.cpp @@ -9,11 +9,11 @@ \brief The LCP protocol. Every PPP interface \e must have an LCP protocol. It is used for establishing - and terminating connections.\n + and terminating connections. \n When establishing a connecition the LCP protocol determines connection-specific settings like the packet MRU. These settings are handled by the KPPPOptionHandler class. Additional LCP codes like the PPP Multilink-Protocol uses them should - be implemented through the KPPPLCPExtension class.\n + be implemented through the KPPPLCPExtension class. \n */ #include @@ -50,7 +50,11 @@ KPPPLCP::~KPPPLCP() } -//! Adds a new option handler. +/*! \brief Adds a new option handler. + + NOTE: You can only add option handlers in \c PPP_DOWN_PHASE. \n + There may only be one handler per option type! +*/ bool KPPPLCP::AddOptionHandler(KPPPOptionHandler *optionHandler) { @@ -59,7 +63,8 @@ KPPPLCP::AddOptionHandler(KPPPOptionHandler *optionHandler) LockerHelper locker(StateMachine().fLock); - if(Interface().Phase() != PPP_DOWN_PHASE || OptionHandlerFor(optionHandler->Type())) + if(Interface().Phase() != PPP_DOWN_PHASE + || OptionHandlerFor(optionHandler->Type())) return false; // a running connection may not change and there may only be // one handler per option type @@ -68,7 +73,10 @@ KPPPLCP::AddOptionHandler(KPPPOptionHandler *optionHandler) } -//! Removes an option handler, but does not delete it. +/*! \brief Removes an option handler, but does not delete it. + + NOTE: You can only remove option handlers in \c PPP_DOWN_PHASE. +*/ bool KPPPLCP::RemoveOptionHandler(KPPPOptionHandler *optionHandler) { @@ -122,7 +130,10 @@ KPPPLCP::OptionHandlerFor(uint8 type, int32 *start = NULL) const } -//! Adds a new LCP extension. +/*! \brief Adds a new LCP extension. + + NOTE: You can only add LCP extensions in \c PPP_DOWN_PHASE. +*/ bool KPPPLCP::AddLCPExtension(KPPPLCPExtension *lcpExtension) { @@ -139,7 +150,10 @@ KPPPLCP::AddLCPExtension(KPPPLCPExtension *lcpExtension) } -//! Removes an LCP extension, but does not delete it. +/*! \brief Removes an LCP extension, but does not delete it. + + NOTE: You can only remove LCP extensions in \c PPP_DOWN_PHASE. +*/ bool KPPPLCP::RemoveLCPExtension(KPPPLCPExtension *lcpExtension) { diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLCPExtension.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLCPExtension.cpp index cf23cd329a..7d8e6c252b 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLCPExtension.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLCPExtension.cpp @@ -5,14 +5,30 @@ // Copyright (c) 2003-2004 Waldemar Kornewald, Waldemar.Kornewald@web.de //----------------------------------------------------------------------- +/*! \class KPPPLCPExtension + \brief LCP protocol extension + + This class can be used to extend the supported LCP protocol codes. +*/ + #include #include -KPPPLCPExtension::KPPPLCPExtension(const char *name, uint8 code, KPPPInterface& interface, - driver_parameter *settings) - : fInterface(interface), +/*! \brief Constructor. + + If an error occurs in the constructor you should set \c fInitStatus. + + \param name Name of the extension. + \param code LCP code that this extension can handle. + \param interface Owning interface. + \param settings Settings for this extension. +*/ +KPPPLCPExtension::KPPPLCPExtension(const char *name, uint8 code, + KPPPInterface& interface, driver_parameter *settings) + : fInitStatus(B_OK), + fInterface(interface), fSettings(settings), fCode(code), fEnabled(true) @@ -24,14 +40,16 @@ KPPPLCPExtension::KPPPLCPExtension(const char *name, uint8 code, KPPPInterface& } +//! Destructor. Frees the name and unregisters extension from LCP protocol. KPPPLCPExtension::~KPPPLCPExtension() { - free(fName); - Interface().LCP().RemoveLCPExtension(this); + + free(fName); } +//! Returns \c fInitStatus. May be overridden to return status-dependend errors. status_t KPPPLCPExtension::InitCheck() const { @@ -39,6 +57,7 @@ KPPPLCPExtension::InitCheck() const } +//! Allows controlling this extension from userlevel. status_t KPPPLCPExtension::Control(uint32 op, void *data, size_t length) { @@ -69,6 +88,7 @@ KPPPLCPExtension::Control(uint32 op, void *data, size_t length) } +//! Stack ioctl handler. status_t KPPPLCPExtension::StackControl(uint32 op, void *data) { @@ -81,6 +101,12 @@ KPPPLCPExtension::StackControl(uint32 op, void *data) } +/*! \brief Notification hook when the interface profile changes dynamically. + + You should override this method to update your profile settings if this extension + has such settings at all. This is mostly used by authenticators and possibly + protocols. +*/ void KPPPLCPExtension::ProfileChanged() { @@ -88,6 +114,10 @@ KPPPLCPExtension::ProfileChanged() } +/*! \brief Reset internal connection state. + + This method is called when: connecting, reconfiguring, or disconnecting. +*/ void KPPPLCPExtension::Reset() { @@ -95,6 +125,10 @@ KPPPLCPExtension::Reset() } +/*! \brief You may override this for periodic tasks. + + This method gets called every \c PPP_PULSE_RATE microseconds. +*/ void KPPPLCPExtension::Pulse() { diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLayer.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLayer.cpp index 5dde66339b..e0e2c5fa83 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLayer.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPLayer.cpp @@ -28,7 +28,7 @@ /*! \brief Creates a new layer. - If an error appears in the constructor you should set \c fInitStatus. + If an error occurs in the constructor you should set \c fInitStatus. */ KPPPLayer::KPPPLayer(const char *name, ppp_level level, uint32 overhead) : fInitStatus(B_OK), diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPOptionHandler.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPOptionHandler.cpp index 6d65d5cc61..ad2955a685 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPOptionHandler.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPOptionHandler.cpp @@ -5,11 +5,26 @@ // Copyright (c) 2003-2004 Waldemar Kornewald, Waldemar.Kornewald@web.de //----------------------------------------------------------------------- +/*! \class KPPPOptionHandler + \brief Handler for LCP configure packets. + + This class can be used to extend the supported LCP configure packets. +*/ + #include #include +/*! \brief Constructor. + + If an error occurs in the constructor you should set \c fInitStatus. + + \param name Name of the handler. + \param type Request type you can handle. + \param interface Owning interface. + \param settings Settings for this handler. +*/ KPPPOptionHandler::KPPPOptionHandler(const char *name, uint8 type, KPPPInterface& interface, driver_parameter *settings) : fInitStatus(B_OK), @@ -25,14 +40,16 @@ KPPPOptionHandler::KPPPOptionHandler(const char *name, uint8 type, } +//! Destructor. Frees the name and unregisters handler from LCP protocol. KPPPOptionHandler::~KPPPOptionHandler() { - free(fName); - Interface().LCP().RemoveOptionHandler(this); + + free(fName); } +//! Returns \c fInitStatus. May be overridden to return status-dependend errors. status_t KPPPOptionHandler::InitCheck() const { @@ -40,6 +57,7 @@ KPPPOptionHandler::InitCheck() const } +//! Allows controlling this handler from userlevel. status_t KPPPOptionHandler::Control(uint32 op, void *data, size_t length) { @@ -70,6 +88,7 @@ KPPPOptionHandler::Control(uint32 op, void *data, size_t length) } +//! Stack ioctl handler. status_t KPPPOptionHandler::StackControl(uint32 op, void *data) { @@ -82,8 +101,97 @@ KPPPOptionHandler::StackControl(uint32 op, void *data) } +/*! \brief Notification hook when the interface profile changes dynamically. + + You should override this method to update your profile settings if this handler + has such settings at all. This is mostly used by authenticators and possibly + protocols. +*/ void KPPPOptionHandler::ProfileChanged() { // do nothing by default } + + +/*! \brief Add request item. + + What you do here depends on the connection side (client or server). \n + Received nak and reject packets influence which value gets added to the + request, too. +*/ +status_t +KPPPOptionHandler::AddToRequest(KPPPConfigurePacket& request) +{ + return B_OK; +} + + +/*! \brief Parse a nak received from the peer. + + This method is called only once for each option handler. You must find the item + yourself (no index is given). +*/ +status_t +KPPPOptionHandler::ParseNak(const KPPPConfigurePacket& nak) +{ + return B_OK; +} + + +/*! \brief Parse a reject received from the peer. + + This method is called only once for each option handler. You must find the item + yourself (no index is given). +*/ +status_t +KPPPOptionHandler::ParseReject(const KPPPConfigurePacket& reject) +{ + return B_OK; +} + + +/*! \brief Parse an ack received from the peer. + + This method is called only once for each option handler. You must find the item + yourself (no index is given). +*/ +status_t +KPPPOptionHandler::ParseAck(const KPPPConfigurePacket& ack) +{ + return B_OK; +} + + +/*! \brief Handler for configure requests sent by peer. + + Index may be behind the last item which means additional values can be + appended. + + \param request The requested values. + \param index Index of item in \a request. + \param nak Values for the nak should be added here. + \param reject Values for the reject should be added here. +*/ +status_t +KPPPOptionHandler::ParseRequest(const KPPPConfigurePacket& request, + int32 index, KPPPConfigurePacket& nak, KPPPConfigurePacket& reject) +{ + return B_OK; +} + + +//! Notification that we ack the values in \a ack. +status_t +KPPPOptionHandler::SendingAck(const KPPPConfigurePacket& ack) +{ + return B_OK; +} + + +//! Reset internal state (e.g.: remove list of rejected values). +void +KPPPOptionHandler::Reset() +{ + // do nothing by default +} diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPProtocol.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPProtocol.cpp index c41fe3d37e..6c649443a5 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPProtocol.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPProtocol.cpp @@ -5,6 +5,12 @@ // Copyright (c) 2003-2004 Waldemar Kornewald, Waldemar.Kornewald@web.de //----------------------------------------------------------------------- +/*! \class KPPPProtocol. + \brief Represents a PPP protocol object. + + This class is the base for all protocols, encapsulators, and authenticators. +*/ + #include #include #include @@ -13,6 +19,27 @@ #include +/*! \brief Constructs a PPP protocol. + + If you are creating a normal protocol use a level of \c PPP_PROTOCOL_LEVEL. + Encapsulators like compression protocols should use a different level. \n + Authenticators are identified by a type string equal to "Authenticator" and they + have an optionHandler that implements only the following methods: + - AddToRequest + - ParseRequest + + \param name The protocol name. + \param activationPhase Our activation phase. + \param protocolNumber Our protocol number. + \param level The level at which we get inserted into the list of protocols. + \param addressFamily The address family. Values < 0 and > 0xFF are ignored. + \param overhead The protocol's header size. + \param interface The owner. + \param settings Our settings. + \param flags Optional flags. See \c ppp_protocol_flags for more information. + \param type Optional type string. Used by authenticators, for example. + \param optionHandler Optional handler associated with this protocol. +*/ KPPPProtocol::KPPPProtocol(const char *name, ppp_phase activationPhase, uint16 protocolNumber, ppp_level level, int32 addressFamily, uint32 overhead, KPPPInterface& interface, @@ -48,6 +75,7 @@ KPPPProtocol::KPPPProtocol(const char *name, ppp_phase activationPhase, } +//! Removes this protocol from the interface and frees the type. KPPPProtocol::~KPPPProtocol() { Interface().RemoveProtocol(this); @@ -56,6 +84,10 @@ KPPPProtocol::~KPPPProtocol() } +/*! \brief This should uninit the protocol before it gets deleted. + + You may want to remove all routes of this protocol. +*/ void KPPPProtocol::Uninit() { @@ -63,6 +95,10 @@ KPPPProtocol::Uninit() } +/*! \brief Allows private extensions. + + If you override this method you must call the parent's method for unknown ops. +*/ status_t KPPPProtocol::Control(uint32 op, void *data, size_t length) { @@ -104,6 +140,7 @@ KPPPProtocol::Control(uint32 op, void *data, size_t length) } +//! Stack ioctl handler. status_t KPPPProtocol::StackControl(uint32 op, void *data) { @@ -116,6 +153,10 @@ KPPPProtocol::StackControl(uint32 op, void *data) } +/*! \brief Enables or disables this protocol. + + A disabled protocol is ignored and Up() is not called! +*/ void KPPPProtocol::SetEnabled(bool enabled = true) { @@ -129,6 +170,7 @@ KPPPProtocol::SetEnabled(bool enabled = true) } +//! Returns if this protocol is allowed to send a packet (enabled, up, etc.). bool KPPPProtocol::IsAllowedToSend() const { @@ -136,6 +178,11 @@ KPPPProtocol::IsAllowedToSend() const } +/*! \brief Report that the protocol is going up. + + Called by Up(). \n + From now on, the connection attempt can may be aborted by calling Down(). +*/ void KPPPProtocol::UpStarted() { @@ -143,6 +190,10 @@ KPPPProtocol::UpStarted() } +/*! \brief Report that the protocol is going down. + + Called by Down(). +*/ void KPPPProtocol::DownStarted() { @@ -150,6 +201,10 @@ KPPPProtocol::DownStarted() } +/*! \brief Reports that we failed going up. May only be called after Up() was called. + + Authenticators \e must call the state machine's authentication notification first! +*/ void KPPPProtocol::UpFailedEvent() { @@ -159,6 +214,10 @@ KPPPProtocol::UpFailedEvent() } +/*! \brief Reports that we went up. May only be called after Up() was called. + + Authenticators \e must call the state machine's authentication notification first! +*/ void KPPPProtocol::UpEvent() { @@ -168,6 +227,10 @@ KPPPProtocol::UpEvent() } +/*! \brief Reports that we went down. This may be called to indicate connection loss. + + Authenticators \e must call the state machine's authentication notification first! +*/ void KPPPProtocol::DownEvent() { diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPReportManager.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPReportManager.cpp index 13c28502fb..ccd9d10374 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPReportManager.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPReportManager.cpp @@ -5,18 +5,27 @@ // Copyright (c) 2003-2004 Waldemar Kornewald, Waldemar.Kornewald@web.de //----------------------------------------------------------------------- +/*! \class KPPPReportManager + \brief Manager for PPP reports and report requests. +*/ + #include #include #include +/*! \brief Constructor. + + \param lock The BLocker that should be used by this report manager. +*/ KPPPReportManager::KPPPReportManager(BLocker& lock) : fLock(lock) { } +//! Deletes all report requests. KPPPReportManager::~KPPPReportManager() { for(int32 index = 0; index < fReportRequests.CountItems(); index++) @@ -24,6 +33,12 @@ KPPPReportManager::~KPPPReportManager() } +/*! \brief Requests report messages of a given \a type. + + \param type The type of report. + \param thread The receiver thread. + \param flags Optional report flags. See \c ppp_report_flags for more information. +*/ void KPPPReportManager::EnableReports(ppp_report_type type, thread_id thread, int32 flags = PPP_NO_FLAGS) @@ -42,6 +57,7 @@ KPPPReportManager::EnableReports(ppp_report_type type, thread_id thread, } +//! Removes a report request. void KPPPReportManager::DisableReports(ppp_report_type type, thread_id thread) { @@ -64,6 +80,7 @@ KPPPReportManager::DisableReports(ppp_report_type type, thread_id thread) } +//! Returns if we report messages of a given \a type to the given \a thread. bool KPPPReportManager::DoesReport(ppp_report_type type, thread_id thread) { @@ -85,6 +102,18 @@ KPPPReportManager::DoesReport(ppp_report_type type, thread_id thread) } +/*! \brief Send out report messages to all requestors. + + You may append additional data to the report messages. The data length may not be + greater than \c PPP_REPORT_DATA_LIMIT. + + \param type The report type. + \param code The report code belonging to the report type. + \param data Additional data. + \param length Length of the data. + + \return \c true if all receivers accepted the message or \c false otherwise. +*/ bool KPPPReportManager::Report(ppp_report_type type, int32 code, void *data, int32 length) { diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPStateMachine.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPStateMachine.cpp index 8a31b6207b..c89e50f0f0 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPStateMachine.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPStateMachine.cpp @@ -5,6 +5,14 @@ // Copyright (c) 2003-2004 Waldemar Kornewald, Waldemar.Kornewald@web.de //----------------------------------------------------------------------- +/*! \class KPPPStateMachine + \brief PPP state machine belonging to the LCP protocol + + The state machine is responsible for handling events and state changes. + + \sa KPPPLCP +*/ + #include #include @@ -23,6 +31,7 @@ static const bigtime_t kPPPStateMachineTimeout = 3000000; // 3 seconds +//! Constructor. KPPPStateMachine::KPPPStateMachine(KPPPInterface& interface) : fInterface(interface), fLCP(interface.LCP()), @@ -45,6 +54,7 @@ KPPPStateMachine::KPPPStateMachine(KPPPInterface& interface) } +//! Destructor. Frees loaded memory. KPPPStateMachine::~KPPPStateMachine() { free(fLocalAuthenticationName); @@ -52,6 +62,7 @@ KPPPStateMachine::~KPPPStateMachine() } +//! Creates an ID for the next LCP packet. uint8 KPPPStateMachine::NextID() { @@ -59,8 +70,11 @@ KPPPStateMachine::NextID() } -// remember: NewState() must always be called _after_ IllegalEvent() -// because IllegalEvent() also looks at the current state. +/*! \brief Changes the current state. + + Remember: NewState() must always be called \e after IllegalEvent() because + IllegalEvent() also looks at the current state. +*/ void KPPPStateMachine::NewState(ppp_state next) { @@ -79,6 +93,11 @@ KPPPStateMachine::NewState(ppp_state next) } +/*! \brief Changes the current phase. + + This method is responsible for setting the \c if_flags and sending the + \c PPP_REPORT_UP_SUCCESSFUL report message. +*/ void KPPPStateMachine::NewPhase(ppp_phase next) { @@ -120,6 +139,8 @@ KPPPStateMachine::NewPhase(ppp_phase next) // public actions + +//! Reconfigures the state machine. This initiates a new configure request handshake. bool KPPPStateMachine::Reconfigure() { @@ -146,6 +167,7 @@ KPPPStateMachine::Reconfigure() } +//! Sends an echo request packet. bool KPPPStateMachine::SendEchoRequest() { @@ -176,6 +198,7 @@ KPPPStateMachine::SendEchoRequest() } +//! Sends a discard request packet. bool KPPPStateMachine::SendDiscardRequest() { @@ -206,6 +229,11 @@ KPPPStateMachine::SendDiscardRequest() // authentication events + +/*! Notification that local authentication is requested. + + NOTE: This must be called \e after \c KPPPProtocol::Up(). +*/ void KPPPStateMachine::LocalAuthenticationRequested() { @@ -226,6 +254,12 @@ KPPPStateMachine::LocalAuthenticationRequested() } +/*! \brief Notification that local authentication was accepted. + + NOTE: This must be called \e before \c UpEvent(). + + \param name The username/login that was accepted. +*/ void KPPPStateMachine::LocalAuthenticationAccepted(const char *name) { @@ -249,6 +283,12 @@ KPPPStateMachine::LocalAuthenticationAccepted(const char *name) } +/*! \brief Notification that local authentication was denied. + + NOTE: This must be called \e before \c UpFailedEvent(). + + \param name The username/login that was denied. +*/ void KPPPStateMachine::LocalAuthenticationDenied(const char *name) { @@ -270,6 +310,7 @@ KPPPStateMachine::LocalAuthenticationDenied(const char *name) } +//! Notification that peer authentication is requested. void KPPPStateMachine::PeerAuthenticationRequested() { @@ -290,6 +331,12 @@ KPPPStateMachine::PeerAuthenticationRequested() } +/*! \brief Notification that peer authentication was accepted. + + NOTE: This must be called \e before \c UpEvent(). + + \param name The username/login that was accepted. +*/ void KPPPStateMachine::PeerAuthenticationAccepted(const char *name) { @@ -313,6 +360,12 @@ KPPPStateMachine::PeerAuthenticationAccepted(const char *name) } +/*! \brief Notification that peer authentication was denied. + + NOTE: This must be called \e before \c UpFailedEvent(). + + \param name The username/login that was denied. +*/ void KPPPStateMachine::PeerAuthenticationDenied(const char *name) { @@ -336,6 +389,7 @@ KPPPStateMachine::PeerAuthenticationDenied(const char *name) } +//! Notification that a child interface failed to go up. void KPPPStateMachine::UpFailedEvent(KPPPInterface& interface) { @@ -349,6 +403,7 @@ KPPPStateMachine::UpFailedEvent(KPPPInterface& interface) } +//! Notification that a child interface went up successfully. void KPPPStateMachine::UpEvent(KPPPInterface& interface) { @@ -379,6 +434,7 @@ KPPPStateMachine::UpEvent(KPPPInterface& interface) } +//! Notification that a child interface went down. void KPPPStateMachine::DownEvent(KPPPInterface& interface) { @@ -425,6 +481,11 @@ KPPPStateMachine::DownEvent(KPPPInterface& interface) } +/*! \brief Notification that a protocol failed to go up. + + NOTE FOR AUTHENTICATORS: This \e must be called \e after an authentication + notification method like \c LocalAuthenticationFailed(). +*/ void KPPPStateMachine::UpFailedEvent(KPPPProtocol *protocol) { @@ -450,6 +511,11 @@ KPPPStateMachine::UpFailedEvent(KPPPProtocol *protocol) } +/*! \brief Notification that a protocol went up successfully. + + NOTE FOR AUTHENTICATORS: This \e must be called \e after an authentication + notification method like \c LocalAuthenticationSuccessful(). +*/ void KPPPStateMachine::UpEvent(KPPPProtocol *protocol) { @@ -465,6 +531,11 @@ KPPPStateMachine::UpEvent(KPPPProtocol *protocol) } +/*! \brief Notification that a protocol went down. + + NOTE FOR AUTHENTICATORS: This \e must be called \e after an authentication + notification method like \c LocalAuthenticationFailed(). +*/ void KPPPStateMachine::DownEvent(KPPPProtocol *protocol) { @@ -475,11 +546,14 @@ KPPPStateMachine::DownEvent(KPPPProtocol *protocol) } -// This is called by the device to tell us that it entered establishment -// phase. We can use Device::Down() to abort establishment until UpEvent() -// is called. -// The return value says if we are waiting for an UpEvent(). If false is -// returned the device should immediately abort its attempt to connect. +/*! \brief Notification that the device entered establishment phase. + + We can use \c Device::Down() to abort establishment until \c UpEvent() is called. + + \return + - \c true: We are waiting for an \c UpEvent() + - \c false: The device should immediately abort its attempt to connect. +*/ bool KPPPStateMachine::TLSNotify() { @@ -501,10 +575,14 @@ KPPPStateMachine::TLSNotify() } -// This is called by the device to tell us that it entered termination phase. -// A Device::Up() should wait until the device went down. -// If false is returned we want to stay connected, though we called -// Device::Down(). +/*! \brief Notification that the device entered termination phase. + + A \c Device::Up() should wait until the device went down. + + \return + - \c true: Continue terminating. + - \c false: We want to stay connected, though we called \c Device::Down(). +*/ bool KPPPStateMachine::TLFNotify() { @@ -522,6 +600,7 @@ KPPPStateMachine::TLFNotify() } +//! Notification that the device failed to go up. void KPPPStateMachine::UpFailedEvent() { @@ -550,6 +629,7 @@ KPPPStateMachine::UpFailedEvent() } +//! Notification that the device went up successfully. void KPPPStateMachine::UpEvent() { @@ -615,6 +695,11 @@ KPPPStateMachine::UpEvent() } +/*! \brief Notification that the device went down. + + If this is called without a prior \c TLFNotify() the state machine will assume + that we lost our connection. +*/ void KPPPStateMachine::DownEvent() { diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPUtils.cpp b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPUtils.cpp index a9cc5f6d72..41f4c2d71b 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPUtils.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/KPPPUtils.cpp @@ -11,6 +11,7 @@ #include +//! Returns if this protocol is allowed to handle packets in the current state. bool IsProtocolAllowed(const KPPPProtocol& protocol) { @@ -27,9 +28,6 @@ IsProtocolAllowed(const KPPPProtocol& protocol) } -// These are very simple send/receive_data functions with a timeout -// and there is a race condition beween has_data() and send/receive_data(). -// Timeouts in ms. status_t send_data_with_timeout(thread_id thread, int32 code, void *buffer, size_t buffer_size, uint32 timeout) diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPDevice.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPDevice.h index 7ac6259067..9f2484fa77 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPDevice.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPDevice.h @@ -42,9 +42,9 @@ class KPPPDevice : public KPPPLayer { /*! \brief This brings the device up. - ATTENTION: This method must not block!\n + ATTENTION: This method must not block! \n Call UpStarted() to check if you are allowed to go down. After UpStarted() - is called the connection attempt may be aborted by calling Down().\n + is called the connection attempt may be aborted by calling Down(). \n In server mode you should listen for incoming connections. On error: \e Either call \c UpFailedEvent() and return \c true \e or return \c false only. \e Never call \c UpFailedEvent() and return @@ -56,7 +56,7 @@ class KPPPDevice : public KPPPLayer { virtual bool Up() = 0; /*! \brief Bring the interface down. - Call DownStarted() to check if you are allowed to go down.\n + Call DownStarted() to check if you are allowed to go down. \n The return value of this method is currently ignored. \sa DownStarted() @@ -77,13 +77,13 @@ class KPPPDevice : public KPPPLayer { /*! \brief Input speed in bytes per second. - The biggest of the two tranfer rates will be set in ifnet.\n + The biggest of the two tranfer rates will be set in ifnet. \n Should return default value when disconnected. */ virtual uint32 InputTransferRate() const = 0; /*! \brief Output speed in bytes per second. - The biggest of the two tranfer rates will be set in ifnet.\n + The biggest of the two tranfer rates will be set in ifnet. \n Should return default value when disconnected. */ virtual uint32 OutputTransferRate() const = 0; diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPInterface.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPInterface.h index 852628bceb..6bd69c456b 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPInterface.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPInterface.h @@ -172,7 +172,7 @@ class KPPPInterface : public KPPPLayer { { return fPFCOptions; } /*! \brief Local PFC state - Values defined in \c ppp_pfc_state.\n + Values defined in \c ppp_pfc_state. \n The local PFC state says if we accepted a request from the peer i.e.: we may use PFC in outgoing packets. */ @@ -180,7 +180,7 @@ class KPPPInterface : public KPPPLayer { { return fLocalPFCState; } /*! \brief Peer PFC state - Values defined in \c ppp_pfc_state.\n + Values defined in \c ppp_pfc_state. \n The peer PFC state says if the peer accepted a request us i.e.: the peer might send PFC-compressed packets to us */ diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPLCP.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPLCP.h index 4f3482bf65..cf30144766 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPLCP.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPLCP.h @@ -71,7 +71,7 @@ class KPPPLCP : public KPPPProtocol { /*! \brief Sets the target protocol handler for outgoing LCP packets. This may be used for filtering or routing LCP packets. Multilink - protocols might need this method.\n + protocols might need this method. \n If \a target != \c NULL all packets will be passed to the given protocol instead of the interface/device. */ diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPLCPExtension.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPLCPExtension.h index 4b1ecf4949..c9ae7d43a2 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPLCPExtension.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPLCPExtension.h @@ -37,10 +37,10 @@ class KPPPLCPExtension { driver_parameter *Settings() const { return fSettings; } - //! Enables or disables this handler. + //! Enables or disables this extension. void SetEnabled(bool enabled = true) { fEnabled = enabled; } - //! Returns if the handler is enabled. + //! Returns if the extension is enabled. bool IsEnabled() const { return fEnabled; } diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPManager.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPManager.h index 1db5b39258..c6f14dfbd3 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPManager.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPManager.h @@ -20,6 +20,7 @@ class KPPPInterface; +//! Private structure used by PPP interface manager. typedef struct ppp_interface_entry { KPPPInterface *interface; vint32 accessing; diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPOptionHandler.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPOptionHandler.h index 9fa5f562e9..1481399a77 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPOptionHandler.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPOptionHandler.h @@ -28,19 +28,25 @@ class KPPPOptionHandler { virtual status_t InitCheck() const; + //! Returns the name of this handler. const char *Name() const { return fName; } + //! Returns the LCP item type this object can handle. uint8 Type() const { return fType; } + //! Returns the owning interface. KPPPInterface& Interface() const { return fInterface; } + //! Returns the handler's settings. driver_parameter *Settings() const { return fSettings; } + //! Enables or disables this handler. void SetEnabled(bool enabled = true) { fEnabled = enabled; } + //! Returns if the handler is enabled. bool IsEnabled() const { return fEnabled; } @@ -51,24 +57,19 @@ class KPPPOptionHandler { virtual void ProfileChanged(); // we want to send a configure request or we received a reply - virtual status_t AddToRequest(KPPPConfigurePacket& request) = 0; - virtual status_t ParseNak(const KPPPConfigurePacket& nak) = 0; + virtual status_t AddToRequest(KPPPConfigurePacket& request); + virtual status_t ParseNak(const KPPPConfigurePacket& nak); // create next request based on these and previous values - virtual status_t ParseReject(const KPPPConfigurePacket& reject) = 0; + virtual status_t ParseReject(const KPPPConfigurePacket& reject); // create next request based on these and previous values - virtual status_t ParseAck(const KPPPConfigurePacket& ack) = 0; + virtual status_t ParseAck(const KPPPConfigurePacket& ack); // this is called for all handlers - // peer sent configure request virtual status_t ParseRequest(const KPPPConfigurePacket& request, - int32 index, KPPPConfigurePacket& nak, KPPPConfigurePacket& reject) = 0; - // index may be behind the last item which means additional values can be - // appended - virtual status_t SendingAck(const KPPPConfigurePacket& ack) = 0; - // notification that we ack these values + int32 index, KPPPConfigurePacket& nak, KPPPConfigurePacket& reject); + virtual status_t SendingAck(const KPPPConfigurePacket& ack); - virtual void Reset() = 0; - // e.g.: remove list of rejected values + virtual void Reset(); protected: status_t fInitStatus; diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPProtocol.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPProtocol.h index c5992109d2..98d4eb65d5 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPProtocol.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPProtocol.h @@ -29,39 +29,50 @@ class KPPPProtocol : public KPPPLayer { virtual void Uninit(); + //! Returns the interface that owns this protocol. KPPPInterface& Interface() const { return fInterface; } + //! Returns the protocol's settings. driver_parameter *Settings() const { return fSettings; } + //! The activation phase is the phase when Up() should be called. ppp_phase ActivationPhase() const { return fActivationPhase; } + //! The protocol number. uint16 ProtocolNumber() const { return fProtocolNumber; } + //! The address family. Negative values and values > 0xFF are ignored. int32 AddressFamily() const { return fAddressFamily; } - // negative values and values > 0xFF are ignored + //! This protocol's flags. int32 Flags() const { return fFlags; } + //! Which side this protocol works for. ppp_side Side() const { return fSide; } - // which side this protocol works for - + + //! Protocol type. May be NULL. const char *Type() const { return fType; } + //! The (optional) KPPPOptionHandler object of this protocol. KPPPOptionHandler *OptionHandler() const { return fOptionHandler; } + //! Sets the next protocol in the list. void SetNextProtocol(KPPPProtocol *protocol) { fNextProtocol = protocol; SetNext(protocol); } + //! Returns the next protocol in the list. KPPPProtocol *NextProtocol() const { return fNextProtocol; } void SetEnabled(bool enabled = true); + //! Returns whether this protocol is enabled. bool IsEnabled() const { return fEnabled; } + //! Returns whether an Up() is requested. bool IsUpRequested() const { return fUpRequested; } @@ -69,24 +80,39 @@ class KPPPProtocol : public KPPPLayer { virtual status_t StackControl(uint32 op, void *data); // called by netstack (forwarded by KPPPInterface) + /*! \brief Bring this protocol up. + + You must call \c UpStarted() from here. + */ virtual bool Up() = 0; + /*! \brief Bring this protocol down. + + You must call DownStarted() from here. \n + If DialOnDemand is supported check for DialOnDemand settings change. + */ virtual bool Down() = 0; - // if DialOnDemand is supported check for DialOnDemand settings change + //! Is this protocol up? bool IsUp() const { return fConnectionPhase == PPP_ESTABLISHED_PHASE; } + //! Is this protocol down? bool IsDown() const { return fConnectionPhase == PPP_DOWN_PHASE; } + //! Is this protocol going up? bool IsGoingUp() const { return fConnectionPhase == PPP_ESTABLISHMENT_PHASE; } + //! Is this protocol going down? bool IsGoingDown() const { return fConnectionPhase == PPP_TERMINATION_PHASE; } virtual bool IsAllowedToSend() const; + //! Encapsulate the packet with the given protocol number. virtual status_t Send(struct mbuf *packet, uint16 protocolNumber) = 0; + //! Receive a packet with the given protocol number. virtual status_t Receive(struct mbuf *packet, uint16 protocolNumber) = 0; protected: + //! \brief Requests Up() to be called. void SetUpRequested(bool requested = true) { fUpRequested = requested; } diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPReportManager.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPReportManager.h index b9ca4603a4..e392cb393b 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPReportManager.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPReportManager.h @@ -16,6 +16,7 @@ #include +//! Sends a reply to the report message sender. #define PPP_REPLY(sender, value) \ send_data_with_timeout((sender), (value), NULL, 0, PPP_REPORT_TIMEOUT) diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPStateMachine.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPStateMachine.h index 99881a48e5..d75aaa4163 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPStateMachine.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/KPPPStateMachine.h @@ -34,21 +34,26 @@ class KPPPStateMachine { KPPPStateMachine& operator= (const KPPPStateMachine& copy); public: + //! Returns the interface that owns this state machine. KPPPInterface& Interface() const { return fInterface; } + //! Returns the LCP protocol object belonging to this state machine. KPPPLCP& LCP() const { return fLCP; } + //! Returns the current state as defined in RFC 1661. ppp_state State() const { return fState; } + //! Returns the internal phase. ppp_phase Phase() const { return fPhase; } uint8 NextID(); - // return the next id for LCP packets + //! Sets our packets' magic number. Used by Link-Quality-Monitoring. void SetMagicNumber(uint32 magicNumber) { fMagicNumber = magicNumber; } + //! Returns our packets' magic number. uint32 MagicNumber() const { return fMagicNumber; } @@ -64,16 +69,20 @@ class KPPPStateMachine { void LocalAuthenticationRequested(); void LocalAuthenticationAccepted(const char *name); void LocalAuthenticationDenied(const char *name); + //! Returns the name/login string we used for authentication. const char *LocalAuthenticationName() const { return fLocalAuthenticationName; } + //! Returns our local authentication status. ppp_authentication_status LocalAuthenticationStatus() const { return fLocalAuthenticationStatus; } void PeerAuthenticationRequested(); void PeerAuthenticationAccepted(const char *name); void PeerAuthenticationDenied(const char *name); + //! Returns the name/login string the peer used for authentication. const char *PeerAuthenticationName() const { return fPeerAuthenticationName; } + //! Returns the peer's authentication status. ppp_authentication_status PeerAuthenticationStatus() const { return fPeerAuthenticationStatus; } diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/LockerHelper.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/LockerHelper.h index 545d9ed6a5..127033b2a4 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/LockerHelper.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/LockerHelper.h @@ -5,15 +5,13 @@ // Copyright (c) 2003-2004 Waldemar Kornewald, Waldemar.Kornewald@web.de //----------------------------------------------------------------------- -/* - * LockerHelper.h - * - * The LockerHelper acquires a lock on construction and releases it - * on destruction. - * This is a very useful class because you do not have to worry about - * releasing the lock at every possible point. It is done automatically. - * - */ +/*! \class LockerHelper + \brief Helper class for automatically releasing a lock. + + The LockerHelper acquires a lock on construction and releases it on destruction. + This is a very useful class because you do not have to worry about + releasing the lock at every possible point. It is done automatically. +*/ #ifndef _LOCKER_HELPER__H @@ -29,18 +27,28 @@ class LockerHelper { LockerHelper& operator= (const LockerHelper& copy); public: + //! Locks the given BLocker. LockerHelper(BLocker& lock) : fLock(&lock) { if(!fLock->Lock()) fLock = NULL; } + /*! \brief Unlocks the BLocker that was passed to the constructor. + + If you called \c UnlockNow() the BLocker will not be unlocked. + */ ~LockerHelper() { if(fLock) fLock->Unlock(); } + /*! \brief Unlocks the BLocker that was passed to the constructor. + + The destructor will not unlock the BLocker anymore and any subsequent + calls to \c UnlockNow() will do \e nothing. + */ void UnlockNow() { if(fLock) diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPControl.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPControl.h index 27e2341f72..120b18c887 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPControl.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPControl.h @@ -90,13 +90,13 @@ enum ppp_control_ops { //! Basic structure used for creating and searching PPP interfaces. typedef struct ppp_interface_description_info { + //! Different values for describing an interface. union { const driver_settings *settings; //!< Interface settings. const char *name; //!< Name of interface description file. } u; - //!< Different values for describing an interface. const driver_settings *profile; //!< An optional profile. If \a profile == NULL the default profile is used. ppp_interface_id interface; @@ -137,6 +137,7 @@ typedef struct ppp_control_info { // ----------------------------------------------------------- #define _PPP_INFO_T_SIZE_ 256 +//! Structure used by \c PPPC_GET_INTERFACE_INFO. typedef struct ppp_interface_info { char name[PPP_HANDLER_NAME_LENGTH_LIMIT + 1]; int32 if_unit; @@ -158,13 +159,17 @@ typedef struct ppp_interface_info { bool doesDialOnDemand, doesAutoRedial, hasDevice, isMultilink, hasParent; } ppp_interface_info; +/*! \brief You \e must use this encapsulator instead of \c ppp_interface_info! + + This structure guarantees backwards compatibility. +*/ typedef struct ppp_interface_info_t { ppp_interface_info info; uint8 _reserved_[_PPP_INFO_T_SIZE_ - sizeof(ppp_interface_info)]; } ppp_interface_info_t; -// devices are special handlers, so they have their own structure +//! Structure used by \c PPPC_GET_DEVICE_INFO. typedef struct ppp_device_info { char name[PPP_HANDLER_NAME_LENGTH_LIMIT + 1]; @@ -172,12 +177,17 @@ typedef struct ppp_device_info { uint32 inputTransferRate, outputTransferRate, outputBytesCount; bool isUp; } ppp_device_info; +/*! \brief You \e must use this encapsulator instead of \c ppp_device_info! + + This structure guarantees backwards compatibility. +*/ typedef struct ppp_device_info_t { ppp_device_info info; uint8 _reserved_[_PPP_INFO_T_SIZE_ - sizeof(ppp_device_info)]; } ppp_device_info_t; +//! Structure used by \c PPPC_GET_PROTOCOL_INFO. typedef struct ppp_protocol_info { char name[PPP_HANDLER_NAME_LENGTH_LIMIT + 1]; char type[PPP_HANDLER_NAME_LENGTH_LIMIT + 1]; @@ -199,12 +209,17 @@ typedef struct ppp_protocol_info { bool isEnabled; bool isUpRequested; } ppp_protocol_info; +/*! \brief You \e must use this encapsulator instead of \c ppp_protocol_info! + + This structure guarantees backwards compatibility. +*/ typedef struct ppp_protocol_info_t { ppp_protocol_info info; uint8 _reserved_[_PPP_INFO_T_SIZE_ - sizeof(ppp_protocol_info)]; } ppp_protocol_info_t; +//! Structure used by \c PPPC_GET_SIMPLE_HANDLER_INFO. typedef struct ppp_simple_handler_info { char name[PPP_HANDLER_NAME_LENGTH_LIMIT + 1]; @@ -213,6 +228,10 @@ typedef struct ppp_simple_handler_info { uint8 code; // only KPPPLCPExtension } ppp_simple_handler_info; +/*! \brief You \e must use this encapsulator instead of \c ppp_simple_handler_info! + + This structure guarantees backwards compatibility. +*/ typedef struct ppp_simple_handler_info_t { ppp_simple_handler_info info; uint8 _reserved_[_PPP_INFO_T_SIZE_ - sizeof(ppp_simple_handler_info)]; diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPDefs.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPDefs.h index d791530a23..6cf9bf9a43 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPDefs.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPDefs.h @@ -98,17 +98,21 @@ enum ppp_pfc_state { //!< PFC was rejected by other side. Not used for peer state. }; -// protocol flags -enum { +//! Protocol flags. +enum ppp_protocol_flags { PPP_NO_FLAGS = 0x00, + //!< No flags. PPP_ALWAYS_ALLOWED = 0x01, - // protocol may send/receive in Phase() >= PPP_ESTABLISHMENT_PHASE, - // but only LCP is allowed in State() != PPP_OPENED_STATE! + //!< Protocol may send/receive in Phase() >= PPP_ESTABLISHMENT_PHASE. + // But only LCP is allowed in State() != PPP_OPENED_STATE! PPP_NOT_IMPORTANT = 0x02, - // if this protocol fails to go up we do not disconnect - PPP_INCLUDES_NCP = 0x04, - // This protocol includes the corresponding NCP protocol (e.g.: IPCP + IP). - // All protocol values will also be checked against Protocol() & 0x7FFF. + //!< If this protocol fails to go up we do not disconnect. + + /*! \brief This protocol includes the corresponding NCP protocol (e.g.: IPCP + IP). + + All protocol values will also be checked against Protocol() & 0x7FFF. + */ + PPP_INCLUDES_NCP = 0x04 }; // phase when the protocol is brought up diff --git a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPReportDefs.h b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPReportDefs.h index e45b89b78a..0f82ea8994 100644 --- a/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPReportDefs.h +++ b/src/add-ons/kernel/network/ppp/shared/libkernelppp/headers/PPPReportDefs.h @@ -18,7 +18,7 @@ #define PPP_REPORT_CODE '_3PR' // the code of receive_data() must have this value -// report flags +//! Report flags. enum ppp_report_flags { PPP_WAIT_FOR_REPLY = 0x01, PPP_REMOVE_AFTER_REPORT = 0x02, @@ -64,15 +64,17 @@ enum ppp_connection_report_codes { }; +//! This is the structure of a report message. typedef struct ppp_report_packet { int32 type; int32 code; uint8 length; - // length of data + //!< Length of the additional data. char data[PPP_REPORT_DATA_LIMIT]; } ppp_report_packet; +//! Private structure used for storing report requests. typedef struct ppp_report_request { ppp_report_type type; thread_id thread; diff --git a/src/add-ons/kernel/network/ppp/shared/libppp/PPPInterface.cpp b/src/add-ons/kernel/network/ppp/shared/libppp/PPPInterface.cpp index 9fdba0aaea..6d367a85bb 100644 --- a/src/add-ons/kernel/network/ppp/shared/libppp/PPPInterface.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libppp/PPPInterface.cpp @@ -23,6 +23,10 @@ #include +/*! \brief Sets the interface to \a ID. + + \param ID The ID of the new interface. +*/ PPPInterface::PPPInterface(ppp_interface_id ID = PPP_UNDEFINED_INTERFACE_ID) { fFD = open(get_stack_driver_path(), O_RDWR); @@ -31,6 +35,7 @@ PPPInterface::PPPInterface(ppp_interface_id ID = PPP_UNDEFINED_INTERFACE_ID) } +//! Copy constructor. PPPInterface::PPPInterface(const PPPInterface& copy) { fFD = open(get_stack_driver_path(), O_RDWR); @@ -39,6 +44,7 @@ PPPInterface::PPPInterface(const PPPInterface& copy) } +//! Destructor. PPPInterface::~PPPInterface() { if(fFD >= 0) @@ -46,16 +52,43 @@ PPPInterface::~PPPInterface() } +/*! \brief Checks if object was created correctly. + + You should always call this method after you constructed a PPPInterface object. + + \return + - \c B_OK: Object could be initialized successfully and the interface exists. + - \c B_BAD_INDEX: The interface does not exist. + - \c B_ERROR: The PPP stack could not be loaded. +*/ status_t PPPInterface::InitCheck() const { - if(fFD < 0 || fID == PPP_UNDEFINED_INTERFACE_ID) + if(fFD < 0) return B_ERROR; + if(fID == PPP_UNDEFINED_INTERFACE_ID) + return B_BAD_INDEX; return B_OK; } +/*! \brief Changes the current interface. + + The interface's info structure is cached in this object. If you want to update + its values you must call \c SetTo() again or use \c Control() with an op of + \c PPPC_GET_INTERFACE_INFO.\n + If this fails it will set the interface's \a ID to \c PPP_UNDEFINED_INTERFACE_ID. + + \param ID The ID of the new interface. + + \return + - \c B_OK: Object could be initialized successfully and the interface exists. + - \c B_BAD_INDEX: The interface does not exist. + - any other value: The PPP stack could not be loaded. + + \sa Control() +*/ status_t PPPInterface::SetTo(ppp_interface_id ID) { @@ -74,11 +107,23 @@ PPPInterface::SetTo(ppp_interface_id ID) } +/*! \brief Use this method for accessing additional PPP features. + + \param op Any value of ppp_control_ops. + \param data Some ops require you to pass a structure or other data using this + argument. + \param length Make sure this value is correct (e.g.: size of structure). + + \return + - \c B_OK: Operation was successful. + - \c B_BAD_INDEX: The interface does not exist. + - any other value: The PPP stack could not be loaded. +*/ status_t PPPInterface::Control(uint32 op, void *data, size_t length) const { if(InitCheck() != B_OK) - return B_ERROR; + return InitCheck(); ppp_control_info control; control_net_module_args args; @@ -97,17 +142,35 @@ PPPInterface::Control(uint32 op, void *data, size_t length) const } +/*! \brief Find BEntry to the interface settings that this object represents. + + \param entry The entry gets stored in this argument. + + \return + - \c B_OK: The settings file was saved in \a entry. + - \c B_BAD_INDEX: The interface does not exist. + - \c B_BAD_VALUE: Either \a entry was \c NULL or the interface is anonymous. + - any other value: The interface could not be found. +*/ status_t PPPInterface::GetSettingsEntry(BEntry *entry) const { - if(InitCheck() != B_OK || !entry || strlen(Name()) == 0) - return B_ERROR; + if(InitCheck() != B_OK) + return InitCheck(); + else if(!entry || strlen(Name()) == 0) + return B_BAD_VALUE; BDirectory directory(PPP_INTERFACE_SETTINGS_PATH); return directory.FindEntry(Name(), entry, true); } +/*! \brief Get the cached ppp_interface_info_t structure. + + \param info The info structure is copied into this argument. + + \return \c true on success, \c false otherwise. +*/ bool PPPInterface::GetInterfaceInfo(ppp_interface_info_t *info) const { @@ -120,6 +183,7 @@ PPPInterface::GetInterfaceInfo(ppp_interface_info_t *info) const } +//! Compares interface's settings to given driver_settings structure. bool PPPInterface::HasSettings(const driver_settings *settings) const { @@ -134,6 +198,13 @@ PPPInterface::HasSettings(const driver_settings *settings) const } +/*! \brief Changes the current interface profile. + + You may change the interface's profile at any time. The changes take effect when + the interface connects. + + \param profile The new profile. +*/ void PPPInterface::SetProfile(const driver_settings *profile) const { @@ -144,6 +215,7 @@ PPPInterface::SetProfile(const driver_settings *profile) const } +//! Brings the interface up. bool PPPInterface::Up() const { @@ -161,6 +233,7 @@ PPPInterface::Up() const } +//! Brings the interface down which causes the deletion of the interface. bool PPPInterface::Down() const { @@ -178,6 +251,14 @@ PPPInterface::Down() const } +/*! \brief Requests report messages from the interface. + + \param type The type of report. + \param thread Receiver thread. + \param flags Optional flags. + + \return \c true on success \c false otherwise. +*/ bool PPPInterface::EnableReports(ppp_report_type type, thread_id thread, int32 flags = PPP_NO_FLAGS) const @@ -191,6 +272,13 @@ PPPInterface::EnableReports(ppp_report_type type, thread_id thread, } +/*! \brief Removes thread from list of report requestors of this interface. + + \param type The type of report. + \param thread Receiver thread. + + \return \c true on success \c false otherwise. +*/ bool PPPInterface::DisableReports(ppp_report_type type, thread_id thread) const { diff --git a/src/add-ons/kernel/network/ppp/shared/libppp/PPPInterfaceListener.cpp b/src/add-ons/kernel/network/ppp/shared/libppp/PPPInterfaceListener.cpp index 0eb95a23b6..d2a6bcd037 100644 --- a/src/add-ons/kernel/network/ppp/shared/libppp/PPPInterfaceListener.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libppp/PPPInterfaceListener.cpp @@ -5,6 +5,23 @@ // Copyright (c) 2003-2004 Waldemar Kornewald, Waldemar.Kornewald@web.de //----------------------------------------------------------------------- +/*! \class PPPInterfaceListener + \brief This class simplifies the process of monitoring PPP interfaces. + + PPPInterfaceListener converts all kernel report messages from the PPP stack + into BMessage objects and forwards them to the target BHandler.\n + In case the BLooper's message queue is full and does not respond after a timeout + period it sends the reply message to the PPP stack for you. Otherwise you must + do it yourself.\n + Of course you can use this class to watch for all interfaces. This includes + automatically adding newly created interfaces to the watch-list.\n + The following values are added to each BMessage as int32 values: + - "sender": the thread_id of the report sender (your reply target) + - "interface" (optional): the interface ID of the affected interface + - "type": the report type + - "code": the report code +*/ + #include "PPPInterfaceListener.h" #include "PPPInterface.h" @@ -20,6 +37,7 @@ static const uint32 kReportFlags = PPP_WAIT_FOR_REPLY | PPP_NO_REPLY_TIMEOUT static const int32 kCodeQuitReportThread = 'QUIT'; +//! Private class. class PPPInterfaceListenerThread { public: PPPInterfaceListenerThread(PPPInterfaceListener *listener) @@ -75,7 +93,8 @@ PPPInterfaceListenerThread::Run() // needed to tell compiler which version of SendMessage we want if(messenger.SendMessage(&message, noHandler, 100000) != B_OK) send_data(sender, B_OK, NULL, 0); - } + } else + send_data(sender, B_OK, NULL, 0); } return B_OK; @@ -96,6 +115,10 @@ report_thread(void *data) } +/*! \brief Constructs a new listener that sends report messages to \a target. + + \param target The target BHandler which should receive report messages. +*/ PPPInterfaceListener::PPPInterfaceListener(BHandler *target) : fTarget(target), fDoesWatch(false), @@ -105,6 +128,7 @@ PPPInterfaceListener::PPPInterfaceListener(BHandler *target) } +//! Copy constructor. PPPInterfaceListener::PPPInterfaceListener(const PPPInterfaceListener& copy) : fTarget(copy.Target()), fDoesWatch(false), @@ -114,6 +138,7 @@ PPPInterfaceListener::PPPInterfaceListener(const PPPInterfaceListener& copy) } +//! Removes all report message requests. PPPInterfaceListener::~PPPInterfaceListener() { // disable all report messages @@ -127,6 +152,15 @@ PPPInterfaceListener::~PPPInterfaceListener() } +/*! \brief Returns whether the listener was constructed correctly. + + \return + - \c B_OK: No errors. + - \c B_ERROR: Some not defined error occured (like missing PPP stack). + - any other value: see \c PPPManager::InitCheck() + + \sa PPPManager::InitCheck() +*/ status_t PPPInterfaceListener::InitCheck() const { @@ -137,6 +171,7 @@ PPPInterfaceListener::InitCheck() const } +//! Changes the target BHandler for the report messages (may be \c NULL). void PPPInterfaceListener::SetTarget(BHandler *target) { @@ -146,6 +181,14 @@ PPPInterfaceListener::SetTarget(BHandler *target) } +/*! \brief Changes the interface being monitored. + + This unregisters the old interface from the watch-list. + + \param ID The ID of the interface you want to watch. + + \return \c true on sucess, \c false on failure. +*/ bool PPPInterfaceListener::WatchInterface(ppp_interface_id ID) { @@ -166,6 +209,7 @@ PPPInterfaceListener::WatchInterface(ppp_interface_id ID) } +//! Enables mode for watching all interfaces. New interfaces are added automatically. void PPPInterfaceListener::WatchAllInterfaces() { @@ -192,6 +236,11 @@ PPPInterfaceListener::WatchAllInterfaces() } +/*! \brief Stops watching interfaces. + + Beware that this does not disable the PPP stack's own report messages (e.g.: new + interfaces that being created). +*/ void PPPInterfaceListener::StopWatchingInterfaces() { diff --git a/src/add-ons/kernel/network/ppp/shared/libppp/PPPManager.cpp b/src/add-ons/kernel/network/ppp/shared/libppp/PPPManager.cpp index f456fa724c..a1a3035266 100644 --- a/src/add-ons/kernel/network/ppp/shared/libppp/PPPManager.cpp +++ b/src/add-ons/kernel/network/ppp/shared/libppp/PPPManager.cpp @@ -5,6 +5,13 @@ // Copyright (c) 2003-2004 Waldemar Kornewald, Waldemar.Kornewald@web.de //----------------------------------------------------------------------- +/*! \class PPPManager + \brief Allows controlling the PPP stack. + + This class can be used for creating and deleting interfaces. It has methods for + requesting PPP stack report messages (e.g.: about newly created interfaces). +*/ + #include "PPPManager.h" #include "PPPInterface.h" @@ -16,12 +23,14 @@ #include "_libppputils.h" +//! Constructor. Does nothing special. PPPManager::PPPManager() { fFD = open(get_stack_driver_path(), O_RDWR); } +//! Destructor. PPPManager::~PPPManager() { if(fFD >= 0) @@ -29,6 +38,7 @@ PPPManager::~PPPManager() } +//! Returns \c B_OK if created successfully and \c B_ERROR otherwise. status_t PPPManager::InitCheck() const { @@ -39,6 +49,17 @@ PPPManager::InitCheck() const } +/*! \brief Offers an ioctl()-like interface to all functions of the PPP stack. + + \param op Any value of ppp_control_ops. + \param data Some ops require you to pass a structure or other data using this + argument. + \param length Make sure this value is correct (e.g.: size of structure). + + If you cannot find the method that fits your needs or if you want to have direct + access to the complete set of PPP functions you should use this method. All + other methods call \c Control(), i.e., they are wrappers around this method. +*/ status_t PPPManager::Control(uint32 op, void *data, size_t length) const { @@ -55,6 +76,25 @@ PPPManager::Control(uint32 op, void *data, size_t length) const } +/*! \brief Controls a specific PPP module. + + Use this method if you want to access a PPP module. The PPP stack will load it, + then call its \c control() function (if it is exported), and finally unload + the module. + + \param name The module name. + \param op The private control op. + \param data Some ops require you to pass a structure or other data using this + argument. + \param length Make sure this value is correct (e.g.: size of structure). + + \return + - \c B_NAME_NOT_FOUND: The module could not be found. + - \c B_ERROR: Some error occured. + - The module's return value. + + \sa ppp_module_info::control() +*/ status_t PPPManager::ControlModule(const char *name, uint32 op, void *data, size_t length) const @@ -71,6 +111,12 @@ PPPManager::ControlModule(const char *name, uint32 op, void *data, } +/*! \brief Creates a nameless interface with the given settings and profile. + + Please use \c CreateInterfaceWithName() instead of this method. + + \return the new interface's ID or \c PPP_UNDEFINED_INTERFACE_ID on failure. +*/ ppp_interface_id PPPManager::CreateInterface(const driver_settings *settings, const driver_settings *profile = NULL) const @@ -86,6 +132,21 @@ PPPManager::CreateInterface(const driver_settings *settings, } +/*! \brief Creates an interface with the given name and profile. + + Every PPP interface has a profile. By it looks if the pppidf/profile folder + contains a profile with the interface's name. Otherwise the interface's settings + become its profile. This has the advantage that you can put the profile and the + settings into the same file which simplifies your PPP configuration if you edit + your PPP interface definitions by hand. In this case PAP, for example, would + still find the username and password although you specify them in the same + parameter that loads the PAP module. + + \param name The PPP interface description file's name. + \param profile You may override the default profile. + + \return the new interface's ID or \c PPP_UNDEFINED_INTERFACE_ID on failure. +*/ ppp_interface_id PPPManager::CreateInterfaceWithName(const char *name, const driver_settings *profile = NULL) const @@ -101,6 +162,7 @@ PPPManager::CreateInterfaceWithName(const char *name, } +//! Deletes the interface with the given \a ID. bool PPPManager::DeleteInterface(ppp_interface_id ID) const { @@ -111,6 +173,21 @@ PPPManager::DeleteInterface(ppp_interface_id ID) const } +/*! \brief Returns all interface IDs matching a certain filter rule. + + ATTENTION: You are responsible for deleting (via \c delete) the returned data!\n + Use this if you want to iterate over all interfaces. It returns an array of all + interface IDs.\c + You can specify a filter rule that can be either of: + - \c PPP_REGISTERED_INTERFACES (default): Only visible interfaces. + - \c PPP_UNREGISTERED_INTERFACES: Only invisible interfaces. + - \c PPP_ALL_INTERFACES: All (visible and invisible) interfaces. + + \param count The number of IDs in the returned array is stored here. + \param filter The filter rule. + + \return an array of interface IDs or \c NULL on failure. +*/ ppp_interface_id* PPPManager::Interfaces(int32 *count, ppp_interface_filter filter = PPP_REGISTERED_INTERFACES) const @@ -143,6 +220,7 @@ PPPManager::Interfaces(int32 *count, } +//! Use \c Interfaces() instead of this method. int32 PPPManager::GetInterfaces(ppp_interface_id *interfaces, int32 count, ppp_interface_filter filter = PPP_REGISTERED_INTERFACES) const @@ -159,6 +237,7 @@ PPPManager::GetInterfaces(ppp_interface_id *interfaces, int32 count, } +//! Returns the ID of the interface with the given settings on success. ppp_interface_id PPPManager::InterfaceWithSettings(const driver_settings *settings) const { @@ -172,6 +251,7 @@ PPPManager::InterfaceWithSettings(const driver_settings *settings) const } +//! Returns the ID of the interface with the given if_unit (interface unit). ppp_interface_id PPPManager::InterfaceWithUnit(int32 if_unit) const { @@ -200,6 +280,7 @@ PPPManager::InterfaceWithUnit(int32 if_unit) const } +//! Returns the ID of the interface with the given name. ppp_interface_id PPPManager::InterfaceWithName(const char *name) const { @@ -238,6 +319,7 @@ PPPManager::InterfaceWithName(const char *name) const } +//! Returns the number of existing interfaces or a negative value on error. int32 PPPManager::CountInterfaces(ppp_interface_filter filter = PPP_REGISTERED_INTERFACES) const @@ -246,6 +328,14 @@ PPPManager::CountInterfaces(ppp_interface_filter filter = } +/*! \brief Requests report messages from the PPP stack. + + \param type The type of report. + \param thread Receiver thread. + \param flags Optional flags. + + \return \c true on success \c false otherwise. +*/ bool PPPManager::EnableReports(ppp_report_type type, thread_id thread, int32 flags = PPP_NO_FLAGS) const @@ -259,6 +349,13 @@ PPPManager::EnableReports(ppp_report_type type, thread_id thread, } +/*! \brief Removes thread from list of report requestors of this interface. + + \param type The type of report. + \param thread Receiver thread. + + \return \c true on success \c false otherwise. +*/ bool PPPManager::DisableReports(ppp_report_type type, thread_id thread) const { diff --git a/src/add-ons/kernel/network/ppp/shared/libppp/headers/PPPInterfaceListener.h b/src/add-ons/kernel/network/ppp/shared/libppp/headers/PPPInterfaceListener.h index f78dbe6c7c..ffd27361ef 100644 --- a/src/add-ons/kernel/network/ppp/shared/libppp/headers/PPPInterfaceListener.h +++ b/src/add-ons/kernel/network/ppp/shared/libppp/headers/PPPInterfaceListener.h @@ -15,7 +15,7 @@ class BHandler; #define PPP_REPORT_MESSAGE 'P3RM' - // the what field of report messages + //!< The what field of PPPInterfaceListener report messages. class PPPInterfaceListener { @@ -28,15 +28,19 @@ class PPPInterfaceListener { status_t InitCheck() const; + //! Returns the target BHandler for the report messages. BHandler *Target() const { return fTarget; } void SetTarget(BHandler *target); + //! Returns whether watching an interface. bool DoesWatch() const { return fDoesWatch; } + //! Returns which interface is being watched or \c PPP_UNDEFINED_INTERFACE_ID. ppp_interface_id WatchingInterface() const { return fWatchingInterface; } + //! Returns the internal PPPManager object used for accessing the PPP stack. const PPPManager& Manager() const { return fManager; } @@ -44,9 +48,9 @@ class PPPInterfaceListener { void WatchAllInterfaces(); void StopWatchingInterfaces(); + //! Just sets the target to the given listener's target. PPPInterfaceListener& operator= (const PPPInterfaceListener& copy) { SetTarget(copy.Target()); return *this; } - // all interface listeners have the same number of interfaces private: void Construct();