diff options
Diffstat (limited to 'libccnx-common/ccnx/common/ccnx_Interest.h')
| -rwxr-xr-x | libccnx-common/ccnx/common/ccnx_Interest.h | 807 |
1 files changed, 807 insertions, 0 deletions
diff --git a/libccnx-common/ccnx/common/ccnx_Interest.h b/libccnx-common/ccnx/common/ccnx_Interest.h new file mode 100755 index 00000000..20dd5c53 --- /dev/null +++ b/libccnx-common/ccnx/common/ccnx_Interest.h @@ -0,0 +1,807 @@ +/* + * 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_Interest.h + * @ingroup Interest + * @brief A CCNx Interest expresses an interest in a piece of named data. + * + * The canonical CCN Interest. An Interest contains a {@link CCNxName}, + * the desired payload, and two optional restrictions (ContentObjectHash and + * KeyId) to limit responses + * to a specific publisher or a specific Content Object. + * + * @see {@link CCNxContentObject} + * @see {@link CCNxName} + * + */ + +#ifndef libccnx_ccnx_Interest_h +#define libccnx_ccnx_Interest_h + +#include <ccnx/common/internal/ccnx_TlvDictionary.h> +#include <ccnx/common/internal/ccnx_InterestInterface.h> + +/** + * @typedef CCNxInterest + * @brief The CCNx Interest Message + */ + +typedef CCNxTlvDictionary CCNxInterest; + +/** + * Create a new instance of `CCNxInterest` for the specified name, with the specified lifetime and + * publisher's key digest, using the specified {@link CCNxInterestInterface}, using dynamically allocated memory. + * + * The name and key digest are used for matching against ContentObjects. If the specified key digest is NULL, + * this Interest will match against any ContentObject with the same name (regardless of whether the + * ContentObject has matching key digest). If the specified key digest is NOT NULL, then this Interest + * will match only against any ContentObject with both the same name and the same key digest. The key digest + * comparison test is a simple buffer comparison. + * + * The lifetime, specified in milliseconds, is a hint to the system how long the application is + * willing to wait for a response before it will re-send the same Interest. It is used by forwarders as a + * guideline on how long they should attempt to keep the Interest alive in their tables. It is not a guarantee + * that they will do so, however. + * + * The created instance of `CCNxInterest` must be released by calling {@link ccnxInterest_Release}(). + * + * @param [in] implementation A pointer to the {@link CCNxInterestInterface} to be used to build this Interest. + * @param [in] name A pointer to a {@link CCNxName} expressing the name of the content you are interested in. + * @param [in] lifetime A `uint32_t` specifying the number of milliseconds the application + * will wait before re-sending the Interest. + * @param [in] keyId A pointer to a {@link PARCBuffer} containing a key digest that should be matched + * against ContentObjects whose names match our specified name. This value may be NULL and, if so, will + * not be used in the matching process. + * @param [in] contentObjectHash A pointer to a `PARCBuffer` containing the hash of the ContentObject that is expected + * to be returned in response to this Interest. + * + * @return A new instance of a `CCNxInterest`. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/temp/2"); + * + * PARCBuffer *keyId = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(keyId, 1234L); + * + * uint32_t lifetime = CCNxInterestDefaultLifetimeMilliseconds; + * + * CCNxInterest *interest = ccnxInterest_CreateWithImpl(&CCNxInterestFacadeV1_Implementation, + * name, lifetime, keyId, NULL); + * + * ... + * + * parcBuffer_Release(&keyId); + * ccnxName_Release(&name); + * ccnxInterest_Release(&interest); + * } + * @endcode + * + * @see {@link ccnxInterest_Release} + */ +CCNxInterest *ccnxInterest_CreateWithImpl(const CCNxInterestInterface *implementation, + const CCNxName *name, + const uint32_t interestLifetime, + const PARCBuffer *keyId, + const PARCBuffer *contentObjectHash, + const uint32_t hopLimit); + +/** + * Create a new instance of `CCNxInterest` for the specified name, with the specified lifetime and + * publisher's key digest, using dynamically allocated memory. + * + * The name and key digest are used for matching against ContentObjects. If the specified key digest is NULL, + * this Interest will match against any ContentObject with the same name (regardless of whether the + * ContentObject has matching key digest). If the specified key digest is NOT NULL, then this Interest + * will match only against any ContentObject with both the same name and the same key digest. The key digest + * comparison test is a simple buffer comparison. + * + * The lifetime, specified in milliseconds, is a hint to the system how long the application is + * willing to wait for a response before it will re-send the same Interest. It is used by forwarders as a + * guideline on how long they should attempt to keep the Interest alive in their tables. It is not a guarantee + * that they will do so, however. + * + * The created instance of `CCNxInterest` must be released by calling {@link ccnxInterest_Release}(). + * + * @param [in] name A pointer to a {@link CCNxName} expressing the name of the content you are interested in. + * @param [in] lifetime A `uint32_t` specifying the number of milliseconds the application + * will wait before re-sending the Interest. + * @param [in] keyId A pointer to a {@link PARCBuffer} containing a key digest that should be matched + * against ContentObjects whose names match our specified name. This value may be NULL and, if so, will + * not be used in the matching process. + * @param [in] contentObjectHash A pointer to a `PARCBuffer` containing the hash of the ContentObject that is expected + * to be returned in response to this Interest. + * + * @return A new instance of a `CCNxInterest`. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/temp/2"); + * + * PARCBuffer *keyId = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(keyId, 1234L); + * + * uint32_t lifetime = CCNxInterestDefaultLifetimeMilliseconds; + * + * CCNxInterest *interest = ccnxInterest_Create(name, lifetime, keyId, NULL); + * + * ... + * + * parcBuffer_Release(&keyId); + * ccnxName_Release(&name); + * ccnxInterest_Release(&interest); + * } + * @endcode + * + * @see {@link ccnxInterest_Release} + */ +CCNxInterest *ccnxInterest_Create(const CCNxName *name, + uint32_t lifetime, + const PARCBuffer *keyId, + const PARCBuffer *contentObjectHash); + + +/** + * Create a new instance of `CCNxInterest` for the specified name, using dynamically allocated memory. + * + * The created instance will specify a default lifetime, and will not specify a publisher's key + * digest for matching. Only the specified name will be used for matching. To specify values + * for the lifetime or publisher's key digest, see {@link ccnxInterest_Create()}. + * + * The created instance of `CCNxInterest` must be released by calling {@link ccnxInterest_Release}. + * + * @param [in] name A pointer to a `CCNxName` expressing the name of the content you are interested in. + * + * @return A new instance of a `CCNxInterest'. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/humidity/4"); + * + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * ... + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&interest); + * } + * @endcode + * + * @see {@link ccnxInterest_Create} + * @see {@link ccnxInterest_Release} + */ +CCNxInterest *ccnxInterest_CreateSimple(const CCNxName *name); + +/** + * Determine if two `CCNxInterest` instances are equal. + * + * The following equivalence relations on non-null `CCNxInterest` instances are maintained: + * + * * It is reflexive: for any non-null reference value x, `ccnxInterest_Equals(x, x)` + * must return true. + * + * * It is symmetric: for any non-null reference values x and y, + * `ccnxInterest_Equals(x, y)` must return true if and only if + * `ccnxInterest_Equals(y, x)` returns true. + * + * * It is transitive: for any non-null reference values x, y, and z, if + * `ccnxInterest_Equals(x, y)` returns true and + * `ccnxInterest_Equals(y, z)` returns true, + * then `ccnxInterest_Equals(x, z)` must return true. + * + * * It is consistent: for any non-null reference values x and y, multiple + * invocations of `ccnxInterest_Equals(x, y)` consistently return true or + * consistently return false. + * + * * For any non-null reference value x, `ccnxInterest_Equals(x, NULL)` must + * return false. + * + * @param interestA A pointer to a `CCNxInterest` instance. + * @param interestB A pointer to a `CCNxInterest` instance. + * @return true if the two `CCNxInterest` instances are equal. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/radiation/11"); + * uint32_t lifetime = 15 * 1000; // 15 seconds, in milliseconds + * + * PARCBuffer *keyDigest1 = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(keyDigest1, 1234L); + * + * PARCBuffer *keyDigest2 = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(keyDigest2, 6789L); // different buffer contents than keyDigest1 + * + * CCNxInterest *interestA = ccnxInterest_Create(name, lifetime, keyDigest1, NULL); + * CCNxInterest *interestB = ccnxInterest_Create(name, lifetime, keyDigest1, NULL); // same as A + * + * CCNxInterest *interestC = ccnxInterest_Create(name, lifetime, keyDigest2); // different key digest + * + * if (ccnxInterest_Equals(interestA, interestB)) { + * // this is expected... + * } + * + * if (ccnxInterest_Equals(interestA, interestC)) { + * // this is NOT expected + * } + * + * ... + * + * ccnxName_Release(&name); + * parcBuffer_Release(&keyDigest1); + * parcBuffer_Release(&keyDigest2); + * ccnxInterest_Release(&interestA); + * ccnxInterest_Release(&interestB); + * ccnxInterest_Release(&interestC); + * } + * @endcode + */ +bool ccnxInterest_Equals(const CCNxInterest *interestA, const CCNxInterest *interestB); + +/** + * Return a pointer to the {@link CCNxName} associated with the given `CCNxInterest`. + * + * The pointer points to memory managed by the `CCNxInterest` and does not have to + * be released unless {@link ccnxName_Acquire()} is called to acquire it. + * + * @param [in] interest A pointer to a `CCNxInterest` instance. + * + * @return A pointer to the CCNxName associated with the specified `CCNxInterest`. + * + * Example: + * @code + * { + * CCNxName *name = ccnxInterest_GetName(interest); + * } + * @endcode + * + * @see {@link CCNxName} + */ +CCNxName *ccnxInterest_GetName(const CCNxInterest *interest); + +/** + * Assign a lifetime value to the specified `CCNxInterest`. + * + * The lifetime, specified in milliseconds, is a hint to the system how long the application is + * willing to wait for a response before it will re-send the same Interest. It is used by forwarders as a + * guideline on how long they should attempt to keep the Interest alive in their tables. It is not a guarantee + * that they will do so, however. + * + * @param [in] interest A pointer to a `CCNxInterest` instance. + * @param [in] lifetime A `uint32_t` containing the desired lifetime of this Interest, in milliseconds. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/media/Ab00se"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * uint32_t lifetime = 15 * 1000; // 15 seconds, in milliseconds + * ccnxInterest_SetLifetime(interest, lifetime); + * + * ... + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&interest); + * } + * @endcode + * + * @see {@link ccnxInterest_GetLifetime} + */ +bool ccnxInterest_SetLifetime(CCNxInterest *interest, uint32_t lifetime); + +/** + * Retrieve the specified `CCNxInterest`'s lifetime value as a uint32_t. + * @param [in] interest A pointer to a `CCNxInterest` instance. + * + * @return The lifetime, in milliseconds, specified for this `CCNxInterest`. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/media/b00se"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * uint32_t lifetime = ccnxInterest_GetLifetime(interest); + * ... + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&interest); + * } + * @endcode + * + * @see {@link ccnxInterest_SetLifetime} + */ +uint32_t ccnxInterest_GetLifetime(const CCNxInterest *interest); + +/** + * Assign a key ID to the specified `CCNxInterest`. + * + * The key ID is used when matching this `CCNxInterest` to CCNx content. If a non-NULL + * key ID is specified in the `CCNxInterest`, then only content with a matching key + * digest will be matched. If the `CCNxInterest`'s key ID is NULL, then it is not used + * when matching against content. + * + * @param [in,out] interest A pointer to a `CCNxInterest` instance. + * @param [in] keyId A pointer to a {@link PARCBuffer} containing the desired key ID, or NULL. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/media/r00"); + * + * PARCBuffer *keyId = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(keyId, 1234L); + * + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * ccnxInterest_SetKeyIdRestriction(interest, keyId); + * + * ... + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&interest); + * parcBuffer_Release(&keyId); + * } + * @endcode + * + * @see ccnxInterest_GetKeyId + */ +bool ccnxInterest_SetKeyIdRestriction(CCNxInterest *interest, const PARCBuffer *keyId); + +/** + * Return a pointer to the {@link PARCBuffer} containing the publisher key digest associated with the given `CCNxInterest`. + * + * The pointer points to memory managed by the `CCNxInterest` and does not have to + * be released unless {@link parcBuffer_Acquire()} is called to acquire it. + * + * @param [in] interest A pointer to a `CCNxInterest` instance. + * + * @return A pointer to a PARCBuffer containing the `CCNxInterest`'s key ID. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/media/p1e"); + * + * PARCBuffer *keyId = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(keyId, 1234L); + * uint32_t lifetime = 5000; + * + * CCNxInterest *interest = ccnxInterest_Create(name, lifetime, keyId, NULL); + * + * PARCBuffer *keyIdP = ccnxInterest_GetKeyIdRestriction(interest); + * + * ... + * + * ccnxName_Release(&name); + * parcBuffer_Release(&keyId); + * ccnxInterest_Release(&interest); + * } + * } + * @endcode + * + * @see {@link ccnxInterest_SetKeyId} + */ +PARCBuffer *ccnxInterest_GetKeyIdRestriction(const CCNxInterest *interest); + +/** + * Assign a `ContentObjectHash` to the specified `CCNxInterest`. + * + * The `ContentObjectHash` is used when performing an exact match against this `CCNxInterest` and + * the response CCNx content. If a non-NULL `ContentObjectHash` is specified in the `CCNxInterest`, + * then only content whose hash digest matches the specified value will match and be returned. If + * the `ContentObjectHash` field is NULL, this binary equality check is not used when checking a response + * Content Object. + * + * @param [in,out] interest A pointer to a `CCNxInterest` instance. + * @param [in] contentObjectHash A pointer to a {@link PARCBuffer} containing the desired ContentObjectHash, or NULL. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/media/r00"); + * + * PARCBuffer *contentObjectHash = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(contentObjectHashcontentObjectHash, 1234L); + * + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * ccnxInterest_SetContentObjectHashRestriction(interest, contentObjectHash); + * + * ... + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&interest); + * parcBuffer_Release(&contentObjectHash); + * } + * @endcode + * + * @see {@link ccnxInterest_GetContentObjectHash} + */ +bool ccnxInterest_SetContentObjectHashRestriction(CCNxInterest *interest, const PARCBuffer *contentObjectHash); + +/** + * Return a pointer to the {@link PARCBuffer} containing the `ContentObjectHash` associated with the given `CCNxInterest`. + * + * The pointer points to memory managed by the `CCNxInterest` and does not have to + * be released unless {@link parcBuffer_Acquire()} is called to acquire it. + * + * @param [in] interest A pointer to a `CCNxInterest` instance. + * + * @return A pointer to a `PARCBuffer` containing the `CCNxInterest`'s `ContentObjectHash`. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/media/p1e"); + * + * uint32_t lifetime = 3 * 1000; // milliseconds + * + * PARCBuffer *contentObjectHash = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(contentObjectHash, 1234L); + * + * + * CCNxInterest *interest = ccnxInterest_Create(name, lifetime, NULL, contentObjectHash); + * + * PARCBuffer *contentObjectHashP = ccnxInterest_GetContentObjectHashRestriction(interest); + * + * ... + * + * ccnxName_Release(&name); + * parcBuffer_Release(&contentObjectHash); + * ccnxInterest_Release(&interest); + * } + * } + * @endcode + * + * @see {@link ccnxInterest_SetContentObjectHash} + */ +PARCBuffer *ccnxInterest_GetContentObjectHashRestriction(const CCNxInterest *interest); + +/** + * Produce a null-terminated string representation of the specified instance. + * + * The result must be freed by the caller via {@link parcMemory_Deallocate()}. + * + * @param [in] interest 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 + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/radiation/11"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * char *string = ccnxInterest_ToString(interest); + * + * if (string != NULL) { + * printf("Interest looks like: %s\n", string); + * parcMemory_Deallocate(string); + * } else { + * printf("Cannot allocate memory\n"); + * } + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&instance); + * } + * @endcode + * + * @see ccnxInterest_Display + * @see parcMemory_Deallocate + */ +char *ccnxInterest_ToString(const CCNxInterest *interest); + +/** + * Print a human readable representation of the given `CCNxInterest`. + * + * @param [in] interest 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:/parc/csl/sensors/radiation/11"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * ccnxInterest_Display(interest, 0); + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&instance); + * } + * @endcode + * */ +void ccnxInterest_Display(const CCNxInterest *interest, int indentation); + +/** + * Increase the number of references to a `CCNxInterest`. + * + * Note that a new `CCNxInterest` is not created, + * only that the given `CCNxInterest` reference count is incremented. + * Discard the reference by invoking {@link ccnxInterest_Release}. + * + * @param [in] instance A pointer to the original instance. + * @return The value of the input parameter @p instance. + * + * Example: + * @code + * { + * CCNxInterest *reference = ccnxInterest_Acquire(interest); + * + * ... + * + * ccnxInterest_Release(&reference); + * + * } + * @endcode + * + * @see ccnxInterest_Release + */ +CCNxInterest *ccnxInterest_Acquire(const CCNxInterest *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 + * { + * CCNxInterest *reference = ccnxInterest_Acquire(contentObject); + * + * ... + * + * ccnxInterest_Release(&reference); + * } + * @endcode + * + * @see {@link ccnxInterest_Acquire} + */ +void ccnxInterest_Release(CCNxInterest **instanceP); + +#ifdef Libccnx_DISABLE_VALIDATION +# define ccnxInterest_OptionalAssertValid(_instance_) +#else +# define ccnxInterest_OptionalAssertValid(_instance_) ccnxInterest_AssertValid(_instance_) +#endif +/** + * Assert that an instance of `CCNxInterest` 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] interest A pointer to the instance to check. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/radiation/11"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * ccnxInterest_AssertValid(interest); + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&instance); + * } + * @endcode + */ +void ccnxInterest_AssertValid(const CCNxInterest *interest); + + +/** + * Set the payload on an `CCnxInterest` instance. A reference to the supplied payload is + * acquired by the Interest, so the caller may release the payload after setting it on + * the CCnxInterest. The payload type must be specified, and must be one of the types + * defined in {@link CCNxPayloadType}. + * + * This will not append a payloadId segment to the Interest's name. If you want to do that, + * see {@link ccnxInterest_SetPayloadAndId} and {@link ccnxInterest_SetPayloadWithId}. + * + * @param [in] interest A pointer to the `CCNxInstance` instance to update. + * @param [in] payload A pointer to the PARCBuffer payload to be applied to the `CCNxInterest`. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/radiation/11"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * PARCBuffer *payload = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(payload, 5432L); + * + * ccnxInterest_SetPayload(interest, payload); + * + * parcBuffer_Release(&payload); + * ccnxName_Release(&name); + * ccnxInterest_Release(&instance); + * } + * @endcode + * @see `CCNxPayloadType` + */ +bool ccnxInterest_SetPayload(CCNxInterest *interest, const PARCBuffer *payload); + +/** + * Set the payload on an `CCnxInterest` instance. A reference to the supplied payload is + * acquired by the Interest, so the caller may release the payload after setting it on + * the CCnxInterest. The payload type must be specified, and must be one of the types + * defined in {@link CCNxPayloadType}. + * + * This will also generate and append a payloadId name segment to the interest name using a + * sha256 hash (the default) of the payload buffer. If you'd like to take responsibility + * for generating a payloadId, use {@link ccnxInterest_SetPayloadAndId} instead. + * + * @param [in] interest A pointer to the `CCNxInstance` instance to update. + * @param [in] payload A pointer to the PARCBuffer payload to be applied to the `CCNxInterest`. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/radiation/11"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * PARCBuffer *payload = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(payload, 5432L); + * + * ccnxInterest_SetPayload(interest, payload); + * + * parcBuffer_Release(&payload); + * ccnxName_Release(&name); + * ccnxInterest_Release(&instance); + * } + * @endcode + * @see `CCNxPayloadType` + */ +bool ccnxInterest_SetPayloadAndId(CCNxInterest *interest, const PARCBuffer *payload); + + +/** + * Set the payload and specified payloadId on an `CCnxInterest` instance. A reference to the + * supplied payload is acquired by the Interest, so the caller may release the payload after + * setting it on the CCnxInterest. The payload type must be specified, and must be one of the types + * defined in {@link CCNxPayloadType}. + * + * This will append the supplied payloadId to the interest name, supplying a NULL payloadId will result + * in not payloadId being appended to the interest name. See {@link CCNxInterestPayloadId} + * + * @param [in] interest A pointer to the `CCNxInstance` instance to update. + * @param [in] payload A pointer to the PARCBuffer payload to be applied to the `CCNxInterest`. + * @param [in] payloadId A pointer to a CCNxInterestPayloadId to use instead of the default. The value may + * be NULL of no payload id is desired. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/radiation/11"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * PARCBuffer *payload = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(payload, 5432L); + * + * CCNxInterestPayloadId *payloadId = ccnxInterestPayloadId_CreateAsSHA256Hash(payload); + * ccnxInterest_SetPayloadWithId(interest, payload, payloadId); + * ccnxInterestPayloadId_Release(&payloadId); + * + * parcBuffer_Release(&payload); + * ccnxName_Release(&name); + * ccnxInterest_Release(&instance); + * } + * @endcode + * @see `CCNxPayloadType` + */ +bool ccnxInterest_SetPayloadWithId(CCNxInterest *interest, const PARCBuffer *payload, const CCNxInterestPayloadId *payloadId); + + +/** + * Return a pointer to the payload attached to the specified `CCNxInterest`, if any. It is up to the + * caller to acquire a reference to the payload if necessary. + * + * @param [in] interest A pointer to the `CCNxInstance` instance to update. + * @return A pointer to the payload buffer attached to the supplied `CCNxInterest` instance. Will be NULL + * if the `CCNxInterest` instance has no payload. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/radiation/11"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * PARCBuffer *payload = parcBuffer_Allocate(8); + * parcBuffer_PutUint64(payload, 5432L); + * + * ccnxInterest_SetPayload(interest, CCNxPayloadType_DATA, payload); + * + * PARCBuffer *reference = ccnxInterest_GetPayload(interest); + * + * parcBuffer_Release(&payload); + * ccnxName_Release(&name); + * ccnxInterest_Release(&instance); + * } + * @endcode + */ +PARCBuffer *ccnxInterest_GetPayload(const CCNxInterest *interest); + +/** + * Set the Hop Limit for the specified `CCNxInterest` instance. + * The Interest HopLimit element is a counter that is decremented with each hop. It limits the distance an Interest may travel. + * The node originating the Interest may put in any value - up to the maximum - in network byte order. Each node that receives + * an Interest with a HopLimit decrements the value upon reception. If the value is 0 after the decrement, the Interest cannot + * be forwarded off the node. + * + * @param [in] interest A pointer to a `CCNxInterest` instance to update. + * @param [in] hopLimit The hop limit to set. + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/radiation/11"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * ccnxInterest_SetHopLimit(interest, 30); + * + * uint32_t hopLimit = ccnxInterest_GetHopLimit(interest); + * assertTrue(hopLimit = 30, "Expected 30 for the hopLimit"); + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&instance); + * } + * @endcode + * @see `ccnxInterest_GetHopLimit` + */ +bool ccnxInterest_SetHopLimit(CCNxInterest *interest, uint32_t hopLimit); + +/** + * Get the Hop Limit for the specified `CCNxInterest` instance. + * The Interest HopLimit element is a counter that is decremented with each hop. It limits the distance an Interest may travel. + * The node originating the Interest may put in any value - up to the maximum - in network byte order. Each node that receives + * an Interest with a HopLimit decrements the value upon reception. If the value is 0 after the decrement, the Interest cannot + * be forwarded off the node. + * + * @param [in] interest A pointer to the `CCNxInterest` from which to retrieve the Hop Limit + * + * Example: + * @code + * { + * CCNxName *name = ccnxName_CreateFromCString("lci:/parc/csl/sensors/radiation/11"); + * CCNxInterest *interest = ccnxInterest_CreateSimple(name); + * + * ccnxInterest_SetHopLimit(interest, 30); + * + * uint32_t hopLimit = ccnxInterest_GetHopLimit(interest); + * assertTrue(hopLimit = 30, "Expected 30 for the hopLimit"); + * + * ccnxName_Release(&name); + * ccnxInterest_Release(&instance); + * } + * @endcode + * @see `ccnxInterest_SetHopLimit` + */ +uint32_t ccnxInterest_GetHopLimit(const CCNxInterest *interest); +#endif // libccnx_ccnx_Interest_h |