diff options
Diffstat (limited to 'libccnx-common/ccnx/common/ccnx_InterestReturn.h')
| -rwxr-xr-x | libccnx-common/ccnx/common/ccnx_InterestReturn.h | 299 |
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 |