diff options
Diffstat (limited to 'libccnx-transport-rta/ccnx/api/control/controlPlaneInterface.h')
| -rw-r--r-- | libccnx-transport-rta/ccnx/api/control/controlPlaneInterface.h | 456 |
1 files changed, 456 insertions, 0 deletions
diff --git a/libccnx-transport-rta/ccnx/api/control/controlPlaneInterface.h b/libccnx-transport-rta/ccnx/api/control/controlPlaneInterface.h new file mode 100644 index 00000000..01b6e861 --- /dev/null +++ b/libccnx-transport-rta/ccnx/api/control/controlPlaneInterface.h @@ -0,0 +1,456 @@ +/* + * Copyright (c) 2017 Cisco and/or its affiliates. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at: + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file controlPlaneInterface.h + * + * Based loosely on Netlink (RFC 3549) + * + * Constructs `CCNxControl` for common control plane operations. + * These methods do not actually communicate with the transport. + * The user must send the message down their protocol stack and await a response. + * + * CPI messages have a Type: Request, Response, or ACK. + * A request may ask for an ACK if successful for commands that would otherwise not + * produce a response. + * Request that fail always generate a NACK. + * + * All messages must carry a "sequence number" which must be unique within + * the Transport. + * Although sequence numbers imply an ordering, they do not imply + * causality or precedence. + * They only imply a duplicate. + * + * An ACK is a reponse that carries no data, it just ACKs (or NACKs) a sequence number. + * A field in the ACK indicates it is an error (NACK). An ACK carries the original + * request and an optional message. + * + * All messages carry a mandatory sequence number, + * which is unique in all messages. + * An ACK (or NACK) contains the original message that generated the ACK, + * including its sequence number. + * These conventions allow one to implement a reliable CPI messaging system, if desired. + * + * The Control Plane operations are: + * + * * CPI_INTERFACE_LIST + * Return: A response with an array of network interfaces ("interfaceIndex", type, and flags), or a NACK. + * + * * CPI_REGISTER + * Add a FIB entry with the given CCNxName prefix to the specified interfaceIndex. + * The value of "-1" means the current interface. + * Return: an ACK (or NACK) + * + * * CPI_UNREGISTER + * Remove a FIB entry with the given CCNxName prefix from the specified interfaceIndex. + * The value of "-1" means the current interface. + * Return: an ACK (or NACK) + * + * * CPI_FORWARDER_VERSION: + * Return: Response (a string) or a NACK. + * + * * CPI_ADDRESS + * Request: by interfaceIndex + * Response: the sockaddr_storage list for the interface, or a NACK + * + * * CPI_PREFIX_REGISTRATION_LIST + * Request: by interfaceIndex, value "-1" means the current interface + * Response: the list of CCNxNames (with their flags) registered on the interface or a NACK + * + * * CPI_PAUSE_INPUT + * Request: by current connection, causes stack to pause the input (top and bottom) + * Response: Forwarder sends ACK up the stack. + * + * Example: + * @code + * <#example#> + * @endcode + * + */ +/* + * This description needs to be revised based on the recent refactoring. + * + * The user will be interested in cpi_Forwarding.h and cpi_ManageLinks.h. + * + * Case 1027: need to specify the memory management, especially for variable sized messages. + */ + +#ifndef libccnx_controlPlaneInterface_h +#define libccnx_controlPlaneInterface_h + +#include <ccnx/transport/common/transport_MetaMessage.h> +#include <sys/socket.h> + +#include <ccnx/api/control/cpi_ControlMessage.h> +#include <ccnx/api/control/cpi_Forwarding.h> +#include <ccnx/api/control/cpi_ManageLinks.h> +#include <ccnx/api/control/cpi_CancelFlow.h> +#include <ccnx/api/control/cpi_ManageCaches.h> +#include <ccnx/api/control/cpi_ManageWldr.h> + +typedef enum { + CPI_REQUEST, + CPI_RESPONSE, // a resonse with contents + CPI_ACK // a response without contents +} CpiMessageType; + +typedef enum { + CPI_ERROR, // a NACK response, carries original message + CPI_REGISTER_PREFIX, + CPI_UNREGISTER_PREFIX, + CPI_FORWARDER_VERSION, + CPI_INTERFACE_LIST, + CPI_ADDRESS, + CPI_PREFIX_REGISTRATION_LIST, + CPI_PAUSE, + CPI_FLUSH, + CPI_CANCEL_FLOW, + CPI_CREATE_TUNNEL, + CPI_REMOVE_TUNNEL, + CPI_CONNECTION_LIST, + CPI_ADD_ETHER_CONNECTION, + CPI_ADD_CONNECTION_ETHERNET, + CPI_REMOVE_CONNECTION_ETHERNET, + CPI_ADD_LISTENER, + CPI_REMOVE_LISTENER, + CPI_CACHE_STORE_ON, + CPI_CACHE_STORE_OFF, + CPI_CACHE_SERVE_ON, + CPI_CACHE_SERVE_OFF, + CPI_CACHE_CLEAR, + CPI_SET_FORWARDING_STRATEGY, + CPI_SET_WLDR +} CpiOperation; + +typedef enum { + ACK_ACK, + ACK_NACK +} CpiAckType; + +typedef struct control_plane_information { + CpiMessageType messageType; + CpiOperation operation; + uint64_t serialNumber; +} ControlPlaneInformation; + + +const char *cpiRequest_GetJsonTag(); +const char *cpiResponse_GetJsonTag(); + +/** + * Return the name used in the JSON representation for a control message sequence number. + * + * @return The name used in the JSON representation for a control message sequence number. + * + * Example: + * @code + * { + **cpiSequence_GetJSONTag + * } + * @endcode + */ +const char *cpiSequence_GetJSONTag(void); + +/** + * Get the CpiOperation from the given JSON representation of the CPI command. + * + * @param [in] json A pointer to a valid PARCJSON instance. + * + * @return The CpiOperation specified in the JSON. + * + * Example: + * @code + * { + * const char *sequenceNumberJSONName = cpiSequence_GetJSONTag(); + * } + * @endcode + * + * @see <#references#> + */ +CpiOperation cpi_getCPIOperation2(const PARCJSON *json); + +/** + * <#One Line Description#> + * + * <#Paragraphs Of Explanation#> + * + * @param [in] control A pointer to a valid CCNxControl instance. + * + * @return <#value#> <#explanation#> + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +CpiOperation cpi_GetMessageOperation(CCNxControl *control); + +/** + * Get the CpiMessageType from the given JSON representation of the CPIMessage + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +CpiMessageType controlPlaneInterface_GetCPIMessageType(PARCJSON *json); + +/** + * <#One Line Description#> + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +CpiMessageType cpi_GetMessageType(const CCNxControl *control); + +/** + * Get the sequence number of the given Control Plane Message. + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +uint64_t controlPlaneInterface_GetSequenceNumber(const PARCJSON *controlPlaneMessage); + +/** + * All CPI messages carry a sequence number. + * + * Example: + * @code + * <#example#> + * @endcode + */ +uint64_t cpi_GetSequenceNumber(CCNxControl *control); + +/** + * Gererate a CPI request + * + * Example: + * @code + * <#example#> + * @endcode + */ +#define CPI_CURRENT_INTERFACE 0x7FFFFFFF + +/** + * Generate a control object to request the forewarder version + * + * Will cause a CPI Response to be sent back, if the forwarder supports the command. + * Otherwise, the ForwarderConnector should send a NACK back. + * + * @return <#return#> + * + * Example: + * @code + * <#example#> + * @endcode + */ +CCNxControl *cpi_ForwarderVersion(void); + +/** + * Cause the connection to pause input (from the top and bottom). + * When the ACk arrives back to the top, caller know there are no + * more data messages in the stack. + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +PARCJSON *cpi_CreatePauseInputRequest(void); + +/** + * Creates a message that the forwarder connector will ACK. Once the + * ACK with the corresponding sequence number is received, the sender knows + * that all prior messages had been handled by the forwarder connector. + * + * @return non-null An allocted JSON object + * @return null An error + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +PARCJSON *cpi_CreateFlushRequest(void); + +/** + * Given the inner operation member, wrap it in a Request with a sequence number + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * + * Example: + * @code + * <#example#> + * @endcode + * + * @see <#references#> + */ +PARCJSON *cpi_CreateRequest(const char *key, PARCJSON *operation); + +/** + * <#One Line Description#> + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * + * Example: + * @code + * <#example#> + * @endcode + * + * @see <#references#> + */ +CCNxControl *cpi_CreateResponse(CCNxControl *request, PARCJSON *response); + +/** + * Create an acknowledgement to the given request (expressed in JSON). + * + * @param [in] request A pointer to a PARCJSON representation of the request to acknowledge. + * + * @return NULL Memory could not be allocated. + * @return non-NULL A pointer to a PARCJSON instance representing the acknowledgement. + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +PARCJSON *cpiAcks_CreateAck(const PARCJSON *request); + +/** + * <#One Line Description#> + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +PARCJSON *cpiAcks_CreateNack(const PARCJSON *request); + +/** + * <#One Line Description#> + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +bool cpiAcks_IsAck(const PARCJSON *json); + +/** + * <#One Line Description#> + * + * <#Paragraphs Of Explanation#> + * + * @param [<#in out in,out#>] <#name#> <#description#> + * + * @return <#value#> <#explanation#> + * @return <#value#> <#explanation#> + * + * Example: + * @code + * { + * <#example#> + * } + * @endcode + * + * @see <#references#> + */ +uint64_t cpiAcks_GetAckOriginalSequenceNumber(const PARCJSON *json); +#endif // libccnx_controlPlaneInterface_h |