Annotation of embedaddon/libpdel/ppp/ppp_l2tp_ctrl.h, revision 1.1.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