From: Marcin Siodelski Date: Fri, 31 Mar 2017 12:54:31 +0000 (+0200) Subject: [5175] Updated Developer's Guide with hooks for CA. X-Git-Tag: trac5196_base~9^2~4 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8152b76e97d7cc567c82aa1ba6b0388458eaba2b;p=thirdparty%2Fkea.git [5175] Updated Developer's Guide with hooks for CA. --- diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index 20f3b83430..594abc6275 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -1,4 +1,4 @@ -// Copyright (C) 2012-2016 Internet Systems Consortium, Inc. ("ISC") +// Copyright (C) 2012-2017 Internet Systems Consortium, Inc. ("ISC") // // This Source Code Form is subject to the terms of the Mozilla Public // License, v. 2.0. If a copy of the MPL was not distributed with this @@ -46,6 +46,7 @@ * - @subpage hooksdgDevelopersGuide * - @subpage dhcpv4Hooks * - @subpage dhcpv6Hooks + * - @subpage agentHooks * - @subpage hooksComponentDeveloperGuide * - @subpage hooksmgMaintenanceGuide * - @subpage libdhcp_user_chk diff --git a/src/bin/agent/Makefile.am b/src/bin/agent/Makefile.am index 0a35c43277..cac15dcfda 100644 --- a/src/bin/agent/Makefile.am +++ b/src/bin/agent/Makefile.am @@ -14,6 +14,7 @@ CLEANFILES = *.gcno *.gcda ca_messages.h ca_messages.cc s-messages man_MANS = kea-ctrl-agent.8 DISTCLEANFILES = $(man_MANS) EXTRA_DIST = $(man_MANS) kea-ctrl-agent.xml +EXTRA_DIST += agent_hooks.dox if GENERATE_DOCS kea-ctrl-agent.8: kea-ctrl-agent.xml diff --git a/src/bin/agent/agent-hooks.dox b/src/bin/agent/agent-hooks.dox new file mode 100644 index 0000000000..7155a325f7 --- /dev/null +++ b/src/bin/agent/agent-hooks.dox @@ -0,0 +1,58 @@ +// Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC") +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +/** +@page agentHooks The Hooks API for the Control Agent + +@section agentHooksIntroduction Introduction +The Kea Control Agent features "Hooks" API that allows the user-written +code to be integrated with the Control Agent and handle some +of the control commands. The hooks library can be either used to provide +support for the new commands (not supported natively by the Control Agent) +or "override" implementation of the existing handlers. The hooks library +signals to the Control Agent that it has processed the given command by +setting "next step status" value to SKIP. + +The hooks library can also be used to perform some additional tasks +related to reception of the control command instead of handling it, e.g. +logging or notifying some external service about reception of the +command. + +@section agentHooksHookPoints Hooks in the Control Agent + + @subsection agentHooksControlCommandReceive control_command_receive + + - @b Arguments: + - name: @b command, type: isc::data::ConstElementPtr, direction: in/out + - name: @b response, type: isc::data::ConstElementPtr, direction: in/out + + - @b Description: this callout is executed when Control Agent receives a + control command over the RESTful interface (HTTP). + The "command" argument is a pointer to the parsed JSON structure + including command name and command arguments. If the callout implements + the specified command, it handles the command and creates appropriate + response. The response should be returned in the "response" argument. + In most cases, the callout which handles the command will set the next + step action to SKIP, to prevent the server from trying to handle the + command on its own and overriding the response created by the callouts. + A notable exception is the 'list-commands' command for which the callouts + should not set the next step action to SKIP. The server has a special + code path for this command which combines the list of commands returned + by the callouts with the list of commands supported by the server. If + the callout sets the next step action to SKIP in this case, the server + will only return the list of commands supported by the hook library. + The callout can modify the command arguments to influence the command + processing by the Command Manager. For example, it may freely modify + the configuration received in 'set-config' before it is processed by + the server. The SKIP action is not set in this case. + + - Next step status: if any callout sets the next step action to SKIP, + the server will assume that the command has been handled by the callouts + and will expect that the response is provided in the "response" argument. + The Control Agent will not handle the command in this case but simply + return the response returned by the callout to the caller. + +*/ \ No newline at end of file