improved PPP API header documentation

This commit is contained in:
Sylvain Rochet 2012-07-07 15:05:15 +02:00
parent be9b23a082
commit 572e457e77
2 changed files with 23 additions and 23 deletions

View File

@ -317,16 +317,6 @@ void ppp_set_auth(ppp_pcb *pcb, u8_t authtype, char *user, char *passwd) {
} }
#if PPPOS_SUPPORT #if PPPOS_SUPPORT
/** Open a new PPP connection using the given I/O device.
* This initializes the PPP control block but does not
* attempt to negotiate the LCP session. If this port
* connects to a modem, the modem connection must be
* established before calling this.
* Return a new PPP connection descriptor on success or
* an error code (negative) on failure.
*
* pppOpen() is directly defined to this function.
*/
int ppp_over_serial_open(ppp_pcb *pcb, sio_fd_t fd, ppp_link_status_cb_fn link_status_cb, void *link_status_ctx) { int ppp_over_serial_open(ppp_pcb *pcb, sio_fd_t fd, ppp_link_status_cb_fn link_status_cb, void *link_status_ctx) {
/* PPP is single-threaded: without a callback, /* PPP is single-threaded: without a callback,

View File

@ -392,15 +392,26 @@ struct ppp_pcb_s {
*** PUBLIC FUNCTIONS *** *** PUBLIC FUNCTIONS ***
************************/ ************************/
/* Initialize the PPP subsystem. */ /*
* Initialize the PPP subsystem.
*/
int ppp_init(void); int ppp_init(void);
/* Create a new PPP session, returns a PPP PCB structure. */ /*
* Create a new PPP session.
*
* This initializes the PPP control block but does not
* attempt to negotiate the LCP session.
*
* Return a new PPP connection control block pointer
* on success or a null pointer on failure.
*/
ppp_pcb *ppp_new(void); ppp_pcb *ppp_new(void);
/* Set auth helper, optional, you can either fill ppp_pcb->settings. */ /*
* Set auth helper, optional, you can either fill ppp_pcb->settings.
/* Warning: Using PPPAUTHTYPE_ANY might have security consequences. *
* Warning: Using PPPAUTHTYPE_ANY might have security consequences.
* RFC 1994 says: * RFC 1994 says:
* *
* In practice, within or associated with each PPP server, there is a * In practice, within or associated with each PPP server, there is a
@ -433,36 +444,35 @@ typedef void (*ppp_link_status_cb_fn)(ppp_pcb *pcb, int err_code, void *ctx);
#if PPPOS_SUPPORT #if PPPOS_SUPPORT
/* /*
* Open a new PPP connection using the given serial I/O device. * Start a new PPP connection using the given serial I/O device.
* This initializes the PPP control block but does not
* attempt to negotiate the LCP session.
* *
* If this port connects to a modem, the modem connection must be * If this port connects to a modem, the modem connection must be
* established before calling this. * established before calling this.
* *
* Return a new PPP connection descriptor on success or * Return 0 on success, an error code on failure.
* an error code (negative) on failure.
*/ */
int ppp_over_serial_open(ppp_pcb *pcb, sio_fd_t fd, ppp_link_status_cb_fn link_status_cb, void *link_status_ctx); int ppp_over_serial_open(ppp_pcb *pcb, sio_fd_t fd, ppp_link_status_cb_fn link_status_cb, void *link_status_ctx);
#endif /* PPPOS_SUPPORT */ #endif /* PPPOS_SUPPORT */
#if PPPOE_SUPPORT #if PPPOE_SUPPORT
/* /*
* Open a new PPP Over Ethernet (PPPoE) connection. * Start a new PPP Over Ethernet (PPPoE) connection.
*
* Return 0 on success, an error code on failure.
*/ */
int ppp_over_ethernet_open(ppp_pcb *pcb, struct netif *ethif, const char *service_name, const char *concentrator_name, int ppp_over_ethernet_open(ppp_pcb *pcb, struct netif *ethif, const char *service_name, const char *concentrator_name,
ppp_link_status_cb_fn link_status_cb, void *link_status_ctx); ppp_link_status_cb_fn link_status_cb, void *link_status_ctx);
#endif /* PPPOE_SUPPORT */ #endif /* PPPOE_SUPPORT */
/* /*
* Close a PPP connection and release the descriptor. * Close a PPP connection and release the control block.
* Any outstanding packets in the queues are dropped. * Any outstanding packets in the queues are dropped.
* Return 0 on success, an error code on failure. * Return 0 on success, an error code on failure.
*/ */
int ppp_close(ppp_pcb *pcb); int ppp_close(ppp_pcb *pcb);
/* /*
* Indicate to the PPP process that the line has disconnected. * Indicate to the PPP stack that the line has disconnected.
*/ */
void ppp_sighup(ppp_pcb *pcb); void ppp_sighup(ppp_pcb *pcb);