1: /*
2: * BIRD -- Documentation for Protocol Hooks (dummy source file)
3: *
4: * (c) 2000 Martin Mares <mj@ucw.cz>
5: *
6: * Can be freely distributed and used under the terms of the GNU GPL.
7: */
8:
9: /**
10: * DOC: Protocol hooks
11: *
12: * Each protocol can provide a rich set of hook functions referred to by pointers
13: * in either the &proto or &protocol structure. They are called by the core whenever
14: * it wants the protocol to perform some action or to notify the protocol about
15: * any change of its environment. All of the hooks can be set to %NULL which means
16: * to ignore the change or to take a default action.
17: */
18:
19: /**
20: * preconfig - protocol preconfiguration
21: * @p: a routing protocol
22: * @c: new configuration
23: *
24: * The preconfig() hook is called before parsing of a new configuration.
25: */
26: void preconfig(struct protocol *p, struct config *c)
27: { DUMMY; }
28:
29: /**
30: * postconfig - instance post-configuration
31: * @c: instance configuration
32: *
33: * The postconfig() hook is called for each configured instance after
34: * parsing of the new configuration is finished.
35: */
36: void postconfig(struct proto_config *c)
37: { DUMMY; }
38:
39: /**
40: * init - initialize an instance
41: * @c: instance configuration
42: *
43: * The init() hook is called by the core to create a protocol instance
44: * according to supplied protocol configuration.
45: *
46: * Result: a pointer to the instance created
47: */
48: struct proto *init(struct proto_config *c)
49: { DUMMY; }
50:
51: /**
52: * reconfigure - request instance reconfiguration
53: * @p: an instance
54: * @c: new configuration
55: *
56: * The core calls the reconfigure() hook whenever it wants to ask the
57: * protocol for switching to a new configuration. If the reconfiguration
58: * is possible, the hook returns 1. Otherwise, it returns 0 and the core
59: * will shut down the instance and start a new one with the new configuration.
60: *
61: * After the protocol confirms reconfiguration, it must no longer keep any
62: * references to the old configuration since the memory it's stored in can
63: * be re-used at any time.
64: */
65: int reconfigure(struct proto *p, struct proto_config *c)
66: { DUMMY; }
67:
68: /**
69: * dump - dump protocol state
70: * @p: an instance
71: *
72: * This hook dumps the complete state of the instance to the
73: * debug output.
74: */
75: void dump(struct proto *p)
76: { DUMMY; }
77:
78: /**
79: * dump_attrs - dump protocol-dependent attributes
80: * @e: a route entry
81: *
82: * This hook dumps all attributes in the &rte which belong to this
83: * protocol to the debug output.
84: */
85: void dump_attrs(rte *e)
86: { DUMMY; }
87:
88: /**
89: * start - request instance startup
90: * @p: protocol instance
91: *
92: * The start() hook is called by the core when it wishes to start
93: * the instance. Multitable protocols should lock their tables here.
94: *
95: * Result: new protocol state
96: */
97: int start(struct proto *p)
98: { DUMMY; }
99:
100: /**
101: * shutdown - request instance shutdown
102: * @p: protocol instance
103: *
104: * The stop() hook is called by the core when it wishes to shut
105: * the instance down for some reason.
106: *
107: * Returns: new protocol state
108: */
109: int shutdown(struct proto *p)
110: { DUMMY; }
111:
112: /**
113: * cleanup - request instance cleanup
114: * @p: protocol instance
115: *
116: * The cleanup() hook is called by the core when the protocol became
117: * hungry/down, i.e. all protocol ahooks and routes are flushed.
118: * Multitable protocols should unlock their tables here.
119: */
120: void cleanup(struct proto *p)
121: { DUMMY; }
122:
123: /**
124: * get_status - get instance status
125: * @p: protocol instance
126: * @buf: buffer to be filled with the status string
127: *
128: * This hook is called by the core if it wishes to obtain an brief one-line user friendly
129: * representation of the status of the instance to be printed by the <cf/show protocols/
130: * command.
131: */
132: void get_status(struct proto *p, byte *buf)
133: { DUMMY; }
134:
135: /**
136: * get_route_info - get route information
137: * @e: a route entry
138: * @buf: buffer to be filled with the resulting string
139: * @attrs: extended attributes of the route
140: *
141: * This hook is called to fill the buffer @buf with a brief user friendly
142: * representation of metrics of a route belonging to this protocol.
143: */
144: void get_route_info(rte *e, byte *buf, ea_list *attrs)
145: { DUMMY; }
146:
147: /**
148: * get_attr - get attribute information
149: * @a: an extended attribute
150: * @buf: buffer to be filled with attribute information
151: * @buflen: a length of the @buf parameter
152: *
153: * The get_attr() hook is called by the core to obtain a user friendly
154: * representation of an extended route attribute. It can either leave
155: * the whole conversion to the core (by returning %GA_UNKNOWN), fill
156: * in only attribute name (and let the core format the attribute value
157: * automatically according to the type field; by returning %GA_NAME)
158: * or doing the whole conversion (used in case the value requires extra
159: * care; return %GA_FULL).
160: */
161: int get_attr(eattr *a, byte *buf, int buflen)
162: { DUMMY; }
163:
164: /**
165: * if_notify - notify instance about interface changes
166: * @p: protocol instance
167: * @flags: interface change flags
168: * @i: the interface in question
169: *
170: * This hook is called whenever any network interface changes its status.
171: * The change is described by a combination of status bits (%IF_CHANGE_xxx)
172: * in the @flags parameter.
173: */
174: void if_notify(struct proto *p, unsigned flags, struct iface *i)
175: { DUMMY; }
176:
177: /**
178: * ifa_notify - notify instance about interface address changes
179: * @p: protocol instance
180: * @flags: address change flags
181: * @a: the interface address
182: *
183: * This hook is called to notify the protocol instance about an interface
184: * acquiring or losing one of its addresses. The change is described by
185: * a combination of status bits (%IF_CHANGE_xxx) in the @flags parameter.
186: */
187: void ifa_notify(struct proto *p, unsigned flags, struct ifa *a)
188: { DUMMY; }
189:
190: /**
191: * rt_notify - notify instance about routing table change
192: * @p: protocol instance
193: * @table: a routing table
194: * @net: a network entry
195: * @new: new route for the network
196: * @old: old route for the network
197: * @attrs: extended attributes associated with the @new entry
198: *
199: * The rt_notify() hook is called to inform the protocol instance about
200: * changes in the connected routing table @table, that is a route @old
201: * belonging to network @net being replaced by a new route @new with
202: * extended attributes @attrs. Either @new or @old or both can be %NULL
203: * if the corresponding route doesn't exist.
204: *
205: * If the type of route announcement is RA_OPTIMAL, it is an
206: * announcement of optimal route change, @new stores the new optimal
207: * route and @old stores the old optimal route.
208: *
209: * If the type of route announcement is RA_ANY, it is an announcement
210: * of any route change, @new stores the new route and @old stores the
211: * old route from the same protocol.
212: *
213: * @p->accept_ra_types specifies which kind of route announcements
214: * protocol wants to receive.
215: */
216: void rt_notify(struct proto *p, net *net, rte *new, rte *old, ea_list *attrs)
217: { DUMMY; }
218:
219: /**
220: * neigh_notify - notify instance about neighbor status change
221: * @neigh: a neighbor cache entry
222: *
223: * The neigh_notify() hook is called by the neighbor cache whenever
224: * a neighbor changes its state, that is it gets disconnected or a
225: * sticky neighbor gets connected.
226: */
227: void neigh_notify(neighbor *neigh)
228: { DUMMY; }
229:
230: /**
231: * make_tmp_attrs - convert embedded attributes to temporary ones
232: * @e: route entry
233: * @pool: linear pool to allocate attribute memory in
234: *
235: * This hook is called by the routing table functions if they need
236: * to convert the protocol attributes embedded directly in the &rte
237: * to temporary extended attributes in order to distribute them
238: * to other protocols or to filters. make_tmp_attrs() creates
239: * an &ea_list in the linear pool @pool, fills it with values of the
240: * temporary attributes and returns a pointer to it.
241: */
242: ea_list *make_tmp_attrs(rte *e, struct linpool *pool)
243: { DUMMY; }
244:
245: /**
246: * store_tmp_attrs - convert temporary attributes to embedded ones
247: * @e: route entry
248: * @attrs: temporary attributes to be converted
249: *
250: * This hook is an exact opposite of make_tmp_attrs() -- it takes
251: * a list of extended attributes and converts them to attributes
252: * embedded in the &rte corresponding to this protocol.
253: *
254: * You must be prepared for any of the attributes being missing
255: * from the list and use default values instead.
256: */
257: void store_tmp_attrs(rte *e, ea_list *attrs)
258: { DUMMY; }
259:
260: /**
261: * import_control - pre-filtering decisions on route import
262: * @p: protocol instance the route is going to be imported to
263: * @e: the route in question
264: * @attrs: extended attributes of the route
265: * @pool: linear pool for allocation of all temporary data
266: *
267: * The import_control() hook is called as the first step of a exporting
268: * a route from a routing table to the protocol instance. It can modify
269: * route attributes and force acceptance or rejection of the route regardless
270: * of user-specified filters. See rte_announce() for a complete description
271: * of the route distribution process.
272: *
273: * The standard use of this hook is to reject routes having originated
274: * from the same instance and to set default values of the protocol's metrics.
275: *
276: * Result: 1 if the route has to be accepted, -1 if rejected and 0 if it
277: * should be passed to the filters.
278: */
279: int import_control(struct proto *p, rte **e, ea_list **attrs, struct linpool *pool)
280: { DUMMY; }
281:
282: /**
283: * rte_recalculate - prepare routes for comparison
284: * @table: a routing table
285: * @net: a network entry
286: * @new: new route for the network
287: * @old: old route for the network
288: * @old_best: old best route for the network (may be NULL)
289: *
290: * This hook is called when a route change (from @old to @new for a
291: * @net entry) is propagated to a @table. It may be used to prepare
292: * routes for comparison by rte_better() in the best route
293: * selection. @new may or may not be in @net->routes list,
294: * @old is not there.
295: *
296: * Result: 1 if the ordering implied by rte_better() changes enough
297: * that full best route calculation have to be done, 0 otherwise.
298: */
299: int rte_recalculate(struct rtable *table, struct network *net, struct rte *new, struct rte *old, struct rte *old_best)
300: { DUMMY; }
301:
302: /**
303: * rte_better - compare metrics of two routes
304: * @new: the new route
305: * @old: the original route
306: *
307: * This hook gets called when the routing table contains two routes
308: * for the same network which have originated from different instances
309: * of a single protocol and it wants to select which one is preferred
310: * over the other one. Protocols usually decide according to route metrics.
311: *
312: * Result: 1 if @new is better (more preferred) than @old, 0 otherwise.
313: */
314: int rte_better(rte *new, rte *old)
315: { DUMMY; }
316:
317: /**
318: * rte_same - compare two routes
319: * @e1: route
320: * @e2: route
321: *
322: * The rte_same() hook tests whether the routes @e1 and @e2 belonging
323: * to the same protocol instance have identical contents. Contents of
324: * &rta, all the extended attributes and &rte preference are checked
325: * by the core code, no need to take care of them here.
326: *
327: * Result: 1 if @e1 is identical to @e2, 0 otherwise.
328: */
329: int rte_same(rte *e1, rte *e2)
330: { DUMMY; }
331:
332: /**
333: * rte_insert - notify instance about route insertion
334: * @n: network
335: * @e: route
336: *
337: * This hook is called whenever a &rte belonging to the instance
338: * is accepted for insertion to a routing table.
339: *
340: * Please avoid using this function in new protocols.
341: */
342: void rte_insert(net *n, rte *e)
343: { DUMMY; }
344:
345: /**
346: * rte_remove - notify instance about route removal
347: * @n: network
348: * @e: route
349: *
350: * This hook is called whenever a &rte belonging to the instance
351: * is removed from a routing table.
352: *
353: * Please avoid using this function in new protocols.
354: */
355: void rte_remove(net *n, rte *e)
356: { DUMMY; }
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to proto-hooks.c CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / nest