diff options
Diffstat (limited to 'libccnx-common/ccnx/common/ccnx_InterestPayloadId.h')
| -rwxr-xr-x | libccnx-common/ccnx/common/ccnx_InterestPayloadId.h | 518 |
1 files changed, 518 insertions, 0 deletions
diff --git a/libccnx-common/ccnx/common/ccnx_InterestPayloadId.h b/libccnx-common/ccnx/common/ccnx_InterestPayloadId.h new file mode 100755 index 00000000..cd3d6fce --- /dev/null +++ b/libccnx-common/ccnx/common/ccnx_InterestPayloadId.h @@ -0,0 +1,518 @@ +/* + * 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_InterestPayloadId.h + * @ingroup Naming + * @brief The basic CCNx InterestPayloadId. + * + * + */ +#ifndef libccnx_ccnx_InterestPayloadId_h +#define libccnx_ccnx_InterestPayloadId_h + +#include <parc/algol/parc_Buffer.h> +#include <ccnx/common/ccnx_NameSegment.h> +#include <ccnx/common/ccnx_Name.h> +//#include <parc/security/parc_CryptoHashType.h> + +struct ccnx_interest_payload_id; +/** + * @typedef CCNxInterestPayloadId + * @brief An RFC3986 URI compliant identifier in which each path segment carries a label. + */ +typedef struct ccnx_interest_payload_id CCNxInterestPayloadId; + + +typedef enum { + //RFC 6920 + CCNxInterestPayloadId_TypeCode_RFC6920_Reserved = 0x00, + CCNxInterestPayloadId_TypeCode_RFC6920_SHA256 = 0x01, //256 bits + CCNxInterestPayloadId_TypeCode_RFC6920_SHA256_128 = 0X02, //128 bits + CCNxInterestPayloadId_TypeCode_RFC6920_SHA256_120 = 0X03, //120 bits + CCNxInterestPayloadId_TypeCode_RFC6920_SHA256_96 = 0X04, //96 bits + CCNxInterestPayloadId_TypeCode_RFC6920_SHA256_64 = 0X05, //64 bits + CCNxInterestPayloadId_TypeCode_RFC6920_SHA256_32 = 0x06, //32 bits + //PARC + CCNxInterestPayloadId_TypeCode_App = 0x80, + CCNxInterestPayloadId_TypeCode_Nonce = 0x81 +} CCNxInterestPayloadId_TypeCode; + + +/** + * Create a new instance of a `CCNxInterestPayloadId` that uses the provided + * PARCBuffer as the ID. The instance is dynamically allocated and must be released by + * calling {@link ccnxInterestPayloadId_Release}. + * + * @param [in] data a PARCBuffer to be used as the body of the KeyId name segment. + * @param [in] type a uint8_t, nominally one of the CCNxInterestPayloadId_TypeCodes, + * which is prepended to the data. + * + * @return A pointer to a `CCNxInterestPayloadId` instance. + * + * Example: + * @code + * { + * PARCBuffer *somePaylaod = .... + * CCNxInterest *someInterest = .... + * + * PARCBuffer *buffer = parcBuffer_WrapCString("Key_42"); + * CCNxInterestPayloadId *interestPayloadId = + * ccnxInterestPayloadId_Create(data, InterestPayloadIdType_App); + * parcBuffer_Release(&buffer); + * + * ccnxInterest_SetPayloadAndId(someInterest, somePayload, interestPayloadId); + * ccnxInterestPayloadId_Release(&interestPayloadId); + * parcBuffer_Release(&somePayload); + * + * ... + * + * } + * @endcode + */ +CCNxInterestPayloadId * +ccnxInterestPayloadId_Create(const PARCBuffer *data, uint8_t type); + + +/** + * Create a new instance of a `CCNxInterestPayloadId` that is a sha256 hash of the + * input data. The instance is dynamically allocated and must be released by + * calling {@link ccnxInterestPayloadId_Release}. + * + * @param [in] data a PARCBuffer to be hashed to obtain the ID bytes. + * + * @return A pointer to a `CCNxInterestPayloadId` instance. + * + * Example: + * @code + * { + * PARCBuffer *somePaylaod = .... + * CCNxInterest *someInterest = .... + * + * CCNxInterestPayloadId *interestPayloadId = + * ccnxInterestPayloadId_CreateAsSHA256Hash(somePayload); + * + * ccnxInterest_SetPayloadAndId(someInterest, somePayload, interestPayloadId); + * ccnxInterestPayloadId_Release(&interestPayloadId); + * parcBuffer_Release(&somePayload); + * + * ... + * + * } + * @endcode + */ +CCNxInterestPayloadId * +ccnxInterestPayloadId_CreateAsSHA256Hash(const PARCBuffer *data); + +/** + * Create a new instance of a `CCNxInterestPayloadId` from an Interest Payload Id name + * segment if one is present in the provided {@link CCNxName}, otherwise return + * NULL. The instance is dynamically allocated and must be released by calling {@link + * ccnxInterestPayloadId_Release}. + * + * @param [in] name a CCNxName that may or may not carry an Interest Payload Id CCNxNameSegment. + * + * @return A pointer to a `CCNxInterestPayloadId` instance or NULL if no + * Interest-Payload-Id typed CCNxNameSegment is found. + * + * Example: + * @code + * { + * CCNxName *someName = ... + * + * CCNxInterestPayloadId *interestPayloadId = + * ccnxInterestPayloadId_CreateFromSegmentInName(someName); + * + * if (interestPayloadId != NULL) { + * .... + * ccnxInterestPayloadId_Release(&interestPayloadId); + * } + * + * ... + * + * ccnxName_Release(&someName); + * } + * @endcode + */ +CCNxInterestPayloadId * +ccnxInterestPayloadId_CreateFromSegmentInName(const CCNxName *name); + +/** + * Get a pointer to a CCNxNameSegment derived from the provided + * CCNxInterestPayloadId. There is no need to release the returned CCNxNameSegment + * object. + * + * @param [in] interestPayloadId A pointer to the `CCNxInterestPayloadId` instance. + * + * @return A pointer to a CCNxNameSegment. + * + * Example: + * @code + * { + * CCNxName *someName = ... + * + * CCNxInterestPayloadId *interestPayloadId = + * ccnxInterestPayloadId_CreateFromSegmentInName(someName); + * + * if (interestPayloadId != NULL) { + * CCNxNameSegmemt *nameSegment = ccnxInterestPayloadId_GetNameSegment(interestPayloadId); + * .... + * ccnxInterestPayloadId_Release(&interestPayloadId); + * } + * + * ... + * + * ccnxName_Release(&someName); + * } + * @endcode + */ +const CCNxNameSegment * +ccnxInterestPayloadId_GetNameSegment(const CCNxInterestPayloadId *interestPayloadId); + +/** + * Get the CCNxInterestPayloadId's value as a PARCBuffer. There is no need to release + * the returned PARCBuffer object. + * + * @param [in] interestPayloadId A pointer to the `CCNxInterestPayloadId` instance. + * + * @return A pointer to a PARCBuffer object containing the Id bytes. + * + * Example: + * @code + * { + * CCNxName *someName = ... + * + * CCNxInterestPayloadId *interestPayloadId = + * ccnxInterestPayloadId_CreateFromSegmentInName(someName); + * + * if (interestPayloadId != NULL) { + * PARCBuffer *ipIdValue = ccnxInterestPayloadId_GetValue(interestPayloadId); + * .... + * ccnxInterestPayloadId_Release(&interestPayloadId); + * } + * + * ... + * + * ccnxName_Release(&someName); + * } + * @endcode + */ +PARCBuffer * +ccnxInterestPayloadId_GetValue(const CCNxInterestPayloadId *interestPayloadId); + +/** + * Get the CCNxInterestPayloadId's uint8 type. + * + * @param [in] interestPayloadId A pointer to the `CCNxInterestPayloadId` instance. + * + * @return A uint8_t containing the type value. + * + * Example: + * @code + * { + * CCNxName *someName = ... + * + * CCNxInterestPayloadId *interestPayloadId = + * ccnxInterestPayloadId_CreateFromSegmentInName(someName); + * + * if (interestPayloadId != NULL) { + * uint8_t type = ccnxInterestPayloadId_GetType(interestPayloadId); + * .... + * ccnxInterestPayloadId_Release(&interestPayloadId); + * } + * + * ... + * + * ccnxName_Release(&someName); + * } + * @endcode + */ +uint8_t +ccnxInterestPayloadId_GetType(const CCNxInterestPayloadId *interestPayloadId); + +/** + * Increase the number of references to a `CCNxInterestPayloadId` instance. + * + * Note that a new `CCNxInterestPayloadId` is not created, only that the given + * `CCNxInterestPayloadId` reference count is incremented. Discard the reference by + * invoking {@link ccnxInterestPayloadId_Release}. + * + * @param [in] interestPayloadId A pointer to the original `CCNxInterestPayloadId`. + * + * @return The value of the input parameter @p interestPayloadId. + * + * Example: + * @code + * { + * CCNxInterestPayloadId *original = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * + * CCNxInterestPayloadId *reference = ccnxInterestPayloadId_Acquire(original); + * + * ccnxInterestPayloadId_Release(&original); + * ccnxInterestPayloadId_Release(&reference); //Triggers final cleanup + * } + * @endcode + * + * @see ccnxInterestPayloadId_Release + */ +CCNxInterestPayloadId * +ccnxInterestPayloadId_Acquire(const CCNxInterestPayloadId *interestPayloadId); + +/** + * 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] interestPayloadIdP A pointer to a pointer to the instance to release. + * + * Example: + * @code + * { + * CCNxInterestPayloadId *interestPayloadId = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * + * ccnxInterestPayloadId_Release(&interestPayloadId); + * } + * @endcode + * + * @see {@link ccnxInterestPayloadId_Acquire} + */ +void +ccnxInterestPayloadId_Release(CCNxInterestPayloadId **interestPayloadIdP); + +/** + * Assert that an instance of `CCNxInterestPayloadId` 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 behavior. This may include the + * validation of internal instances of types. + * + * @param [in] interestPayloadId A pointer to a `CCNxInterestPayloadId` instance. + * + * Example: + * @code + * { + * CCNxInterestPayloadId *interestPayloadId = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * + * ccnxInterestPayloadId_AssertValid(interestPayloadId); + * + * ccnxInterestPayloadId_Release(&interestPayloadId); + * } + * @endcode + */ +void +ccnxInterestPayloadId_AssertValid(const CCNxInterestPayloadId *interestPayloadId); + +/** + * Determine if an instance of `CCNxInterestPayloadId` is valid. + * + * Valid means the internal state of the type is consistent with its required current + * or future behavior. This may include the validation of internal instances of + * types. + * + * @param [in] interestPayloadId A pointer to a `CCNxInterestPayloadId` instance. + * + * @return true If the instance is valid. + * @return false if the instance is not valid. + * + * Example: + * @code + * { + * CCNxInterestPayloadId *interestPayloadId = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * + * if (ccnxInterestPayloadId_IsValid(interestPayloadId) == true) { + * ... + * } + * + * ccnxInterestPayloadId_Release(&interestPayloadId); + * } + * @endcode + */ +bool +ccnxInterestPayloadId_IsValid(const CCNxInterestPayloadId *interestPayloadId); + +/** + * Produce a null-terminated string representation of the specified instance. The + * non-null result must be freed by the caller via {@link parcMemory_Deallocate}. + * + * @param [in] interestPayloadId A pointer to the `CCNxInterestPayloadId` instance. + * + * @return NULL Cannot allocate memory. + * @return non-NULL A pointer to an allocated, null-terminated C string that must be + * deallocated via `parcMemory_Deallocate()`. + * + * Example: + * @code + * { + * CCNxInterestPayloadId *instance = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * + * char *string = ccnxInterestPayloadId_ToString(instance); + * + * if (string != NULL) { + * printf("Hello: %s\n", string); + * parcMemory_Deallocate(string); + * } else { + * printf("Cannot allocate memory\n"); + * } + * + * ccnxInterestPayloadId_Release(&instance); + * } + * @endcode + */ +char * +ccnxInterestPayloadId_ToString(const CCNxInterestPayloadId *interestPayloadId); + +/** + * Create a copy of the specified `CCNxInterestPayloadId` instance, producing a new, + * independent, instance from dynamically allocated memory. This a deep copy, all + * referenced memory is copied. The created instance of `CCNxInterestPayloadId` must be + * released by calling {@link ccnxInterestPayloadId_Release}(). + * + * @param [in] interestPayloadId The `CCNxInterestPayloadId` to copy + * + * @return A new, independent copy of the given `CCNxInterestPayloadId`. + * + * Example: + * @code + * { + * CCNxInterestPayloadId *interestPayloadId = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * CCNxInterestPayloadId *copy = ccnxInterestPayloadId_Copy(interestPayloadId); + * + * ... + * + * ccnxInterestPayloadId_Release(&interestPayloadId); + * ccnxInterestPayloadId_Release(©); + * } + * @endcode + */ +CCNxInterestPayloadId * +ccnxInterestPayloadId_Copy(const CCNxInterestPayloadId *interestPayloadId); + +/** + * Determine if two `CCNxInterestPayloadId` instances are equal. + * + * The following equivalence relations on non-null `CCNxInterestPayloadId` instances are maintained: + * + * * It is reflexive: for any non-null reference value x, `ccnxInterestPayloadId_Equals(x, x)` must return true. + * + * * It is symmetric: for any non-null reference values x and y, `ccnxInterestPayloadId_Equals(x, y)` must return true if and only if + * `ccnxInterestPayloadId_Equals(y, x)` returns true. + * + * * It is transitive: for any non-null reference values x, y, and z, if + * `ccnxInterestPayloadId_Equals(x, y)` returns true and + * `ccnxInterestPayloadId_Equals(y, z)` returns true, + * then `ccnxInterestPayloadId_Equals(x, z)` must return true. + * + * * It is consistent: for any non-null reference values x and y, multiple invocations of `ccnxInterestPayloadId_Equals(x, y)` + * consistently return true or consistently return false. + * + * * For any non-null reference value x, `ccnxInterestPayloadId_Equals(x, NULL)` must return false. + * + * @param [in] interestPayloadId1 A pointer to a `CCNxInterestPayloadId` instance. + * @param [in] interestPayloadId2 A pointer to a `CCNxInterestPayloadId` instance. + * + * @return True If the given `CCNxInterestPayloadId` instances are equal + * @return False Otherwise + * + * Example: + * @code + * { + * CCNxInterestPayloadId *a = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * CCNxInterestPayloadId *b = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * + * if (ccnxInterestPayloadId_Equals(a, b)) { + * // true + * } else { + * // false + * } + * ccnxInterestPayloadId_Release(&a); + * ccnxInterestPayloadId_Release(&b); + * } + * @endcode + * + * @see {@link ccnxInterestPayloadId_Compare} + */ +bool +ccnxInterestPayloadId_Equals(const CCNxInterestPayloadId *interestPayloadId1, const CCNxInterestPayloadId *interestPayloadId2); + +/** + * Compare @p interestPayloadId1 to @p interestPayloadId2 using CCNx canonical ordering (shortlex). + * + * `NULL` is considered the shortest interestPayloadId, so `(NULL, non-NULL) -> -1` and + * `(NULL, NULL) -> 0`, `(non-NULL, NULL) -> +1`. + * + * @param [in] interestPayloadId1 A pointer to a `CCNxInterestPayloadId` instance. + * @param [in] interestPayloadId2 A pointer to a `CCNxInterestPayloadId` instance. + * + * Returns: + * <ul> + * <li>-1 for interestPayloadId1 < interestPayloadId2</li> + * <li> 0 for interestPayloadId1 = interestPayloadId2</li> + * <li>+1 for interestPayloadId1 > interestPayloadId2</li> + * </ul> + * + * Example: + * @code + * { + * CCNxInterestPayloadId *a = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * CCNxInterestPayloadId *b = ccnxInterestPayloadId_CreateAsSHA256Hash(...); + * + * if (ccnxInterestPayloadId_Compare(a, b) == 0) { + * ... + * } + * + * ccnxInterestPayloadId_Release(&a); + * ccnxInterestPayloadId_Release(&b); + * } + * @endcode + * + * @see {@link ccnxInterestPayloadId_Equals} + */ +int +ccnxInterestPayloadId_Compare(const CCNxInterestPayloadId *interestPayloadId1, const CCNxInterestPayloadId *interestPayloadId2); + +/** + * Retrieve the hashcode of the CCNxInterestPayloadId. + * + * @param [in] id A pointer to a `CCNxINterestPayloadId` instance. + * + * @return uint32_t The hashcode + * + * Example: + * @code + * { + * CCNxName *someName = ... + * + * CCNxInterestPayloadId *interestPayloadId = + * ccnxInterestPayloadId_CreateFromSegmentInName(someName); + * + * if (interestPayloadId != NULL) { + * uint32_t hashcode = ccnxInterestPayloadId_HashCode(interestPayloadId); + * .... + * ccnxInterestPayloadId_Release(&interestPayloadId); + * } + * + * ... + * + * ccnxName_Release(&someName); + * } + * @endcode + */ +uint32_t +ccnxInterestPayloadId_HashCode(const CCNxInterestPayloadId *id); +#endif // libccnx_ccnx_InterestPayloadId_h |