nest/proto-hooks.c

   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; }