Annotation of embedaddon/libpdel/ppp/ppp_l2tp_ctrl.h, revision 1.1
1.1 ! misho 1:
! 2: /*
! 3: * Copyright (c) 2001-2002 Packet Design, LLC.
! 4: * All rights reserved.
! 5: *
! 6: * Subject to the following obligations and disclaimer of warranty,
! 7: * use and redistribution of this software, in source or object code
! 8: * forms, with or without modifications are expressly permitted by
! 9: * Packet Design; provided, however, that:
! 10: *
! 11: * (i) Any and all reproductions of the source or object code
! 12: * must include the copyright notice above and the following
! 13: * disclaimer of warranties; and
! 14: * (ii) No rights are granted, in any manner or form, to use
! 15: * Packet Design trademarks, including the mark "PACKET DESIGN"
! 16: * on advertising, endorsements, or otherwise except as such
! 17: * appears in the above copyright notice or in the software.
! 18: *
! 19: * THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
! 20: * TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
! 21: * REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
! 22: * THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
! 23: * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
! 24: * OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
! 25: * OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
! 26: * OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
! 27: * RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
! 28: * LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
! 29: * OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
! 30: * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
! 31: * DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
! 32: * USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
! 33: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
! 34: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
! 35: * THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
! 36: * THE POSSIBILITY OF SUCH DAMAGE.
! 37: *
! 38: * Author: Archie Cobbs <archie@freebsd.org>
! 39: */
! 40:
! 41: #ifndef _PPP_L2TP_PDEL_PPP_PPP_L2TP_CTRL_H_
! 42: #define _PPP_L2TP_PDEL_PPP_PPP_L2TP_CTRL_H_
! 43:
! 44: /*
! 45: * API between L2TP 'control' and 'link' code. The control code handles
! 46: * the L2TP control connection. The link code handles plumbing netgraph,
! 47: * and interfacing with the PPP engine.
! 48: *
! 49: * Each control connection is represented by a 'struct ppp_l2tp_ctrl',
! 50: * and each session by a 'struct ppp_l2tp_sess'. The link side may store
! 51: * its own opaque pointer in these structures as well.
! 52: *
! 53: * The functions and callbacks are designed so that whenever either side
! 54: * declares a control connection or session 'terminated', then the other
! 55: * side (whose function is being called) must not refer to that object
! 56: * any more.
! 57: *
! 58: * It is presumed that the 'link' side has a mutex which is held while
! 59: * calling any of the 'control' side functions, and which is acquired
! 60: * first when any 'link' side functions are invoked. In other words,
! 61: * the control side is not reentrant (though see 'ppp_l2tp_initiated_t'
! 62: * for an exception).
! 63: */
! 64:
! 65: struct ppp_l2tp_ctrl; /* control connection structure */
! 66: struct ppp_l2tp_sess; /* call session structure */
! 67:
! 68: /************************************************************************
! 69: CONTROL -> LINK CALLBACK FUNCTIONS
! 70: ************************************************************************/
! 71:
! 72: /*
! 73: * This is called when a control connection is terminated for any reason
! 74: * other than a call ppp_l2tp_ctrl_destroy().
! 75: *
! 76: * Arguments:
! 77: * ctrl Control connection
! 78: * result Result code (never zero)
! 79: * error Error code (if result == L2TP_RESULT_GENERAL, else zero)
! 80: * errmsg Error message string
! 81: */
! 82: typedef void ppp_l2tp_ctrl_terminated_t(struct ppp_l2tp_ctrl *ctrl,
! 83: u_int16_t result, u_int16_t error, const char *errmsg);
! 84:
! 85: /*
! 86: * This callback is used to report the peer's initiating a new incoming
! 87: * or outgoing call.
! 88: *
! 89: * In the case of an incoming call, when/if the call eventually connects,
! 90: * the ppp_l2tp_connected_t callback will be called by the control side.
! 91: *
! 92: * In the case of an outgoing call, the link side is responsible for calling
! 93: * ppp_l2tp_connected() when/if the call is connected.
! 94: *
! 95: * This callback may choose to call ppp_l2tp_terminate() (to deny the call)
! 96: * or ppp_l2tp_connected() (to accept it immediately if outgoing) before
! 97: * returning.
! 98: *
! 99: * The link side is expected to plumb the netgraph session hook at this time.
! 100: *
! 101: * Arguments:
! 102: * ctrl Associated control connection
! 103: * sess Session structure
! 104: * out Non-zero to indicate outgoing call
! 105: * avps AVP's contained in the associated Outgoing-Call-Request
! 106: * or Incoming-Call-Request control message.
! 107: */
! 108: typedef void ppp_l2tp_initiated_t(struct ppp_l2tp_ctrl *ctrl,
! 109: struct ppp_l2tp_sess *sess, int out,
! 110: const struct ppp_l2tp_avp_list *avps);
! 111:
! 112: /*
! 113: * This callback is used to report successful connection of a remotely
! 114: * initiated incoming call (see ppp_l2tp_initiated_t) or a locally initiated
! 115: * outgoing call (see ppp_l2tp_initiate()). That is, we are acting as
! 116: * the LNS for this session.
! 117: *
! 118: * Arguments:
! 119: * sess Session structure
! 120: * avps AVP's contained in the associated Outgoing-Call-Connected
! 121: * or Incoming-Call-Connected control message.
! 122: */
! 123: typedef void ppp_l2tp_connected_t(struct ppp_l2tp_sess *sess,
! 124: const struct ppp_l2tp_avp_list *avps);
! 125:
! 126: /*
! 127: * This callback is called when any call, whether successfully connected
! 128: * or not, is terminated for any reason other than explict termination
! 129: * from the link side (via a call to either ppp_l2tp_terminate() or
! 130: * ppp_l2tp_ctrl_destroy()).
! 131: *
! 132: * Arguments:
! 133: * sess Session structure
! 134: * result Result code (never zero)
! 135: * error Error code (if result == L2TP_RESULT_GENERAL, else zero)
! 136: * errmsg Error message string
! 137: */
! 138: typedef void ppp_l2tp_terminated_t(struct ppp_l2tp_sess *sess,
! 139: u_int16_t result, u_int16_t error, const char *errmsg);
! 140:
! 141: /*
! 142: * This callback is used when the remote side sends a Set-Link-Info
! 143: * message. It is optional and may be NULL if not required.
! 144: *
! 145: * Arguments:
! 146: * sess Session structure
! 147: * xmit LAC's send ACCM
! 148: * recv LAC's receive ACCM
! 149: */
! 150: typedef void ppp_l2tp_set_link_info_t(struct ppp_l2tp_sess *sess,
! 151: u_int32_t xmit, u_int32_t recv);
! 152:
! 153: /*
! 154: * This callback is used when the remote side sends a WAN-Error-Notify
! 155: * message. It is optional and may be NULL if not required.
! 156: *
! 157: * Arguments:
! 158: * sess Session structure
! 159: * crc CRC errors
! 160: * frame Framing errors
! 161: * overrun Hardware overrun errors
! 162: * buffer Buffer overrun errors
! 163: * timeout Timeout errors
! 164: * align Alignment errors
! 165: */
! 166: typedef void ppp_l2tp_wan_error_notify_t(struct ppp_l2tp_sess *sess,
! 167: u_int32_t crc, u_int32_t frame, u_int32_t overrun,
! 168: u_int32_t buffer, u_int32_t timeout, u_int32_t align);
! 169:
! 170: /* Callback structure provided by the link side */
! 171: struct ppp_l2tp_ctrl_cb {
! 172: ppp_l2tp_ctrl_terminated_t *ctrl_terminated;
! 173: ppp_l2tp_initiated_t *initiated;
! 174: ppp_l2tp_connected_t *connected;
! 175: ppp_l2tp_terminated_t *terminated;
! 176: ppp_l2tp_set_link_info_t *set_link_info;
! 177: ppp_l2tp_wan_error_notify_t *wan_error_notify;
! 178: };
! 179:
! 180: /************************************************************************
! 181: LINK -> CONTROL FUNCTIONS
! 182: ************************************************************************/
! 183:
! 184: __BEGIN_DECLS
! 185:
! 186: /*
! 187: * This function creates a new control connection. If successful, the
! 188: * control code will create a ng_l2tp(4) node and fill in *nodep and
! 189: * the 'hook' buffer. The link code must then connect this hook to the
! 190: * appropriate L2TP packet delivery node before the next context switch.
! 191: *
! 192: * The control code guarantees exactly one call in the future to the
! 193: * ppp_l2tp_ctrl_terminated_t callback unless ppp_l2tp_ctrl_destroy()
! 194: * is called first.
! 195: *
! 196: * Arguments:
! 197: * ctx Event context for use by control code
! 198: * mutex Mutex for operation
! 199: * cb Pointer to link callback functions
! 200: * log Where to log stuff (if successful, the log is consumed)
! 201: * peer_id Unique identifier for peer (used for tie-breakers)
! 202: * initiate Whether to send a SCCRQ or just wait for one
! 203: * nodep Pointer to netgraph node ID variable
! 204: * hook Buffer for hook on L2TP netgraph node (size >= NG_HOOKSIZ)
! 205: * avps List of AVP's to include in the associated
! 206: * Start-Control-Connection-Request or
! 207: * Start-Control-Connection-Reply control message.
! 208: * secret Shared secret (or NULL if none required)
! 209: * seclen Length of shared secret (if secret != NULL)
! 210: *
! 211: * Returns NULL if failure (errno is set), otherwise a pointer to an
! 212: * opaque control connection object.
! 213: */
! 214: extern struct ppp_l2tp_ctrl *ppp_l2tp_ctrl_create(struct pevent_ctx *ctx,
! 215: pthread_mutex_t *mutex,
! 216: const struct ppp_l2tp_ctrl_cb *cb, struct ppp_log *log,
! 217: int initiate, u_int32_t peer_id, ng_ID_t *nodep,
! 218: char *hook, const struct ppp_l2tp_avp_list *avps,
! 219: const void *secret, size_t seclen);
! 220:
! 221: /*
! 222: * Close a control connection gracefully.
! 223: *
! 224: * All active sessions will be terminated, and eventually
! 225: * ppp_l2tp_ctrl_terminated_t will be called, assuming no
! 226: * intervening call to ppp_l2tp_ctrl_destroy() has been made.
! 227: *
! 228: * Arguments:
! 229: * ctrl Control connection structure
! 230: * result Result code (never zero)
! 231: * error Error code (if result == L2TP_RESULT_GENERAL, else zero)
! 232: * errmsg Error message string
! 233: */
! 234: extern void ppp_l2tp_ctrl_shutdown(struct ppp_l2tp_ctrl *ctrl,
! 235: u_int16_t result, u_int16_t error, const char *errmsg);
! 236:
! 237: /*
! 238: * Immediately destroy a control connection and all associated sessions.
! 239: * This does *not* result in any callbacks to the link side for either
! 240: * active sessions (ppp_l2tp_terminated_t) or the control connection
! 241: * itself (ppp_l2tp_ctrl_terminated_t).
! 242: *
! 243: * Upon return, *ctrlp will be set to NULL.
! 244: *
! 245: * Arguments:
! 246: * ctrlp Pointer to the control connection descriptor pointer
! 247: */
! 248: extern void ppp_l2tp_ctrl_destroy(struct ppp_l2tp_ctrl **ctrlp);
! 249:
! 250: /*
! 251: * This function initiates a new session, either an as an incoming or
! 252: * outgoing call request to the peer.
! 253: *
! 254: * In the case of an incoming call, when/if the call eventually connects,
! 255: * ppp_l2tp_connected() must be called.
! 256: *
! 257: * In the case of an outgoing call, when/if the call eventually connects,
! 258: * the link's ppp_l2tp_connected_t callback will be invoked.
! 259: *
! 260: * The link side is expected to plumb the netgraph session hook at this time.
! 261: *
! 262: * Arguments:
! 263: * ctrl Control connection
! 264: * out Non-zero to indicate outgoing call
! 265: * avps List of AVP's to include in the associated
! 266: * Outgoing-Call-Request or Incoming-Call-Request
! 267: * control message.
! 268: *
! 269: * Returns:
! 270: * NULL Initiation failed, errno is set
! 271: * sess Session structure
! 272: */
! 273: extern struct ppp_l2tp_sess *ppp_l2tp_initiate(struct ppp_l2tp_ctrl *ctrl,
! 274: int out, const struct ppp_l2tp_avp_list *avps);
! 275:
! 276: /*
! 277: * This function is used to report successful connection of a remotely
! 278: * initiated outgoing call (see ppp_l2tp_initiated_t) or a locally initiated
! 279: * incoming call (see ppp_l2tp_initiate()). That is, we are acting as
! 280: * the LAC for this session.
! 281: *
! 282: * Note: if this function returns -1, no special action is required;
! 283: * the control side will close the connection gracefully as if
! 284: * ppp_l2tp_terminate() had been called.
! 285: *
! 286: * Arguments:
! 287: * sess Session structure
! 288: * avps List of AVP's to include in the associated
! 289: * Outgoing-Call-Connected or Incoming-Call-Connected
! 290: * control message.
! 291: *
! 292: * Returns:
! 293: * 0 Connection successful
! 294: * -1 Connection failed, errno is set
! 295: */
! 296: extern int ppp_l2tp_connected(struct ppp_l2tp_sess *sess,
! 297: const struct ppp_l2tp_avp_list *avps);
! 298:
! 299: /*
! 300: * This function terminates a session. The session may be in any state.
! 301: * The control code will *not* make any futher calls to link callbacks
! 302: * regarding this session, so the link should clean up any associated
! 303: * state.
! 304: *
! 305: * Arguments:
! 306: * sess Session structure
! 307: * result Result code (must not be zero)
! 308: * error Error code (if result == L2TP_RESULT_GENERAL, else zero)
! 309: * errmsg Error message string (optional; may be NULL)
! 310: */
! 311: extern void ppp_l2tp_terminate(struct ppp_l2tp_sess *sess,
! 312: u_int16_t result, u_int16_t error, const char *errmsg);
! 313:
! 314: /*
! 315: * Get or set the link side cookie corresponding to a control connection
! 316: * or a call session.
! 317: */
! 318: extern void *ppp_l2tp_ctrl_get_cookie(struct ppp_l2tp_ctrl *ctrl);
! 319: extern void ppp_l2tp_ctrl_set_cookie(struct ppp_l2tp_ctrl *ctrl,
! 320: void *cookie);
! 321: extern void *ppp_l2tp_sess_get_cookie(struct ppp_l2tp_sess *sess);
! 322: extern void ppp_l2tp_sess_set_cookie(struct ppp_l2tp_sess *sess,
! 323: void *cookie);
! 324:
! 325: /*
! 326: * Get the node ID and hook name for the hook that corresponds
! 327: * to a control connection's L2TP frames.
! 328: */
! 329: extern void ppp_l2tp_ctrl_get_hook(struct ppp_l2tp_ctrl *ctrl,
! 330: ng_ID_t *nodep, const char **hookp);
! 331:
! 332: /*
! 333: * Get the node ID and hook name for the hook that corresponds
! 334: * to a session's data packets.
! 335: */
! 336: extern void ppp_l2tp_sess_get_hook(struct ppp_l2tp_sess *sess,
! 337: ng_ID_t *nodep, const char **hookp);
! 338:
! 339: __END_DECLS
! 340:
! 341: #endif /* _PPP_L2TP_PDEL_PPP_PPP_L2TP_CTRL_H_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to ppp_l2tp_ctrl.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / ppp