1 files changed, 515 insertions, 0 deletions
diff --git a/libccnx-transport-rta/ccnx/transport/common/transport_MetaMessage.h b/libccnx-transport-rta/ccnx/transport/common/transport_MetaMessage.h
new file mode 100644
index 00000000..f7dda45c
--- /dev/null
+++ b/libccnx-transport-rta/ccnx/transport/common/transport_MetaMessage.h
@@ -0,0 +1,515 @@
+/*
+ * 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_MetaMessage.h
+ * @brief A CCNx message suitable for sending through the CCNx Portal API.
+ *
+ * A CCNxMetaMessage encapsulates a CCN Interest, ContentObject, or Control message, and can
+ * be read from and written to the CCNx Portal API.
+ *
+ */
+#ifndef libccnx_ccnx_MetaMessage_h
+#define libccnx_ccnx_MetaMessage_h
+
+#include <ccnx/common/ccnx_Interest.h>
+#include <ccnx/common/ccnx_InterestReturn.h>
+#include <ccnx/common/ccnx_ContentObject.h>
+#include <ccnx/common/ccnx_Manifest.h>
+#include <ccnx/common/ccnx_WireFormatMessage.h>
+
+#include <ccnx/common/internal/ccnx_TlvDictionary.h>
+
+#include <ccnx/api/control/cpi_ControlMessage.h>
+
+/**
+ * @typedef CCNxMetaMessage
+ * @brief A CCNxMetaMessage encapsulates a CCN Interest, ContentObject, or Control message.
+ */
+typedef CCNxTlvDictionary CCNxMetaMessage;
+
+
+/**
+ * Create a `CCNxMetaMessage` instance containing the given {@link CCNxInterest}.
+ *
+ * A new reference to the `CCNxInterest` is created.
+ *
+ * @param [in] interest A pointer to a valid `CCNxInterest` instance.
+ *
+ * @return NULL The `CCNxInterest` is not valid, or memory could not be allocated.
+ * @return non-NULL A pointer to a `CCNxMetaMessage` instance.
+ *
+ * Example:
+ * @code
+ * {
+ *         CCNxMetaMessage *message = ccnxMetaMessage_CreateFromInterest(interest);
+ * }
+ * @endcode
+ */
+CCNxMetaMessage *ccnxMetaMessage_CreateFromInterest(const CCNxInterest *interest);
+
+/**
+ * Create a `CCNxMetaMessage` instance containing the given {@link CCNxContentObject}.
+ *
+ * A new reference to the `CCNxContentObject` is created.
+ *
+ * @param [in] contentObject A pointer to a valid `CCNxContentObject` instance.
+ *
+ * @return NULL The `CCNxContentObject` is not valid, or memory could not be allocated.
+ * @return non-NULL A pointer to a `CCNxMetaMessage` instance.
+ *
+ * Example:
+ * @code
+ * {
+ *         CCNxMetaMessage *message = ccnxMetaMessage_CreateFromContentObject(contentObject);
+ * }
+ * @endcode
+ */
+CCNxMetaMessage *ccnxMetaMessage_CreateFromContentObject(const CCNxContentObject *contentObject);
+
+/**
+ * Create a `CCNxMetaMessage` instance containing the given {@link CCNxControl}.
+ *
+ * A new reference to the `CCNxControl` is created.
+ *
+ * @param [in] control A pointer to a valid `CCNxControl` instance.
+ *
+ * @return NULL The `CCNxControl` is not valid, or memory could not be allocated.
+ * @return non-NULL A pointer to a `CCNxMetaMessage` instance.
+ *
+ * Example:
+ * @code
+ * {
+ *         CCNxMetaMessage *message = ccnxMetaMessage_CreateFromControl(control);
+ * }
+ * @endcode
+ */
+CCNxMetaMessage *ccnxMetaMessage_CreateFromControl(const CCNxControl *control);
+
+/**
+ * Create a `CCNxMetaMessage` instance containing the given {@link CCNxManifest}.
+ *
+ * A new reference to the `CCNxManifest` is created.
+ *
+ * @param [in] control A pointer to a valid `CCNxManifest` instance.
+ *
+ * @return NULL The `CCNxManifest` is not valid, or memory could not be allocated.
+ * @return non-NULL A pointer to a `CCNxMetaMessage` instance.
+ *
+ * Example:
+ * @code
+ * {
+ *         CCNxMetaMessage *message = ccnxMetaMessage_CreateFromManifest(manifest);
+ * }
+ * @endcode
+ */
+CCNxMetaMessage *ccnxMetaMessage_CreateFromManifest(const CCNxManifest *manifest);
+
+/**
+ * Print a human readable representation of the given `CCNxMetaMessage` instance.
+ *
+ * @param [in] message A pointer to the `CCNxMetaMessage` to display.
+ * @param [in] indentation The level of indentation to use to pretty-print the output.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxMetaMessage_CreateFromInterest(...);
+ *
+ *     ccnxMetaMessage_Display(message, 0);
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ *
+ */
+void ccnxMetaMessage_Display(const CCNxMetaMessage *message, int indentation);
+
+/**
+ * Increase the number of references to a `CCNxMetaMessage`.
+ *
+ * Note that new `CCNxMetaMessage` is not created,
+ * only that the given `CCNxMetaMessage` reference count is incremented.
+ * Discard the reference by invoking {@link ccnxMetaMessage_Release}().
+ *
+ * @param [in] instance A pointer to a `CCNxMetaMessage` instance.
+ * @return The input @p instance.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *     CCNxMetaMessage *messageReference = ccnxMetaMessage_Acquire(message);
+ *
+ *     ccnxMetaMessage_Release(&message);
+ *     ccnxMetaMessage_Release(&messageReference);
+ * }
+ * @endcode
+ * @see `ccnxMetaMessage_Release`
+ */
+CCNxMetaMessage *ccnxMetaMessage_Acquire(const CCNxMetaMessage *instance);
+
+/**
+ * Determine whether a specified `CCNxMetaMessage` instance encapsulates an {@link CCNxInterest}.
+ *
+ * Returns `true` if the underlying message is a `CCNxInterest`.
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return `true` If the underlying message is a `CCNxInterest`.
+ * @return `false` If the underlying message is not a `CCNxInterest`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsInterest(message)) {
+ *         CCNxInterest *interest = ccnxMetaMessage_GetInterest(message);
+ *         ...
+ *         ccnxInterest_Release(&interest);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ * @see CCNxInterest
+ */
+bool ccnxMetaMessage_IsInterest(const CCNxMetaMessage *message);
+
+/**
+ * Determine whether a specified `CCNxMetaMessage` instance encapsulates an {@link CCNxInterestReturn}.
+ *
+ * Returns `true` if the underlying message is a `CCNxInterestReturn`.
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return `true` If the underlying message is a `CCNxInterestReturn`.
+ * @return `false` If the underlying message is not a `CCNxInterestReturn`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsInterestReturn(message)) {
+ *         CCNxInterestReturn *interestReturn = ccnxMetaMessage_GetInterestReturn(message);
+ *
+ *         ...
+ *         ccnxInterestReturn_Release(&interestReturn);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ * @see CCNxInterestReturn
+ */
+bool ccnxMetaMessage_IsInterestReturn(const CCNxMetaMessage *message);
+
+/**
+ * Determine whether a specified `CCNxMetaMessage` instance encapsulates a {@link CCNxContentObject}.
+ *
+ * Returns true if the underlying message is a `CCNxContentObject`.
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return `true` If the underlying message is a `CCNxContentObject`.
+ * @return `false` If the underlying message is not a `CCNxContentObject`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsContentObject(message)) {
+ *         CCNxContentObject *contentObject = ccnxMetaMessage_GetContentObject(message);
+ *         ...
+ *         ccnxContentObject_Release(&contentObject);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ * @see `CCNxContentObject`
+ */
+bool ccnxMetaMessage_IsContentObject(const CCNxMetaMessage *message);
+
+/**
+ * Determine whether a specified `CCNxMetaMessage` instance encapsulates a {@link CCNxControl}.
+ *
+ * Returns true if the underlying message is a `CCNxControl`.
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return `true` If the underlying message is a `CCNxControl`.
+ * @return `false` If the underlying message is not a `CCNxControl`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsControl(message)) {
+ *         CCNxControl *control = ccnxMetaMessage_GetControl(message);
+ *         ...
+ *         ccnxControl_Release(&control);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ * @see `CCNxControl`
+ */
+bool ccnxMetaMessage_IsControl(const CCNxMetaMessage *message);
+
+/**
+ * Determine whether a specified `CCNxMetaMessage` instance encapsulates a {@link CCNxManifest}.
+ *
+ * Returns true if the underlying message is a `CCNxManifest`.
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return `true` If the underlying message is a `CCNxManifest`.
+ * @return `false` If the underlying message is not a `CCNxManifest`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsManifest(message)) {
+ *         CCNxManifest *control = ccnxMetaMessage_GetManifest(message);
+ *         ...
+ *         ccnxManifest_Release(&manifest);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ * @see `CCNxManifest`
+ */
+bool ccnxMetaMessage_IsManifest(const CCNxMetaMessage *message);
+
+/**
+ * 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] messagePtr A pointer to a pointer to the instance to release.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *     CCNxMetaMessage *messageReference = ccnxMetaMessage_Acquire(message);
+ *
+ *     ccnxMetaMessage_Release(&message);
+ *     ccnxMetaMessage_Release(&messageReference);
+ * }
+ * @endcode
+ * @see {@link ccnxMetaMessage_Acquire}
+ */
+void ccnxMetaMessage_Release(CCNxMetaMessage **messagePtr);
+
+/**
+ * Return a new {@link CCNxContentObject} instance created from the `CCNxMetaMessage`.
+ *
+ * The newly created `CCNxContentObject` instance must eventually be released by calling {@link ccnxContentObject_Release}().
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return A new `CCNxContentObject` instance, which must eventually be released by calling `ccnxContentObject_Release()`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsContentObject(message)) {
+ *         CCNxContentObject *contentObject = ccnxMetaMessage_GetContentObject(message);
+ *         ...
+ *         ccnxContentObject_Release(&contentObject);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ *
+ * @see `ccnxContentObject_Release`
+ * @see {@link ccnxMetaMessage_IsContentObject}
+ */
+CCNxContentObject *ccnxMetaMessage_GetContentObject(const CCNxMetaMessage *message);
+
+/**
+ * Return a new {@link CCNxInterest} instance created from the `CCNxMetaMessage`.
+ *
+ * The newly created `CCNxInterest}\` instance must eventually be released by calling {@link ccnxInterest_Release}().
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return A new `CCNxInterest` instance, which must eventually be released by calling `ccnxInterest_Release()`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsInterest(message)) {
+ *         CCNxInterest *interest = ccnxMetaMessage_GetInterest(message);
+ *         ...
+ *         ccnxInterest_Release(&interest);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ *
+ * @see `ccnxInterest_Release`
+ * @see {@link ccnxMetaMessage_IsInterest}
+ */
+CCNxInterest *ccnxMetaMessage_GetInterest(const CCNxMetaMessage *message);
+
+/**
+ * Return a new {@link CCNxInterestReturn} instance created from the `CCNxMetaMessage`.
+ *
+ * The newly created `CCNxInterestReturn}\` instance must eventually be released by calling {@link ccnxInterest_Release}().
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return A new `CCNxInterest` instance, which must eventually be released by calling `ccnxInterestReturn_Release()`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsInterestReturn(message)) {
+ *         CCNxInterestReturn *interestReturn = ccnxMetaMessage_GetInterestReturn(message);
+ *
+ *         ...
+ *         ccnxInterestReturn_Release(&interestReturn);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ *
+ * @see `ccnxInterest_Release`
+ * @see {@link ccnxMetaMessage_IsInterest}
+ */
+CCNxInterest *ccnxMetaMessage_GetInterestReturn(const CCNxMetaMessage *message);
+
+/**
+ * Return a new {@link CCNxControl} instance created from the `CCNxMetaMessage`.
+ *
+ * The newly created `CCNxControl` instance must eventually be released by calling {@link ccnxControl_Release}().
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return A new `CCNxControl` instance, which must eventually be released by calling `ccnxControl_Release()`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsControl(message)) {
+ *         CCNxControl *control = ccnxMetaMessage_GetControl(message);
+ *         ...
+ *         ccnxControl_Release(&control);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ *
+ * @see `ccnxControl_Release`
+ * @see {@link ccnxMetaMessage_IsControl}
+ */
+CCNxControl *ccnxMetaMessage_GetControl(const CCNxMetaMessage *message);
+
+/**
+ * Return a new {@link CCNxManifest} instance created from the `CCNxMetaMessage`.
+ *
+ * The newly created `CCNxManifest` instance must eventually be released by calling {@link ccnxManifest_Release}().
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ *
+ * @return A new `CCNxManifest` instance, which must eventually be released by calling `ccnxManifest_Release()`.
+ *
+ * Example:
+ * @code
+ * {
+ *     CCNxMetaMessage *message = ccnxPortal_Receive(portal, CCNxStackTimeout_Never);
+ *
+ *     if (ccnxMetaMessage_IsManifest(message)) {
+ *         CCNxManifest *manifest = ccnxMetaMessage_GetManifest(message);
+ *         ...
+ *         ccnxManifest_Release(&manifest);
+ *     }
+ *
+ *     ccnxMetaMessage_Release(&message);
+ * }
+ * @endcode
+ *
+ * @see {@link ccnxManifest_Release}
+ * @see {@link ccnxMetaMessage_IsManifest}
+ */
+CCNxManifest *ccnxMetaMessage_GetManifest(const CCNxMetaMessage *message);
+
+/**
+ * Return a new {@link CCNxMetaMessage} instance created from a wire format message
+ *
+ * The newly created `CCNxMetaMessage` instance must eventually be released by calling {@link CCNxMetaMessage_Release}().
+ *
+ * @param [in] message A pointer to a `PARCBuffer` instance containing a wire format message.
+ *
+ * @return A new `CCNxMetaMessage` instance, which must eventually be released by calling `ccnxMetaMessage_Release()`.
+ *
+ * Example:
+ * @code
+ * {
+ * }
+ * @endcode
+ *
+ */
+CCNxMetaMessage *ccnxMetaMessage_CreateFromWireFormatBuffer(PARCBuffer *rawMessage);
+
+/**
+ * Return a new {@link PARCBuffer} instance containing an encodeded wire format message created
+ * from the source `CCNxMetaMessage`.
+ *
+ * The newly created `PARCBuffer` instance must eventually be released by calling {@link parcBuffer_Release}().
+ *
+ * @param [in] message A pointer to a `CCNxMetaMessage` instance.
+ * @param [in] signer A pointer to a `PARCSigner` instance.
+ *
+ * @return A new `PARCBuffer` instance, which must eventually be released by calling `parcBuffer_Release()`.
+ *
+ * Example:
+ * @code
+ * {
+ * }
+ * @endcode
+ *
+ */
+PARCBuffer *ccnxMetaMessage_CreateWireFormatBuffer(CCNxMetaMessage *message, PARCSigner *signer);
+
+#endif // libccnx_ccnx_MetaMessage_h