aboutsummaryrefslogtreecommitdiffstats
path: root/libccnx-common/ccnx/common/ccnx_InterestReturn.h
diff options
context:
space:
mode:
authorLuca Muscariello <lumuscar+fdio@cisco.com>2017-02-23 20:44:26 +0100
committerLuca Muscariello <lumuscar+fdio@cisco.com>2017-02-23 19:51:14 +0000
commitd18ae43123fcd7604d1c36a1ec8450dbe6071824 (patch)
tree2d49fc3aabd0f2607251c854565648d47b56b2e9 /libccnx-common/ccnx/common/ccnx_InterestReturn.h
parent9b30fc10fb1cbebe651e5a107e8ca5b24de54675 (diff)
Initial commit: ccnxlibs.
Change-Id: I1b376527a7dd01a6b9e083a6cb646955902f45c0 Signed-off-by: Luca Muscariello <lumuscar+fdio@cisco.com>
Diffstat (limited to 'libccnx-common/ccnx/common/ccnx_InterestReturn.h')
-rwxr-xr-xlibccnx-common/ccnx/common/ccnx_InterestReturn.h299
1 files changed, 299 insertions, 0 deletions
diff --git a/libccnx-common/ccnx/common/ccnx_InterestReturn.h b/libccnx-common/ccnx/common/ccnx_InterestReturn.h
new file mode 100755
index 00000000..44bb48aa
--- /dev/null
+++ b/libccnx-common/ccnx/common/ccnx_InterestReturn.h
@@ -0,0 +1,299 @@
+/*
+ * 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 ccnx_InterestReturn.h
+ * @ingroup InterestRetrun
+ * @brief A CCNx InterestReturn is an optional error response for an Interest that can't be satisfied by the returning entity
+ *
+ * An InterestReturn is a convience type for a returned Interest. It is created from an CCNxInterest and a return code
+ * with the intent of returning the interest to the previous hop. Other than modifing the PacketType to indicate that it
+ * is a Interest Return, it wraps and preserves the state of the provided CCNxInterest and can be used with CCNxInterest
+ * functions as if it were a CCNxInterest type.
+ *
+ * The possible return codes are:
+ *
+ * +--------------------+
+ * | No Route |
+ * | |
+ * | Hop Limit Exceeded |
+ * | |
+ * | No Resources |
+ * | |
+ * | Path Error |
+ * | |
+ * | Prohibited |
+ * | |
+ * | Congested |
+ * | |
+ * | MTU too large |
+ * +--------------------+
+ *
+ * @see {@link CCNxInterest}
+ *
+ */
+
+#ifndef libccnx_ccnx_InterestReturn_h
+#define libccnx_ccnx_InterestReturn_h
+
+#include <ccnx/common/internal/ccnx_TlvDictionary.h>
+#include <ccnx/common/ccnx_Interest.h>
+
+/**
+ * @typedef CCNxInterestReturn
+ * @brief The CCNx InterestReturn Message
+ */
+typedef CCNxTlvDictionary CCNxInterestReturn;
+
+/**
+ * @typedef CCNxInterestReturn_ReturnCode
+ * @brief The CCNx InterestReturn ReturnCode options
+ */
+typedef enum {
+ CCNxInterestReturn_ReturnCode_NoRoute = 1,
+ CCNxInterestReturn_ReturnCode_HopLimitExceeded = 2,
+ CCNxInterestReturn_ReturnCode_NoResources = 3,
+ CCNxInterestReturn_ReturnCode_PathError = 4,
+ CCNxInterestReturn_ReturnCode_Prohibited = 5,
+ CCNxInterestReturn_ReturnCode_Congestion = 6,
+ CCNxInterestReturn_ReturnCode_MTUTooLarge = 7,
+ CCNxInterestReturn_ReturnCode_END = 8
+} CCNxInterestReturn_ReturnCode;
+
+/**
+ * Create a new instance of `CCNxInterestRetrun` from the specified CCNxInterest, with the specified return code.
+ *
+ * The created instance of `CCNxInterestReturn` must be released by calling {@link ccnxInterestReturn_Release}().
+ *
+ * @param [in] interest A pointer to the {@link CCNxInterest} to be returned.
+ * @param [in] returnCode The {@link CCNxInterestReturn_ReturnCode} to return.
+ *
+ * @return A new instance of a `CCNxInterestReturn`.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxInterest *interest = ...
+ *
+ * CCNxInterestReturn *interestToReturn = ccnxInterest_Create(interest, CCNxInterestReturn_ReturnCode_NoRoute);
+ *
+ * ...
+ *
+ * ccnxInterestReturn_Release(&interestToReturn);
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxInterestReturn_Release}
+ */
+CCNxInterestReturn *
+ccnxInterestReturn_Create(const CCNxInterest *interest, CCNxInterestReturn_ReturnCode returnCode);
+
+
+/**
+ * Retrieve the specified `CCNxInterestReturn`'s {@link CCNxInterestReturn_ReturnCode}
+ *
+ * @return The return code for the specified CCNxInterestReturn.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxInterest *interest = ccnxInterest_CreateSimple(...);
+ * CCNxInterestReturn *interestReturn = ccnxInterestReturn_Create(interest, CCNxInterestReturn_ReturnCode_NoRoute);
+ *
+ * ...
+ *
+ * CCNxInterestReturn_ReturnCode returnCode = ccnxInterest_GetReturnCode(interestReturn);
+ *
+ * ...
+ *
+ * ccnxInterestReturn_Release(&interestReturn);
+ * }
+ * @endcode
+ *
+ */
+CCNxInterestReturn_ReturnCode
+ccnxInterestReturn_GetReturnCode(const CCNxInterestReturn *interestReturn);
+
+
+// Canonocal
+/**
+ * Increase the number of references to a `CCNxInterestReturn`.
+ *
+ * Note that a new `CCNxInterestReturn` is not created,
+ * only that the given `CCNxInterestReturn` reference count is incremented.
+ * Discard the reference by invoking {@link ccnxInterestReturn_Release}.
+ *
+ * @param [in] instance A pointer to the original instance.
+ * @return The value of the input parameter @p instance.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxInterestReturn *reference = ccnxInterestReturn_Acquire(interestReturn);
+ *
+ * ...
+ *
+ * ccnxInterestReturn_Release(&reference);
+ *
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxInterestReturn_Release}
+ */
+
+CCNxInterestReturn *
+ccnxInterestReturn_Acquire(const CCNxInterestReturn *instance);
+
+/**
+ * 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] instanceP A pointer to a pointer to the instance to release.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxInterestReturn *reference = ccnxInterestReturn_Acquire(contentObject);
+ *
+ * ...
+ *
+ * ccnxInterestReturn_Release(&reference);
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxInterestReturn_Acquire}
+ */
+void
+ccnxInterestReturn_Release(CCNxInterestReturn **instanceP);
+
+/**
+ * Determine if two `CCNxInterestReturn` instances are equal.
+ *
+ * The following equivalence relations on non-null `CCNxInterestReturn` instances are maintained:
+ *
+ * * It is reflexive: for any non-null reference value x, `ccnxInterestReturn_Equals(x, x)`
+ * must return true.
+ *
+ * * It is symmetric: for any non-null reference values x and y,
+ * `ccnxInterestReturn_Equals(x, y)` must return true if and only if
+ * `ccnxInterestReturn_Equals(y, x)` returns true.
+ *
+ * * It is transitive: for any non-null reference values x, y, and z, if
+ * `ccnxInterestReturn_Equals(x, y)` returns true and
+ * `ccnxInterestReturn_Equals(y, z)` returns true,
+ * then `ccnxInterestReturn_Equals(x, z)` must return true.
+ *
+ * * It is consistent: for any non-null reference values x and y, multiple
+ * invocations of `ccnxInterestReturn_Equals(x, y)` consistently return true or
+ * consistently return false.
+ *
+ * * For any non-null reference value x, `ccnxInterestReturn_Equals(x, NULL)` must
+ * return false.
+ *
+ * @param interestReturnA A pointer to a `CCNxInterestReturn` instance.
+ * @param interestReturnB A pointer to a `CCNxInterestReturn` instance.
+ * @return true if the two `CCNxInterestReturn` instances are equal.
+ *
+ * Example:
+ * @code
+ * {
+ *
+ * CCNxInterestReturn *interestReturnA = ccnxInterestReturn_Create(interestA, CCNxInterestReturn_ReturnCode_NoRoute);
+ * CCNxInterestReturn *interestReturnB = ccnxInterestReturn_Create(interestA, CCNxInterestReturn_ReturnCode_NoRoute); // same as A
+ * CCNxInterestReturn *interestReturnC = ccnxInterestReturn_Create(interestA, CCNxInterestReturn_ReturnCode_HopLimitExceeded ); // different
+ *
+ * if (ccnxInterestReturn_Equals(interestReturnA, interestReturnB)) {
+ * // this is expected...
+ * }
+ *
+ * if (ccnxInterestReturn_Equals(interestReturnA, interestReturnC)) {
+ * // this is NOT expected
+ * }
+ *
+ * ...
+ *
+ * ccnxInterestReturn_Release(&interestReturnA);
+ * ccnxInterestReturn_Release(&interestReturnB);
+ * ccnxInterestReturn_Release(&interestReturnC);
+ * }
+ * @endcode
+ */
+bool
+ccnxInterestReturn_Equals(const CCNxInterestReturn *a, const CCNxInterestReturn *b);
+
+/**
+ * Produce a null-terminated string representation of the specified instance.
+ *
+ * The result must be freed by the caller via {@link parcMemory_Deallocate()}.
+ *
+ * @param [in] interestReturn A pointer to the instance.
+ *
+ * @return NULL Cannot allocate memory.
+ * @return non-NULL A pointer to an allocated, nul-terminated C string that must be deallocated via `parcMemory_Deallocate()`.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxInterestReturn *interestReturn = ccnxInterestReturn_Create(...);
+ *
+ * char *string = ccnxInterestReturn_ToString(interestReturn);
+ *
+ * if (string != NULL) {
+ * printf("InterestReturn looks like: %s\n", string);
+ * parcMemory_Deallocate(string);
+ * } else {
+ * printf("Cannot allocate memory\n");
+ * }
+ *
+ * ccnxInterestReturn_Release(&instance);
+ * }
+ * @endcode
+ *
+ */
+char *
+ccnxInterestReturn_ToString(const CCNxInterestReturn *interestReturn);
+
+/**
+ * Assert that an instance of `CCNxInterestReturn` is valid.
+ *
+ * If the instance is not valid, terminate via {@link trapIllegalValue}
+ *
+ * Valid means the internal state of the type is consistent with its
+ * required current or future behaviour.
+ * This may include the validation of internal instances of types.
+ *
+ * @param [in] interestReturn A pointer to the instance to check.
+ *
+ * Example:
+ * @code
+ * {
+ * CCNxInterestReturn *interestReturn = ccnxInterest_Create(...);
+ * ccnxInterestReturn_AssertValid(interestReturn);
+ *
+ * ...
+ *
+ * ccnxInterestReturn_Release(&instance);
+ * }
+ * @endcode
+ */
+void
+ccnxInterestReturn_AssertValid(const CCNxInterestReturn *interestReturn);
+#endif //libccnx_ccnx_InterestReturn_h