aboutsummaryrefslogtreecommitdiffstats
path: root/libccnx-transport-rta/ccnx/api/notify/notify_Status.h
diff options
context:
space:
mode:
Diffstat (limited to 'libccnx-transport-rta/ccnx/api/notify/notify_Status.h')
-rw-r--r--libccnx-transport-rta/ccnx/api/notify/notify_Status.h345
1 files changed, 345 insertions, 0 deletions
diff --git a/libccnx-transport-rta/ccnx/api/notify/notify_Status.h b/libccnx-transport-rta/ccnx/api/notify/notify_Status.h
new file mode 100644
index 00000000..3fcdcb1d
--- /dev/null
+++ b/libccnx-transport-rta/ccnx/api/notify/notify_Status.h
@@ -0,0 +1,345 @@
+/*
+ * 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 notify_Status.h
+ *
+ * @brief
+ * An API to handle notifications from the Transport.
+ *
+ * These notifications are specific to the RTA Transport, in that they use the Component model and Component names.
+ *
+ */
+#ifndef Libccnx_notifyStatus_h
+#define Libccnx_notifyStatus_h
+
+#include <parc/algol/parc_JSON.h>
+#include <ccnx/common/ccnx_Name.h>
+
+struct notify_status;
+/**
+ * @typedef NotifyStatus
+ * @brief Notifications from Transport
+ */
+typedef struct notify_status NotifyStatus;
+
+// This needs to be replaced with a more sophisticated encoding scheme that individual stack components can use. Case 1035
+/**
+ * @typedef NotifyStatusCode
+ * @brief Codes for Notify Status
+ */
+typedef enum {
+ // TRANSPORT_READY = 1, // returned when Transport_Create finished
+ // TRANSPORT_DESTROYED = 2, // when Transport_Destroy is done
+ notifyStatusCode_OPEN_ERROR = 3, // error when opening a connection stack
+ notifyStatusCode_CONNECTION_OPEN = 4, // returned when a connection is opened
+ notifyStatusCode_CONNECTION_CLOSED = 5, // returned when close is finished
+ notifyStatusCode_FORWARDER_NOT_AVAILABLE = 6, // connection problem with forwarder
+ notifyStatusCode_FLOW_CONTROL_STARTED = 7, // when flow control starts on a name
+ notifyStatusCode_FLOW_CONTROL_FINISHED = 8, // after final block is passed up
+ notifyStatusCode_FLOW_CONTROL_ERROR = 9, // some hard error on the name
+ notifyStatusCode_ENCODING_ERROR = 10, // something bad in the codec
+ notifyStatusCode_SIGNING_ERROR = 11, // error signing
+ notifyStatusCode_SEND_ERROR = 12, // some other "down" stack error
+} NotifyStatusCode;
+
+/**
+ * @typedef NotifyStatusDirection
+ * @brief The direction of the NotifyStatus
+ */
+typedef enum {
+ notifyStatusDirection_UPSTACK,
+ notifyStatusDirection_DOWNSTACK
+} NotifyStatusDirection;
+
+/**
+ * Create an instance of `NotifyStatus`.
+ *
+ * @param [in] apiFd The corresponding api file descriptor.
+ * @param [in] code The NotifyStatusCode for this status.
+ * @param [in] name An associated CCNxName
+ * @param [in] message An (optional) string message
+ *
+ * @return NULL An error occurred
+ * @return non-NULL A pointer to a valid NotifyStatus instance that must be released via notifyStatus_Release().
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *expected = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ * }
+ * @endcode
+ *
+ * @see {@link notifyStatus_Release}
+ */
+NotifyStatus *notifyStatus_Create(int apiFd, NotifyStatusCode code, CCNxName *name, const char *message);
+
+/**
+ * Increase the number of references to a `NotifyStatus`.
+ *
+ * Note that new `NotifyStatus` is not created,
+ * only that the given `NotifyStatus` reference count is incremented.
+ * Discard the reference by invoking {@link notifyStatus_Release}.
+ *
+ * @param [in] status A pointer to a `NotifyStatus` instance.
+ * @return The input `NotifyStatus` pointer.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * NotifyStatus *x_2 = notifyStatus_Acquire(status);
+ *
+ * notifyStatus_Release(&status);
+ * notifyStatus_Release(&x_2);
+ * }
+ * @endcode
+ */
+NotifyStatus *notifyStatus_Acquire(const NotifyStatus *status);
+
+/**
+ * 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] statusPtr A pointer to a pointer to the instance to release.
+ *
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * notifyStatus_Release(&status);
+ * }
+ * @endcode
+ */
+void notifyStatus_Release(NotifyStatus **statusPtr);
+
+/**
+ * Returns true if contents of two NotifyStatus objects are the same.
+ *
+ * @param [in] x object 1
+ * @param [in] y object 2
+ *
+ * @return true X & Y are equal
+ * @return false X & Y are not equal
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status1 = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ * NotifyStatus *status2 = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * if (notifyStatus_Equals(status1, status2)) {
+ * ...
+ * }
+ * }
+ * @endcode
+ */
+bool notifyStatus_Equals(const NotifyStatus *x, const NotifyStatus *y);
+
+/**
+ * Print a human readable representation of the given `NotifyStatus`.
+ *
+ * @param [in] status A pointer to the instance to display.
+ * @param [in] indentation The level of indentation to use to pretty-print the output.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * notifyStatus_Display(status, 0);
+ *
+ * notifyStatus_Release(&status);
+ * }
+ * @endcode
+ */
+void notifyStatus_Display(const NotifyStatus *status, int indentation);
+
+/**
+ * Get the associated file descriptor of the given `NotifyStatus` instance.
+ *
+ * @param [in] status A pointer to a valid instance of `NotifyStatus`.
+ *
+ * @return The associated file descriptor of this NotifyStatus instance.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * int fd = notifyStatus_GetFiledes(status);
+ * }
+ * @endcode
+ */
+int notifyStatus_GetFiledes(const NotifyStatus *status);
+
+/**
+ * Get the associated {@link NotifyStatusCode} of the given `NotifyStatus` instance.
+ *
+ * @param [in] status A pointer to a valid instance of `NotifyStatus`.
+ *
+ * @return The associated NotifyStatusCode of the given `NotifyStatus` instance.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * NotifyStatusCode code = notifyStatus_GetStatusCode(status);
+ * }
+ * @endcode
+ */
+NotifyStatusCode notifyStatus_GetStatusCode(const NotifyStatus *status);
+
+/**
+ * Get the associated {@link CCNxName} of the given `NotifyStatus` instance.
+ *
+ * @param [in] status A pointer to a valid instance of `NotifyStatus`.
+ *
+ * @return The `CCNxName` of this `NotifyStatus` instance.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * NotifyStatusCode code = notifyStatus_GetStatusCode(status);
+ * }
+ * @endcode
+ */
+CCNxName *notifyStatus_GetName(const NotifyStatus *status);
+
+/**
+ * Get the associated {@link CCNxName} of the given `NotifyStatus` instance.
+ *
+ * @param [in] status A pointer to a valid instance of `NotifyStatus`.
+ *
+ * @return The message of this NotifyStatus instance.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * NotifyStatusCode code = notifyStatus_GetStatusCode(status);
+ * }
+ * @endcode
+ */
+char *notifyStatus_GetMessage(const NotifyStatus *status);
+
+/**
+ * Return a {@link PARCJSON} representation of the given `NotifyStatus` instance.
+ *
+ * @param [in] status A pointer to a valid instance of `NotifyStatus`.
+ *
+ * @return NULL An error occurred
+ * @return non-NULL A pointer to a valid `PARCJSON` instance
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * PARCJSON *json = notifyStatus_ToJSON(status);
+ * }
+ * @endcode
+ */
+PARCJSON *notifyStatus_ToJSON(const NotifyStatus *status);
+
+/**
+ * Create a new `NotifyStatus` instance from a {@link PARCJSON} instance.
+ *
+ * @param [in] json A pointer to a `PARCJSON` instance.
+ *
+ * @return NULL An error occurred
+ * @return non-NULL A pointer to a valid `NotifyStatus` instance.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * PARCJSON *json = notifyStatus_ToJSON(status);
+ *
+ * NotifyStatus *status2 = notifyStatus_ParseJSON(json)
+ * }
+ * @endcode
+ */
+NotifyStatus *notifyStatus_ParseJSON(const PARCJSON *json);
+
+/**
+ * Evaluate to `true` if the given `NotifyStatus` indicates a Connection Open.
+ *
+ * @param [in] status A pointer to a `NotifyStatus` instance.
+ *
+ * @return `true` The given `NotifyStatus` indicates a Connection open.
+ * @return `false` The given ``NotifyStatus` indicates that the Connection is not open.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * if (notifyStatus_IsConnectionOpen(status)) {
+ * printf("Connection is open\n");
+ * }
+ * }
+ * @endcode
+ */
+bool notifyStatus_IsConnectionOpen(const NotifyStatus *status);
+
+/**
+ * Return `true` if the given status indicates that the flow control has started.
+ *
+ * @param [in] status A pointer to a NotifyStatus instance.
+ *
+ * @return `true` The given `NotifyStatu`s indicates that flow controller has started
+ * @return `false` The given `NotifyStatus` indicates that the flow controller has not started.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxName *name = ccnxName_CreateFromCString("lci:/a/b/c");
+ * NotifyStatus *status = notifyStatus_Create(1, notifyStatus_CONNECTION_OPEN, name, "Good to go");
+ *
+ * if (notifyStatus_IsFlowControlStarted(status)) {
+ * printf("Flow controller has started\n");
+ * }
+ * }
+ * @endcode
+ */
+bool notifyStatus_IsFlowControlStarted(const NotifyStatus *status);
+#endif // Libccnx_notifyStatus_h