From eb323e056e747d71867cf965434811c1de925de2 Mon Sep 17 00:00:00 2001
From: Luca Muscariello <lumuscar+fdio@cisco.com>
Date: Sat, 23 Mar 2019 14:13:53 +0100
Subject: [HICN-141] Definition of a C API for hicn-light

Change-Id: Id861f0abe58b1e3c9ba8cc76701da0f9c6801748
Signed-off-by: Luca Muscariello <lumuscar+fdio@cisco.com>
Signed-off-by: Angelo Mantellini <manangel@cisco.com>
---
 hicn-light/src/hicn/messenger/messengerRecipient.h | 104 +++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 hicn-light/src/hicn/messenger/messengerRecipient.h

(limited to 'hicn-light/src/hicn/messenger/messengerRecipient.h')

diff --git a/hicn-light/src/hicn/messenger/messengerRecipient.h b/hicn-light/src/hicn/messenger/messengerRecipient.h
new file mode 100644
index 000000000..cb5705b3a
--- /dev/null
+++ b/hicn-light/src/hicn/messenger/messengerRecipient.h
@@ -0,0 +1,104 @@
+/*
+ * Copyright (c) 2017-2019 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 messengerRecipient.h
+ * @brief A recipient represents the entity that will recieve a Missive from the
+ * Messenger.
+ *
+ * A recipient is identified by the pair (contenxt, callback).  The context is
+ * the recipients context, such as it's object pointer.  The callback is the
+ * function the recipient uses to receive a Missive.
+ *
+ * If the receiver is going to do a lot of work or potentially send other
+ * missives, the receiver should queue the received notifications and process
+ * them in its own slice.
+ *
+ * A recipient will receive a reference counted copy of the missive, so it must
+ * call
+ * {@link missive_Release} on it.
+ *
+ *
+ */
+
+#ifndef messengerRecipient_h
+#define messengerRecipient_h
+
+#include <hicn/messenger/missive.h>
+
+struct messenger_recipient;
+typedef struct messenger_recipient MessengerRecipient;
+
+/**
+ * @typedef MessengerRecipientCallback
+ * @abstract A recipient implements a callback to receive Missives.
+ * @constant recipient The recipient to recieve the missive
+ * @constant missive The missive, recipient must call {@link missive_Release} on
+ * it
+ */
+typedef void(MessengerRecipientCallback)(MessengerRecipient *recipient,
+                                         Missive *missive);
+
+/**
+ * Creates a Recipient, which represents a reciever of missives.
+ *
+ * Creates a Recipient that can be registerd with the Messenger using {@link
+ * messenger_Register}.
+ *
+ * @param [in] recipientContext This pointer will be passed back to the
+ * recipient with each missive, may be NULL
+ * @param [in] recipientCallback The function that receives the missive, must be
+ * non-NULL.
+ *
+ * @return non-null A recipient object
+ */
+MessengerRecipient *messengerRecipient_Create(
+    void *recipientContext, MessengerRecipientCallback *recipientCallback);
+
+/**
+ * Destroys a recipient.  You should unregister it first.
+ *
+ * Destroying a recipient does not unregister it, so be sure to call
+ * {@link messenger_Unregister} first.
+ *
+ * @param [in,out] recipientPtr Double pointer to the recipient to destroy, will
+ * be NULL'd.
+ */
+void messengerRecipient_Destroy(MessengerRecipient **recipientPtr);
+
+/**
+ * Returns the recipient context passed on Create
+ *
+ * @param [in] recipient The recipient object
+ *
+ * @return pointer The context pointer used to create the object, maybe NULL
+ */
+void *messengerRecipient_GetRecipientContext(MessengerRecipient *recipient);
+
+/**
+ * Delivers a Missive to the recipient
+ *
+ * Passes the missive to the recipients callback.
+ *
+ * A recipient will receive a reference counted copy of the missive, so it must
+ * call
+ * {@link missive_Release} on it.
+ *
+ * @param [in] recipient The receiver
+ * @param [in] missive The message to send
+ */
+void messengerRecipient_Deliver(MessengerRecipient *recipient,
+                                Missive *missive);
+#endif  // messengerRecipient_h
-- 
cgit 1.2.3-korg