From: Marcin Siodelski Date: Tue, 7 Jul 2015 11:36:47 +0000 (+0200) Subject: [3484] Updated description of hooks for DHCPv4 and DHCPv6 server. X-Git-Tag: trac4006_base~25^2~12 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0fcceb6b27168842fa04b51f5455239c3ebd4c1e;p=thirdparty%2Fkea.git [3484] Updated description of hooks for DHCPv4 and DHCPv6 server. --- diff --git a/src/bin/dhcp4/dhcp4_hooks.dox b/src/bin/dhcp4/dhcp4_hooks.dox index 4cd6e42b59..1cf6310d22 100644 --- a/src/bin/dhcp4/dhcp4_hooks.dox +++ b/src/bin/dhcp4/dhcp4_hooks.dox @@ -1,4 +1,4 @@ -// Copyright (C) 2013 Internet Systems Consortium, Inc. ("ISC") +// Copyright (C) 2013-2015 Internet Systems Consortium, Inc. ("ISC") // // Permission to use, copy, modify, and/or distribute this software for any // purpose with or without fee is hereby granted, provided that the above @@ -22,7 +22,7 @@ the @ref hooksdgDevelopersGuide. Information for Kea maintainers can be found in the @ref hooksComponentDeveloperGuide. - This manual is more specialised and is aimed at developers of hook + This manual is more specialized and is aimed at developers of hook code for the DHCPv4 server. It describes each hook point, what the callouts attached to the hook are able to do, and the arguments passed to the callouts. Each entry in this manual has the following information: @@ -54,23 +54,25 @@ packet processing. Hook points that are not specific to packet processing - @b Arguments: - name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: in/out - - @b Description: this callout is executed when an incoming DHCPv4 - buffer is received, before its content is parsed. The sole argument - - query4 - contains a pointer to an isc::dhcp::Pkt4 object that - contains raw information regarding incoming packet, including its - source and destination addresses, interface over which it was - received, and a raw buffer stored in data_ field. None of the - packet fields (op_, hlen_, chaddr_, etc.) are set yet. Callouts - installed on this hook point can modify the incoming buffer. The - server will parse the buffer afterwards. + - @b Description: this callout is executed when the server has received a + buffer containing a DHCPv4 message, but the message hasn't been parsed + yet. The sole argument "query4" contains a pointer to the isc::dhcp::Pkt4 + object, which contains the source and destination address of the + received packet, interface over which the packet has been received, and + a raw buffer, stored in the data_ field, containing the DHCPv4 message + in the wire format. None of the packet fields (op_, hlen_, chaddr_, etc.) + are set yet. Callouts installed on this hook point can modify the data + in the received buffer. The server will parse the buffer afterwards. - Skip flag action: If any callout sets the skip flag, the server will skip the buffer parsing. In such case there is an expectation that - the callout will parse the buffer and create option objects (see - isc::dhcp::Pkt4::addOption()). Otherwise the server will find out - that some mandatory options are missing (e.g. DHCP Message Type) and - will drop the packet. If you want to have the capability to drop - a message, it is better to use skip flag in pkt4_receive callout. + the callout will parse options carried in the buffer, create + @c isc::dhcp::Option objects (or derived) and add them to the "query4" + object using the @c isc::dhcp::Pkt4::addOption. + Otherwise the server will find out that some mandatory options are + missing (e.g. DHCP Message Type) and will drop the message. If you + want to have the capability to drop a message, it is better to use + skip flag in "pkt4_receive" callout. @subsection dhcpv4HooksPkt4Receive pkt4_receive @@ -79,15 +81,14 @@ packet processing. Hook points that are not specific to packet processing - @b Description: this callout is executed when an incoming DHCPv4 packet is received and its content has been parsed. The sole - argument - query4 - contains a pointer to an isc::dhcp::Pkt4 object + argument "query4" contains a pointer to an isc::dhcp::Pkt4 object that contains all information regarding incoming packet, including its source and destination addresses, interface over which it was - received, a list of all options present within and relay + received, a list of all options present within and the relay information. All fields of the Pkt4 object can be modified at this - time, except data_. (By the time this hook is reached, the contents - of the data_ field has been already parsed and stored in other - fields. Therefore, the modification in the data_ field has no - effect.) + time. By the time this hook is reached, the contents of the data_ + field has been already parsed and stored in other fields. Therefore, + the modification in the data_ field has no effect. - Skip flag action: If any callout sets the skip flag, the server will drop the packet and start processing the next one. The reason for the drop @@ -98,19 +99,19 @@ packet processing. Hook points that are not specific to packet processing - @b Arguments: - name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: in/out - name: @b subnet4, type: isc::dhcp::Subnet4Ptr, direction: in/out - - name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *, direction: in + - name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *, + direction: in - @b Description: this callout is executed when a subnet is being selected for the incoming packet. All parameters and addresses will be assigned from that subnet. A callout can select a - different subnet if it wishes so, the list of all subnets currently - configured being provided as 'subnet4collection'. The list itself must + different subnet if it wishes so. The list of all subnets currently + configured are provided as "subnet4collection". The list itself must not be modified. - - Skip flag action: If any callout installed on 'subnet4_select' + - Skip flag action: If any callout, installed on "subnet4_select", sets the skip flag, the server will not select any subnet. Packet processing - will continue, but will be severely limited (i.e. only global options - will be assigned). + will continue, but will be severely limited. @subsection dhcpv4HooksLeaseSelect lease4_select @@ -120,22 +121,24 @@ packet processing. Hook points that are not specific to packet processing - name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: in/out - @b Description: this callout is executed after the server engine - has selected a lease for client's request but before the lease has + has selected a lease for the client's request, but before the lease has been inserted into the database. Any modifications made to the - isc::dhcp::Lease4 object will be stored in the lease's record in - the database. The callout should sanity check all modifications as - the server will use that data as is with no further checking.\n\n - The server processes lease requests for DISCOVER and REQUEST in a - very similar way. The only major difference is that for DISCOVER - the lease is just selected, but not inserted into the database. It - is possible to distinguish between DISCOVER and REQUEST by checking - value of the fake_allocation flag: a value of true indicates that the - lease won't be inserted into the database (DISCOVER), a value of - false indicates that it will (REQUEST). - - - Skip flag action: If any callout installed on 'lease4_select' - sets the skip flag, the server will not assign any lease. Packet - processing will continue, but client will not get an address. + "lease4" object will affect the lease's record in the database. + The callout should sanity check all modifications as the server will + use that data as is, with no further checking.\n\n + The server processes lease requests for DHCPDISCOVER and DHCPREQUEST in a + very similar way. The only major difference is that for DHCPDISCOVER + the lease is only selected, but not inserted into the database. The callouts + may distinguish between DHCPDISCOVER and DHCPREQUEST by checking the + value of the "fake_allocation" flag: a value of true indicates that the + lease won't be inserted into the database (DHCPDISCOVER case), a value of + false indicates that it will (DHCPREQUEST case). + + - Skip flag action: If any callout installed on "lease4_select" + sets the skip flag, the server will not assign any lease and the callouts + become responsible for the lease assignment. If the callouts fail to provide + a lease, the packet processing will continue, but client will not get + an address. @subsection dhcpv4HooksLeaseRenew lease4_renew @@ -146,15 +149,15 @@ packet processing. Hook points that are not specific to packet processing - name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: in/out - @b Description: this callout is executed when the server engine - is about to renew a lease, as a result of receiving REQUEST/Renewing - packet. The lease4 argument points to Lease4 object that contains - the updated values. Callout can modify those values. Care should be taken - as the server will attempt to update the lease in the database without - any additional checks. + is about to renew a lease, as a result of receiving DHCPREQUEST/Renewing + packet. The "lease4" argument points to @c isc::dhcp::Lease4 object that + contains the updated values. Callout can modify those values. Care should + be taken as the server will attempt to update the lease in the database + without any additional checks. - - Skip flag action: If any callout installed on 'lease4_renew' - sets the skip flag, the server will not update the lease and will - use old values instead. + - Skip flag action: If any callout installed on "lease4_renew" + sets the skip flag, the server will not update the lease in the + database and continue using old values instead. @subsection dhcpv4HooksLeaseRelease lease4_release @@ -163,11 +166,11 @@ packet processing. Hook points that are not specific to packet processing - name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: in - @b Description: this callout is executed when the server engine - is about to release a lease, as a result of receiving RELEASE packet. - The lease4 argument points to Lease4 object that contains the lease to + is about to release a lease, as a result of receiving DHCPRELEASE packet. + The "lease4" argument points to @c Lease4 object that contains the lease to be released. It doesn't make sense to modify it at this time. - - Skip flag action: If any callout installed on 'lease4_release' + - Skip flag action: If any callout installed on "lease4_release" sets the skip flag, the server will not delete the lease. It will be kept in the database and will go through the regular expiration/reuse process. @@ -178,17 +181,17 @@ packet processing. Hook points that are not specific to packet processing - name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: in/out - @b Description: this callout is executed when server's response - is about to be sent back to the client. The sole argument - response4 - - contains a pointer to an isc::dhcp::Pkt4 object that contains the + is about to be sent back to the client. The sole argument "response4" + contains a pointer to an isc::dhcp::Pkt4 object carrying the packet, with source and destination addresses set, interface over which it will be sent, and a list of all options and relay information. All fields - of the Pkt4 object can be modified at this time, except buffer_out_. + of the @c Pkt4 object can be modified at this time, except @c buffer_out_. (This is scratch space used for constructing the packet after all pkt4_send callouts are complete, so any changes to that field will be overwritten.) - Skip flag action: if any callout sets the skip flag, the server - will not construct raw buffer. The expectation is that if the callout + will not construct the raw buffer. The expectation is that if the callout set skip flag, it is responsible for constructing raw form on its own. Otherwise the output packet will be sent with zero length. @@ -198,17 +201,19 @@ packet processing. Hook points that are not specific to packet processing - name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: in/out - @b Description: this callout is executed when server's response - is about to be sent back to the client. The sole argument - response4 - - contains a pointer to an isc::dhcp::Pkt4 object that contains the + is about to be sent back to the client. The sole argument "response4" + contains a pointer to an @c isc::dhcp::Pkt4 object that contains the packet, with source and destination addresses set, interface over which it will be sent, and a list of all options and relay information. The raw - on-wire form is already prepared in buffer_out_ (see isc::dhcp::Pkt4::getBuffer()) - It doesn't make any sense to modify packet fields or options content - at this time, because they were already used to construct on-wire buffer. + on-wire form is already prepared in @c buffer_out_ (see + @c isc::dhcp::Pkt4::getBuffer()) + Callouts should not modify the packet fields or options contents at this + time, because they were already used to construct on-wire buffer. Their + modification would have no effect. - Skip flag action: if any callout sets the skip flag, the server will drop this response packet. However, the original request packet - from a client was processed, so server's state was most likely changed + from a client was processed, so server's state most likely has changed (e.g. lease was allocated). Setting this flag merely stops the change being communicated to the client. diff --git a/src/bin/dhcp6/dhcp6_hooks.dox b/src/bin/dhcp6/dhcp6_hooks.dox index de268c8be6..8247a54654 100644 --- a/src/bin/dhcp6/dhcp6_hooks.dox +++ b/src/bin/dhcp6/dhcp6_hooks.dox @@ -55,25 +55,25 @@ packet processing. Hook points that are not specific to packet processing - name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: in/out - @b Description: This callout is executed when an incoming DHCPv6 - packet is received and the data stored in a buffer. The sole argument - - query6 - contains a pointer to an isc::dhcp::Pkt6 object that contains + packet is received and the data stored in a buffer. The sole argument + "query6" contains a pointer to an @c isc::dhcp::Pkt6 object that contains the received information stored in the data_ field. Basic information like protocol, source/destination addresses and ports are set, but the contents of the buffer have not yet been parsed. That means that - the options_ field (that will eventually contain a list of objects + the @c options_ field (that will eventually contain a list of objects representing the received options) is empty, so none of the methods that operate on it (e.g., getOption()) will work. The primary purpose of this early call is to offer the ability to modify incoming packets in their raw form. Unless you need to access to the raw data, it is - usually better to install your callout on the pkt6_receive hook point. + usually better to install your callout on the "pkt6_receive" hook point. - Skip flag action: If any callout sets the skip flag, the - server will assume that the callout parsed the buffer and added then - necessary option objects to the options_ field; the server will not + server will assume that the callout parsed the buffer and added the + necessary option objects to the @c options_ field; the server will not do any parsing. If the callout sets the skip flag but does not parse the buffer, the server will most probably drop the packet due to the absence of mandatory options. If you want to drop the packet, - see the description of the skip flag in the pkt6_receive hook point. + see the description of the skip flag in the "pkt6_receive" hook point. @subsection dhcpv6HooksPkt6Receive pkt6_receive @@ -81,16 +81,16 @@ packet processing. Hook points that are not specific to packet processing - name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: in/out - @b Description: This callout is executed when an incoming DHCPv6 - packet is received and its content is parsed. The sole argument - - query6 - contains a pointer to an isc::dhcp::Pkt6 object that contains + packet is received and its content is parsed. The sole argument + "query6" contains a pointer to an @c isc::dhcp::Pkt6 object that contains all information regarding incoming packet, including its source and destination addresses, the interface over which it was received, a list of all options present within and relay information. All fields of - the Pkt6 object can be modified at this time, except data_. (data_ + the "query6" object can be modified at this time, except data_. (data_ contains the incoming packet as raw buffer. By the time this hook is reached, that information has already been parsed and is available though - other fields in the Pkt6 object. For this reason, it doesn't make - sense to modify it.) + other fields in the Pkt6 object. For this reason, modification of the + @c data_ field would have no effect.) - Skip flag action: If any callout sets the skip flag, the server will drop the packet and start processing the next one. The reason for the drop @@ -107,13 +107,12 @@ packet processing. Hook points that are not specific to packet processing selected for the incoming packet. All parameters, addresses and prefixes will be assigned from that subnet. A callout can select a different subnet if it wishes so, the list of all subnets currently - configured being provided as 'subnet6collection'. The list itself must + configured being provided as "subnet6collection". The list itself must not be modified. - - Skip flag action: If any callout installed on 'subnet6_select' + - Skip flag action: If any callout installed on "subnet6_select" sets the skip flag, the server will not select any subnet. Packet processing - will continue, but will be severely limited (i.e. only global options - will be assigned). + will continue, but will be severely limited. @subsection dhcpv6HooksLease6Select lease6_select @@ -125,18 +124,18 @@ packet processing. Hook points that are not specific to packet processing - @b Description: This callout is executed after the server engine has selected a lease for client's request but before the lease has been inserted into the database. Any modifications made to the - isc::dhcp::Lease6 object will be stored in the lease's record in the - database. The callout should make sure that any modifications are - sanity checked as the server will use that data as is with no further + "lease6" object will affect the lease's record in the database. + The callout should make sure that any modifications are sanity + checked as the server will use that data as is, with no further checking.\n\n The server processes lease requests for SOLICIT and - REQUEST in a very similar way. The only major difference is that - for SOLICIT the lease is just selected; it is not inserted into - the database. It is possible to distinguish between SOLICIT and - REQUEST by checking value of the fake_allocation flag: a value of true - means that the lease won't be inserted into the database (SOLICIT), - a value of false means that it will (REQUEST). - - - Skip flag action: If any callout installed on 'lease6_select' + REQUEST in a very similar way. The major difference is that + for SOLICIT the lease is only selected; it is not inserted into + the database. The callouts can distinguish between the SOLICIT and + REQUEST by checking the value of the "fake_allocation" flag: a value + of true means that the lease won't be inserted into the database + (SOLICIT case), a value of false means that it will (REQUEST). + + - Skip flag action: If any callout installed on "lease6_select" sets the skip flag, the server will not assign that particular lease. Packet processing will continue and the client may get other addresses or prefixes if it requested more than one address and/or prefix. @@ -150,26 +149,26 @@ packet processing. Hook points that are not specific to packet processing - @b Description: This callout is executed when the server engine is about to renew an existing lease. The client's request is provided as - the query6 argument and the existing lease with the appropriate fields - already modified is given in the lease6 argument. The final argument, + the "query6" argument and the existing lease with the appropriate fields + already modified is given in the "lease6" argument. The final argument, ia_na, is the IA_NA option that will be sent back to the client. - Callouts installed on the lease6_renew may modify the content of - the lease6 object. Care should be taken however, as that modified + Callouts installed on the "lease6_renew" may modify the content of + the "lease6" object. Care should be taken however, as that modified information will be written to the database without any further checking. \n\n Although the envisaged usage assumes modification of T1, T2, preferred and valid lifetimes only, other parameters associated - with the lease may be modified as well. The only exception is the addr_ + with the lease may be modified as well. The only exception is the @c addr_ field, which must not be modified as it is used by the database to select the existing lease to be updated. Care should also be taken to - modify the ia_na argument to match any changes in the lease6 argument. + modify the "ia_na" argument to match any changes in the "lease6" argument. If a client sends more than one IA_NA option, callouts will be called separately for each IA_NA instance. The callout will be called only when the update is valid, i.e. conditions such as an invalid addresses or invalid iaid renewal attempts will not trigger this hook point. - - Skip flag action: If any callout installed on 'lease6_renew' + - Skip flag action: If any callout installed on "lease6_renew" sets the skip flag, the server will not renew the lease. Under these - circumstances, the callout should modify the ia_na argument to reflect + circumstances, the callout should modify the "ia_na" argument to reflect this fact; otherwise the client will think the lease was renewed and continue to operate under this assumption. @@ -181,12 +180,12 @@ packet processing. Hook points that are not specific to packet processing - @b Description: This callout is executed when the server engine is about to release an existing lease. The client's request is provided - as the query6 argument and the existing lease is given in the lease6 - argument. Although the lease6 structure may be modified, it doesn't + as the "query6" argument and the existing lease is given in the "lease6" + argument. Although the "lease6" structure may be modified, it doesn't make sense to do so as it will be destroyed immediately the callouts finish execution. - - Skip flag action: If any callout installed on 'lease6_release' + - Skip flag action: If any callout installed on "lease6_release" sets the skip flag, the server will not delete the lease, which will remain in the database until it expires. However, the server will send out the response back to the client as if it did. @@ -197,22 +196,22 @@ packet processing. Hook points that are not specific to packet processing - name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: in/out - @b Description: This callout is executed when server's response - is about to be send back to the client. The sole argument - response6 - - contains a pointer to an isc::dhcp::Pkt6 object that contains the + is about to be send back to the client. The sole argument "response6" + contains a pointer to an @c isc::dhcp::Pkt6 object that contains the packet, with set source and destination addresses, interface over which it will be send, list of all options and relay information. All fields - of the Pkt6 object can be modified at this time. It should be noted that - unless the callout sets the skip flag (see below), anything placed in the - bufferOut_ field will be overwritten when the callout returns. - (bufferOut_ is scratch space used for constructing the packet.) + of the "response6" object can be modified at this time. It should be + noted that unless the callout sets the skip flag (see below), anything + placed in the @c buffer_out_ field will be overwritten when the callout + returns. (buffer_out_ is scratch space used for constructing the packet.) - Skip flag action: If any callout sets the skip flag, the server - will assume that the callout did pack the transaction-id, message type and - option objects into the bufferOut_ field and will skip packing part. + will assume that the callout did pack the "transaction-id", "message type" + and option objects into the @c buffer_out_ field and will skip packing part. Note that if the callout sets skip flag, but did not prepare the output buffer, the server will send a zero sized message that will be ignored by the client. If you want to drop the packet, please see - skip flag in the buffer6_send hook point. + skip flag in the "buffer6_send" hook point. @subsection dhcpv6HooksBuffer6Send buffer6_send @@ -221,14 +220,14 @@ packet processing. Hook points that are not specific to packet processing - @b Description: This callout is executed when server's response is assembled into binary form and is about to be send back to the - client. The sole argument - response6 - contains a pointer to an - isc::dhcp::Pkt6 object that contains the packet, with set source and + client. The sole argument "response6" contains a pointer to an + @c isc::dhcp::Pkt6 object that contains the packet, with set source and destination addresses, interface over which it will be sent, list of all options and relay information. All options are already encoded - in bufferOut_ field. It doesn't make sense to modify anything but the - contents of bufferOut_ at this time (although if it is a requirement + in @c buffer_out_ field. It doesn't make sense to modify anything but the + contents of buffer_out_ at this time (although if it is a requirement to modify that data, it will probably be found easier to modify the - option objects in a callout attached to the pkt6_send hook). + option objects in a callout attached to the "pkt6_send" hook). - Skip flag action: If any callout sets the skip flag, the server will drop this response packet. However, the original request packet diff --git a/src/lib/hooks/hooks_user.dox b/src/lib/hooks/hooks_user.dox index ee62b5c22f..0122106549 100644 --- a/src/lib/hooks/hooks_user.dox +++ b/src/lib/hooks/hooks_user.dox @@ -100,11 +100,11 @@ shared library and loaded by Kea into its address space. To illustrate how to write code that integrates with Kea, we will use the following (rather contrived) example: -The Kea DHCPv4 server is used to allocate IPv4 addresses to clients +The Kea DHCPv4 server is used to allocate IPv4 addresses to clients (as well as to pass them other information such as the address of DNS servers). We will suppose that we need to classify clients requesting IPv4 addresses according to their hardware address, and want to log both -the hardware address and allocated IP address for the clients of interest. +the hardware address and allocated IP address for the clients of interest. The following sections describe how to implement these requirements. The code presented here is not efficient and there are better ways of @@ -282,11 +282,11 @@ int callout(CalloutHandle& handle); @endcode (As before, the callout is declared with "C" linkage.) Information is passed -between Kea and the callout through name/value pairs in the CalloutHandle +between Kea and the callout through name/value pairs in the @c CalloutHandle object. The object is also used to pass information between callouts on a per-request basis. (Both of these concepts are explained below.) -A callout returns an "int" as a status return. A value of 0 indicates +A callout returns an @c int as a status return. A value of 0 indicates success, anything else signifies an error. The status return has no effect on server processing; the only difference between a success and error code is that if the latter is returned, the server will @@ -296,7 +296,7 @@ error information to the Kea logging system. @subsubsection hooksdgArguments Callout Arguments -The CalloutHandle object provides two methods to get and set the +The @c CalloutHandle object provides two methods to get and set the arguments passed to the callout. These methods are called (naturally enough) getArgument and SetArgument. Their usage is illustrated by the following code snippets. @@ -336,27 +336,27 @@ In the callout handle.setArgument("data_count", number); @endcode -As can be seen "getArgument" is used to retrieve data from the -CalloutHandle, and setArgument used to put data into it. If a callout +As can be seen @c getArgument is used to retrieve data from the +@c CalloutHandle, and @c setArgument used to put data into it. If a callout wishes to alter data and pass it back to the server, it should retrieve -the data with getArgument, modify it, and call setArgument to send +the data with @c getArgument, modify it, and call @c setArgument to send it back. There are several points to be aware of: -- the data type of the variable in the call to getArgument must match -the data type of the variable passed to the corresponding setArgument +- the data type of the variable in the call to @c getArgument must match +the data type of the variable passed to the corresponding @c setArgument exactly: using what would normally be considered to be a "compatible" type is not enough. For example, if the server passed -an argument as an "int" and the callout attempted to retrieve it as a -"long", an exception would be thrown even though any value that can -be stored in an "int" will fit into a "long". This restriction also +an argument as an @c int and the callout attempted to retrieve it as a +@c long, an exception would be thrown even though any value that can +be stored in an @c int will fit into a @c long. This restriction also applies the "const" attribute but only as applied to data pointed to by -pointers, e.g. if an argument is defined as a "char*", an exception will +pointers, e.g. if an argument is defined as a @c char*, an exception will be thrown if an attempt is made to retrieve it into a variable of type -"const char*". (However, if an argument is set as a "const int", it can -be retrieved into an "int".) The documentation of each hook point will -detail the data type of each argument. +@c const @c char*. (However, if an argument is set as a @c const @c int, +it can be retrieved into an @c int.) The documentation of each hook +point will detail the data type of each argument. - Although all arguments can be modified, some altered values may not be read by the server. (These would be ones that the server considers "read-only".) Consult the documentation of each hook to see whether an @@ -371,8 +371,8 @@ parameters can be modified. As a general rule: - Do not alter arguments unless you mean the change to be reflected in the server. -- If you alter an argument, call CalloutHandle::setArgument to update the -value in the CalloutHandle object. +- If you alter an argument, call @c CalloutHandle::setArgument to update the +value in the @c CalloutHandle object. @subsubsection hooksdgSkipFlag The "Skip" Flag @@ -391,7 +391,7 @@ is a server where a callout inspects the hardware address of the client sending the packet and compares it against a black list; if the address is on it, the callout notifies the server to drop the packet. -To handle these common cases, the CalloutHandle has a "skip" flag. +To handle these common cases, the @c CalloutHandle has a "skip" flag. This is set by a callout when it wishes the server to skip normal processing. It is set false by the hooks framework before callouts on a hook are called. If the flag is set on return, the server will take the @@ -427,7 +427,7 @@ Future developments may have the server processing multiple packets simultaneously, or to suspend processing on a packet and resume it at a later time after other packets have been processed. -As well as argument information, the CalloutHandle object can be used by +As well as argument information, the @c CalloutHandle object can be used by callouts to attach information to a packet being handled by the server. This information (known as "context") is not used by the server: its purpose is to allow callouts to pass information between one another on a @@ -441,9 +441,9 @@ simultaneously: callouts can effectively attach data to a packet that follows the packet around the system. Context information is held as name/value pairs in the same way -as arguments, being accessed by the pair of methods setContext and -getContext. They have the same restrictions as the setArgument and -getArgument methods - the type of data retrieved from context must +as arguments, being accessed by the pair of methods @c setContext and +@c getContext. They have the same restrictions as the @c setArgument and +@c getArgument methods - the type of data retrieved from context must exactly match the type of the data set. The example in the next section illustrates their use. @@ -457,8 +457,9 @@ do this in one callout, for this example we'll use two: - pkt4_receive - a callout on this hook is invoked when a packet has been received and has been parsed. It is passed a single argument, "query4" -which is an isc::dhcp::Pkt4 object (representing a DHCP v4 packet). -We will do the classification here. +which is an isc::dhcp::Pkt4Ptr object, holding a pointer to the +isc::dhcp::Pkt4 object (representing a DHCPv4 packet). We will do the +classification here. - pkt4_send - called when a response is just about to be sent back to the client. It is passed a single argument "response4". This is the @@ -521,7 +522,7 @@ int pkt4_receive(CalloutHandle& handle) { } @endcode -The pkt4_receive callout placed the hardware address of an interesting client in +The "pkt4_receive" callout placed the hardware address of an interesting client in the "hwaddr" context for the packet. Turning now to the callout that will write this information to the log file: @@ -757,12 +758,12 @@ to initialize per-request context. The second is called after all server-defined hooks have been processed, and is to allow a library to tidy up. -As an example, the pkt4_send example above required that the code +As an example, the "pkt4_send" example above required that the code check for an exception being thrown when accessing the "hwaddr" context item in case it was not set. An alternative strategy would have been to provide a callout for the "context_create" hook and set the context item "hwaddr" to an empty string. Instead of needing to handle an exception, -pkt4_send would be guaranteed to get something when looking for +"pkt4_send" would be guaranteed to get something when looking for the hwaddr item and so could write or not write the output depending on the value. @@ -771,7 +772,7 @@ automatically deletes context. An example where it could be required is where memory has been allocated by a callout during the processing of a request and a raw pointer to it stored in the context object. On destruction of the context, that memory will not be automatically -released. Freeing in the memory in the "context_destroy callout will solve +released. Freeing in the memory in the "context_destroy" callout will solve that problem. Actually, when the context is destroyed, the destructor @@ -786,8 +787,8 @@ Here it is assumed that the hooks library is performing some form of security checking on the packet and needs to maintain information in a user-specified "SecurityInformation" object. (The details of this fictitious object are of no concern here.) The object is created in -the context_create callout and used in both the pkt4_receive and the -pkt4_send callouts. +the "context_create" callout and used in both the "pkt4_receive" and the +"pkt4_send" callouts. @code // Storing information in a "raw" pointer. Assume that the @@ -831,7 +832,7 @@ int pkt4_send(CalloutHandle& handle) { } // Context destruction. We need to delete the pointed-to SecurityInformation -// object because we will lose the pointer to it when the CalloutHandle is +// object because we will lose the pointer to it when the @c CalloutHandle is // destroyed. int context_destroy(CalloutHandle& handle) { // Retrieve the pointer to the SecurityInformation object @@ -843,7 +844,7 @@ int context_destroy(CalloutHandle& handle) { } @endcode -The requirement for the context_destroy callout can be eliminated if +The requirement for the "context_destroy" callout can be eliminated if a Boost shared ptr is used to point to the allocated memory: @code @@ -865,7 +866,7 @@ int context_create(CalloutHandle& handle) { } // Other than the data type, a shared pointer has similar semantics to a "raw" -// pointer. Only the code from pkt4_receive is shown here. +// pointer. Only the code from "pkt4_receive" is shown here. int pkt4_receive(CalloutHandle& handle) { // Retrieve the pointer to the SecurityInformation object @@ -881,7 +882,7 @@ int pkt4_receive(CalloutHandle& handle) { } // No context_destroy callout is needed to delete the allocated -// SecurityInformation object. When the CalloutHandle is destroyed, the shared +// SecurityInformation object. When the @c CalloutHandle is destroyed, the shared // pointer object will be destroyed. If that is the last shared pointer to the // allocated memory, then it too will be deleted. @endcode @@ -915,13 +916,13 @@ registration is through the LibraryHandle object. This was briefly introduced in the discussion of the framework functions, in that an object of this type is pass to the "load" function. A LibraryHandle can also be obtained from within a callout by calling the CalloutHandle's -getLibraryHandle() method. +@c getLibraryHandle() method. The LibraryHandle provides three methods to manipulate callouts: -- registerCallout - register a callout on a hook. -- deregisterCallout - deregister a callout from a hook. -- deregisterAllCallouts - deregister all callouts on a hook. +- @c registerCallout - register a callout on a hook. +- @c deregisterCallout - deregister a callout from a hook. +- @c deregisterAllCallouts - deregister all callouts on a hook. The following sections cover some of the ways in which these can be used. @@ -960,7 +961,7 @@ a hook point. Although it is likely to be rare for user code to need to do this, there may be instances where it make sense. To register multiple callouts on a hook, just call -LibraryHandle::registerCallout multiple times on the same hook, e.g. +@c LibraryHandle::registerCallout multiple times on the same hook, e.g. @code libhandle.registerCallout("pkt4_receive", classify); @@ -968,7 +969,7 @@ LibraryHandle::registerCallout multiple times on the same hook, e.g. @endcode The hooks framework will call the callouts in the order they are -registered. The same CalloutHandle is passed between them, so any +registered. The same @c CalloutHandle is passed between them, so any change made to the CalloutHandle's arguments, "skip" flag, or per-request context by the first is visible to the second. @@ -1036,7 +1037,7 @@ int write_data(CalloutHandle& handle) { flush(interesting); // We've logged the data, so deregister ourself. This callout will not - // be called again until it is registered by pkt4_receive. + // be called again until it is registered by "pkt4_receive". handle.getLibraryHandle().deregisterCallout("pkt4_send", write_data); @@ -1093,7 +1094,7 @@ request. The vertical blue lines represent callout context. Context is per-packet but also per-library. When the server calls "authorize", -the CalloutHandle's getContext and setContext methods access a context +the CalloutHandle's @c getContext and @c setContext methods access a context created purely for library 1. The next callout on the hook will access context created for library 2. These contexts are passed to the callouts associated with the next hook. So when "check" is called, it gets the @@ -1132,7 +1133,7 @@ as separate elements of the hooks-libraries configuration element, e.g. In rare cases, it is possible that one library may want to pass data to another. This can be done in a limited way by means of the -CalloutHandle's setArgument and getArgument calls. For example, in the +CalloutHandle's @c setArgument and @c getArgument calls. For example, in the above diagram, the callout "add_option" can pass a value to "putopt" by setting a name.value pair in the hook's argument list. "putopt" would be able to read this, but would not be able to return information @@ -1185,7 +1186,7 @@ to add one.) For example: extern "C" { int version() { - return (BIND10_HOOKS_VERSION); + return (KEA_HOOKS_VERSION); } int load() {