SDOCM00115293 Linux transport interfaces need documentation
[ipc/ipcdev.git] / linux / include / ti / ipc / interfaces / ITransport.h
index c8f087ef04b3106523c5c27c334d08bea39c241b..f4bbf90376c8b1fae3ae32391a5d161afdd40400 100644 (file)
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ *  @file linux/include/ti/ipc/interfaces/ITransport.h
+ *
+ *  @brief Base interface for all message transports
+ *
+ *  All message transport interfaces must inherit from this base class.
+ *
+ *  The ITransport interface includes the following instance methods:
+ *
+ *  itype - return the derived interface type
+ */
+
 /*
  *  ======== ITransport.h ========
  */
 /*
  *  ======== ITransport.h ========
  */
 #ifndef ITRANSPORT_H
 #define ITRANSPORT_H
 
 #ifndef ITRANSPORT_H
 #define ITRANSPORT_H
 
-/* opaque instance handle */
-typedef struct ITransport_Object *ITransport_Handle;
+#if defined (__cplusplus)
+extern "C" {
+#endif
 
 
+/*!
+ *  @brief  Interface type ID
+ *
+ *  When adding a new interface type, please ensure to define a
+ *  unique ID value for each new type.
+ */
 #define ITransport_TypeId 0x01
 
 #define ITransport_TypeId 0x01
 
-/* instance object */
+/*!
+ *  @brief ITransport_Handle type
+ *
+ *  An opaque instance handle.
+ */
+typedef struct ITransport_Object *ITransport_Handle;
+
+/*!
+ *  @brief The instance object definition for ITransport
+ */
 typedef struct ITransport_Object {
 typedef struct ITransport_Object {
+
     Int interfaceType;
     Int interfaceType;
+    /*!< Interface type ID
+     *
+     *  This field is initialized by the constructor of the derived
+     *  implementation. It should be assigned the interface type ID
+     *  which is being implemented.
+     */
 } ITransport_Object;
 
 } ITransport_Object;
 
-/* instance functions */
+/*!
+ *  @brief Identify the derived interface type
+ *
+ *  Identify the interface type which is implemented by the instance
+ *  object. Transport users (e.g. MessageQ) would use this method to
+ *  identify the interface type and then downcast the ITransport_Handle
+ *  to that interface type.
+ *
+ *  @param[in]  inst        Instance handle
+ *
+ *  @return     Derived interface type ID
+ */
 static inline
 Int ITransport_itype(ITransport_Handle inst)
 {
 static inline
 Int ITransport_itype(ITransport_Handle inst)
 {
@@ -55,4 +101,7 @@ Int ITransport_itype(ITransport_Handle inst)
     return obj->interfaceType;
 }
 
     return obj->interfaceType;
 }
 
+#if defined (__cplusplus)
+}
+#endif
 #endif /* ITRANSPORT_H */
 #endif /* ITRANSPORT_H */