]>
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 | * | |
12 | * Each protocol provides 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. | |
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 | * get_status - get instance status | |
114 | * @p: protocol instance | |
115 | * @buf: buffer to be filled with the status string | |
116 | * | |
117 | * This hook is called by the core if it wishes to obtain an brief one-line user friendly | |
118 | * representation of the status of the instance to be printed by the <cf/show protocols/ | |
119 | * command. | |
120 | */ | |
121 | void get_status(struct proto *p, byte *buf) | |
122 | { DUMMY; } | |
123 | ||
124 | /** | |
125 | * get_route_info - get route information | |
126 | * @e: a route entry | |
127 | * @buf: buffer to be filled with the resulting string | |
128 | * @attrs: extended attributes of the route | |
129 | * | |
130 | * This hook is called to fill the buffer @buf with a brief user friendly | |
131 | * representation of metrics of a route belonging to this protocol. | |
132 | */ | |
133 | void get_route_info(rte *e, byte *buf, ea_list *attrs) | |
134 | { DUMMY; } | |
135 | ||
136 | /** | |
137 | * get_attr - get attribute information | |
138 | * @a: an extended attribute | |
139 | * @buf: buffer to be filled with attribute information | |
140 | * | |
141 | * The get_attr() hook is called by the core to obtain a user friendly | |
142 | * representation of an extended route attribute. It can either leave | |
143 | * the whole conversion to the core (by returning %GA_UNKNOWN), fill | |
144 | * in only attribute name (and let the core format the attribute value | |
145 | * automatically according to the type field; by returning %GA_NAME) | |
146 | * or doing the whole conversion (used in case the value requires extra | |
147 | * care; return %GA_FULL). | |
148 | */ | |
149 | int get_attr(eattr *a, byte *buf) | |
150 | { DUMMY; } | |
151 | ||
152 | /** | |
153 | * if_notify - notify instance about interface changes | |
154 | * @p: protocol instance | |
155 | * @flags: interface change flags | |
156 | * @i: the interface in question | |
157 | * | |
158 | * This hook is called whenever any network interface changes its status. | |
159 | * The change is described by a combination of status bits (%IF_CHANGE_xxx) | |
160 | * in the @flags parameter. | |
161 | */ | |
162 | void if_notify(struct proto *p, unsigned flags, struct iface *i) | |
163 | { DUMMY; } | |
164 | ||
165 | /** | |
166 | * ifa_notify - notify instance about interface address changes | |
167 | * @p: protocol instance | |
168 | * @flags: address change flags | |
169 | * @a: the interface address | |
170 | * | |
171 | * This hook is called to notify the protocol instance about an interface | |
172 | * acquiring or losing one of its addresses. The change is described by | |
173 | * a combination of status bits (%IF_CHANGE_xxx) in the @flags parameter. | |
174 | */ | |
175 | void ifa_notify(struct proto *p, unsigned flags, struct ifa *a) | |
176 | { DUMMY; } | |
177 | ||
178 | /** | |
179 | * rt_notify - notify instance about routing table change | |
180 | * @p: protocol instance | |
181 | * @net: a network entry | |
182 | * @new: new optimal route for the network | |
183 | * @old: old optimal route for the network | |
184 | * @attrs: extended attributes associated with the @new entry | |
185 | * | |
186 | * The rt_notify() hook is called to inform the protocol instance about | |
187 | * changes in the routing table it's connected to, that is a route @old | |
188 | * belonging to network @net being replaced by a new route @new with | |
189 | * extended attributes @attrs. Either @new or @old or both can be %NULL | |
190 | * if the corresponding route doesn't exist. | |
191 | */ | |
192 | void rt_notify(struct proto *p, net *net, rte *new, rte *old, ea_list *attrs) | |
193 | { DUMMY; } | |
194 | ||
195 | /** | |
196 | * neigh_notify - notify instance about neighbor status change | |
197 | * @neigh: a neighbor cache entry | |
198 | * | |
199 | * The neigh_notify() hook is called by the neighbor cache whenever | |
200 | * a neighbor changes its state, that is it gets disconnected or a | |
201 | * sticky neighbor gets connected. | |
202 | */ | |
203 | void neigh_notify(neighbor *neigh) | |
204 | { DUMMY; } | |
205 | ||
206 | /** | |
207 | * make_tmp_attrs - convert embedded attributes to temporary ones | |
208 | * @e: route entry | |
209 | * @pool: linear pool to allocate attribute memory in | |
210 | * | |
211 | * This hook is called by the routing table functions if they need | |
212 | * to convert the protocol attributes embedded directly in the &rte | |
213 | * to temporary extended attributes in order to distribute them | |
214 | * to other protocols or to filters. make_tmp_attrs() creates | |
2e9b2421 | 215 | * an &ea_list in the linear pool @pool, fills it with values of the |
ddbcb927 MM |
216 | * temporary attributes and returns a pointer to it. |
217 | */ | |
218 | ea_list *make_tmp_attrs(rte *e, struct linpool *pool) | |
219 | { DUMMY; } | |
220 | ||
221 | /** | |
222 | * store_tmp_attrs - convert temporary attributes to embedded ones | |
223 | * @e: route entry | |
224 | * @attrs: temporary attributes to be converted | |
225 | * | |
226 | * This hook is an exact opposite of make_tmp_attrs() -- it takes | |
227 | * a list of extended attributes and converts them to attributes | |
228 | * embedded in the &rte corresponding to this protocol. | |
229 | * | |
230 | * You must be prepared for any of the attributes being missing | |
231 | * from the list and use default values instead. | |
232 | */ | |
233 | void store_tmp_attrs(rte *e, ea_list *attrs) | |
234 | { DUMMY; } | |
235 | ||
236 | /** | |
237 | * import_control - pre-filtering decisions on route import | |
238 | * @p: protocol instance the route is going to be imported to | |
239 | * @e: the route in question | |
240 | * @attrs: extended attributes of the route | |
241 | * @pool: linear pool for allocation of all temporary data | |
242 | * | |
243 | * The import_control() hook is called as the first step of a exporting | |
244 | * a route from a routing table to the protocol instance. It can modify | |
245 | * route attributes and force acceptance or rejection of the route regardless | |
246 | * of user-specified filters. See rte_announce() for a complete description | |
247 | * of the route distribution process. | |
248 | * | |
249 | * The standard use of this hook is to reject routes having originated | |
250 | * from the same instance and to set default values of the protocol's metrics. | |
251 | * | |
252 | * Result: -1 if the route has to be accepted, 1 if rejected and 0 if it | |
253 | * should be passed to the filters. | |
254 | */ | |
255 | int import_control(struct proto *p, rte **e, ea_list **attrs, struct linpool *pool) | |
256 | { DUMMY; } | |
257 | ||
258 | /** | |
259 | * rte_better - compare metrics of two routes | |
260 | * @new: the new route | |
261 | * @old: the original route | |
262 | * | |
263 | * This hook gets called when the routing table contains two routes | |
264 | * for the same network which have originated from different instances | |
265 | * of a single protocol and it wants to select which one is preferred | |
266 | * over the other one. Protocols usually decide according to route metrics. | |
267 | * | |
268 | * Result: 1 if @new is better (more preferred) than @old, 0 otherwise. | |
269 | */ | |
270 | int rte_better(rte *new, rte *old) | |
271 | { DUMMY; } | |
272 | ||
273 | /** | |
274 | * rte_same - compare two routes | |
275 | * @e1: route | |
276 | * @e2: route | |
277 | * | |
278 | * The rte_same() hook tests whether the routes @e1 and @e2 belonging | |
279 | * to the same protocol instance have identical contents. Contents of | |
280 | * &rta, all the extended attributes and &rte preference are checked | |
281 | * by the core code, no need to take care of them here. | |
282 | * | |
283 | * Result: 1 if @e1 is identical to @e2, 0 otherwise. | |
284 | */ | |
285 | int rte_same(rte *e1, rte *e2) | |
286 | { DUMMY; } | |
287 | ||
288 | /** | |
289 | * rte_insert - notify instance about route insertion | |
290 | * @n: network | |
291 | * @e: route | |
292 | * | |
293 | * This hook is called whenever a &rte belonging to the instance | |
294 | * is accepted for insertion to a routing table. | |
295 | * | |
296 | * Please avoid using this function in new protocols. | |
297 | */ | |
298 | void rte_insert(net *n, rte *e) | |
299 | { DUMMY; } | |
300 | ||
301 | /** | |
302 | * rte_remove - notify instance about route removal | |
303 | * @n: network | |
304 | * @e: route | |
305 | * | |
306 | * This hook is called whenever a &rte belonging to the instance | |
307 | * is removed from a routing table. | |
308 | * | |
309 | * Please avoid using this function in new protocols. | |
310 | */ | |
311 | void rte_remove(net *n, rte *e) | |
312 | { DUMMY; } |