1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
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
|
