]>
Commit | Line | Data |
---|---|---|
ddbcb927 MM |
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 | * | |
58f7d004 | 12 | * Each protocol can provide a rich set of hook functions referred to by pointers |
ddbcb927 MM |
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 | |
c0adf7e9 | 93 | * the instance. Multitable protocols should lock their tables here. |
ddbcb927 MM |
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 | ||
c0adf7e9 OZ |
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 | ||
ddbcb927 MM |
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 | |
8e433d6a | 151 | * @buflen: a length of the @buf parameter |
ddbcb927 MM |
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 | */ | |
aebe06b4 | 161 | int get_attr(eattr *a, byte *buf, int buflen) |
ddbcb927 MM |
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 | |
dca75fd7 | 193 | * @table: a routing table |
ddbcb927 | 194 | * @net: a network entry |
f98e2915 OZ |
195 | * @new: new route for the network |
196 | * @old: old route for the network | |
ddbcb927 MM |
197 | * @attrs: extended attributes associated with the @new entry |
198 | * | |
199 | * The rt_notify() hook is called to inform the protocol instance about | |
dca75fd7 | 200 | * changes in the connected routing table @table, that is a route @old |
ddbcb927 MM |
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. | |
23ac9e9a | 204 | * |
f98e2915 OZ |
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. | |
ddbcb927 MM |
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 | |
2e9b2421 | 239 | * an &ea_list in the linear pool @pool, fills it with values of the |
ddbcb927 MM |
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 | * | |
93e868c7 | 276 | * Result: 1 if the route has to be accepted, -1 if rejected and 0 if it |
ddbcb927 MM |
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 | ||
be4cd99a OZ |
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 | ||
ddbcb927 MM |
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; } |