diff options
Diffstat (limited to 'libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_CommandOpenConnection.h')
| -rw-r--r-- | libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_CommandOpenConnection.h | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_CommandOpenConnection.h b/libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_CommandOpenConnection.h new file mode 100644 index 00000000..031ae04b --- /dev/null +++ b/libccnx-transport-rta/ccnx/transport/transport_rta/commands/rta_CommandOpenConnection.h @@ -0,0 +1,219 @@ +/* + * 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 rta_CommandOpenConnection.h + * @brief Represents a command to open a connection + * + * Used to construct an RtaCommand object that is passed to rtaTransport_PassCommand() or _rtaTransport_SendCommandToFramework() + * to send a command from the API's thread of execution to the Transport's thread of execution. + * + */ +#ifndef Libccnx_rta_CommandOpenConnection_h +#define Libccnx_rta_CommandOpenConnection_h + + +struct rta_command_openconnection; +typedef struct rta_command_openconnection RtaCommandOpenConnection; + +/** + * Creates a OpenConnection command object + * + * Creates a OpenConnection command object used to signal the RTA framework to + * open a specified connection. The user passes in the two sides of a socket pair + * plus the JSON representation of the connection. + * + * The RTA transport API connector will use the transportNotifierFd side of the socket pair. + * + * The caller must know the protocol stack handle stackId to specify which stack to + * associate the connection with. + * + * @param [in] stackId The protocol stack handle to use for the connection. + * @param [in] apiNotifierFd A descriptor used to notify the API that there's data to read from the transport. + * @param [in] transportNotifierFd A descriptor used to notify the Transport there's data to read from the API. + * @param [in] config The stack/connection config. + * + * @return non-null An allocated object + * @return null An error + * + * Example: + * @code + * void foo(RTATransport *transport) + * { + * #define API_SIDE 0 + * #define TRANSPORT_SIDE 1 + * + * int pair[2]; + * socketpair(AF_LOCAL, SOCK_STREAM, 0, pair); + * PARCJSON *config = createConnectionConfig(); + * + * RtaCommandOpenConnection *openCommand = rtaCommandOpenConnection_Create(6, pair[API_SIDE], pair[TRANSPORT_SIDE], config); + * RtaCommand *command = rtaCommand_CreateOpenConnection(openCommand); + * _rtaTransport_SendCommandToFramework(transport, command); + * rtaCommand_Release(&command); + * rtaCommandOpenConnection_Release(&openCommand); + * + * // ... do work ... + * RtaCommandCloseConnection *closeCommand = rtaCommandCloseConnection_Create(pair[API_SIDE]); + * RtaCommand *command = rtaCommand_CreateCloseConnection(openCommand); + * _rtaTransport_SendCommandToFramework(transport, command); + * rtaCommand_Release(&command); + * rtaCommandCloseConnection_Release(&closeCommand); + * } + * @endcode + */ +RtaCommandOpenConnection *rtaCommandOpenConnection_Create(int stackId, int apiNotifierFd, int transportNotifierFd, const PARCJSON *config); + +/** + * Increase the number of references to a `RtaCommandOpenConnection`. + * + * Note that new `RtaCommandOpenConnection` is not created, + * only that the given `RtaCommandOpenConnection` reference count is incremented. + * Discard the reference by invoking `rtaCommandOpenConnection_Release`. + * + * @param [in] openConnection The RtaCommandDestroyProtocolStack to reference. + * + * @return non-null A reference to `openConnection`. + * @return null An error + * + * Example: + * @code + * { + * RtaCommandOpenConnection *openConnection = rtaCommandOpenConnection_Create(6, pair[API_SIDE], pair[TRANSPORT_SIDE], config); + * RtaCommandOpenConnection *second = rtaCommandOpenConnection_Acquire(openConnection); + * + * // release order does not matter + * rtaCommandOpenConnection_Release(&openConnection); + * rtaCommandOpenConnection_Release(&second); + * } + * @endcode + */ +RtaCommandOpenConnection *rtaCommandOpenConnection_Acquire(const RtaCommandOpenConnection *openConnection); + +/** + * Release a previously acquired reference to the specified instance, + * decrementing the reference count for the instance. + * + * The pointer to the instance is set to NULL as a side-effect of this function. + * + * If the invocation causes the last reference to the instance to be released, + * the instance is deallocated and the instance's implementation will perform + * additional cleanup and release other privately held references. + * + * @param [in,out] closePtr A pointer to the object to release, will return NULL'd. + * + * Example: + * @code + * { + * RtaCommandOpenConnection *openCommand = rtaCommandOpenConnection_Create(6, pair[API_SIDE], pair[TRANSPORT_SIDE], config); + * RtaCommand *command = rtaCommand_CreateOpenConnection(openCommand); + * _rtaTransport_SendCommandToFramework(transport, command); + * rtaCommand_Release(&command); + * rtaCommandOpenConnection_Release(&openCommand); + * } + * @endcode + */ +void rtaCommandOpenConnection_Release(RtaCommandOpenConnection **openPtr); + +/** + * Returns the Stack ID of the open command + * + * Returns the Stack ID parameter. + * + * @param [in] openConnection An allocated RtaCommandOpenConnection + * + * @return integer The value passed to rtaCommandOpenConnection_Create(). + * + * Example: + * @code + * { + * int stackId = 7; + * RtaCommandOpenConnection *openCommand = rtaCommandOpenConnection_Create(apiSocket, pair[API_SIDE], pair[TRANSPORT_SIDE], config); + * int testValue = rtaCommandOpenConnection_GetStackId(openCommand); + * assertTrue(testValue == stackId, "Wrong value got %d expected %d", testValue, stackId); + * rtaCommandOpenConnection_Release(&openCommand); + * } + * @endcode + */ +int rtaCommandOpenConnection_GetStackId(const RtaCommandOpenConnection *openConnection); + +/** + * Returns the API descriptor of the open command + * + * Returns the apiNotifierFd parameter. The API descriptor is the side read/written by the API. + * + * @param [in] openConnection An allocated RtaCommandOpenConnection + * + * @return integer The value passed to rtaCommandOpenConnection_Create(). + * + * Example: + * @code + * { + * int stackId = 7; + * RtaCommandOpenConnection *openCommand = rtaCommandOpenConnection_Create(apiSocket, pair[API_SIDE], pair[TRANSPORT_SIDE], config); + * int testValue = rtaCommandOpenConnection_GetApiNotifierFd(openCommand); + * assertTrue(testValue == pair[API_SIDE], "Wrong value got %d expected %d", testValue, pair[API_SIDE]); + * rtaCommandOpenConnection_Release(&openCommand); + * } + * @endcode + */ +int rtaCommandOpenConnection_GetApiNotifierFd(const RtaCommandOpenConnection *openConnection); + +/** + * Returns the Transport descriptor of the open command + * + * Returns the transportNotifierFd parameter. The transport descriptor is the side read/written by the Transport. + * + * @param [in] openConnection An allocated RtaCommandOpenConnection + * + * @return integer The value passed to rtaCommandOpenConnection_Create(). + * + * Example: + * @code + * { + * int stackId = 7; + * RtaCommandOpenConnection *openCommand = rtaCommandOpenConnection_Create(apiSocket, pair[API_SIDE], pair[TRANSPORT_SIDE], config); + * int testValue = rtaCommandOpenConnection_GetTransportNotifierFd(openCommand); + * assertTrue(testValue == pair[TRANSPORT_SIDE], "Wrong value got %d expected %d", testValue, pair[TRANSPORT_SIDE]); + * rtaCommandOpenConnection_Release(&openCommand); + * } + * @endcode + */ +int rtaCommandOpenConnection_GetTransportNotifierFd(const RtaCommandOpenConnection *openConnection); + +/** + * Returns the PARCJSON stack configuration of the create stack command + * + * Returns the JSON representation of the stack configuration. + * + * @param [in] createStack An allocated RtaCommandCreateProtocolStack + * + * @return The value passed to rtaCommandCreateProtocolStack_Create(). + * + * Example: + * @code + * { + * int stackId = 7; + * PARCJSON *config = createConnectionConfiguration(); + * RtaCommandOpenConnection *openCommand = rtaCommandOpenConnection_Create(apiSocket, pair[API_SIDE], pair[TRANSPORT_SIDE], config); + * PARCJSON *testValue = rtaCommandOpenConnection_GetConfig(openCommand); + * assertTrue(ccnxJson_Equals(config, testValue), "Wrong value"); + * rtaCommandOpenConnection_Release(&openCommand); + * parcJSON_Release(&config); + * } + * @endcode + */ +PARCJSON *rtaCommandOpenConnection_GetConfig(const RtaCommandOpenConnection *openConnection); +#endif // Libccnx_rta_CommandOpenConnection_h |