Statistics
| Branch: | Revision:

iof-bird / bird-2.0.1 / nest / proto-hooks.c @ 6b3f1a54

History | View | Annotate | Download (11.2 KB)

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
 * @channel: notifying channel
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; }