client: provide API documentationneedlefish_13.93.0needlefish/13.93.0marlin_12.93.0marlin_12.92.0marlin_12.91.0marlin_12.90.1marlin/12.93.0marlin/12.92.0marlin/12.91.0marlin/12.90.1lamprey_12.1.6lamprey_12.1.5lamprey_12.1.4lamprey_12.1.3lamprey_12.1.2lamprey_12.1.1lamprey_12.1.0lamprey_12.0.1lamprey/12.1.6lamprey/12.1.5lamprey/12.1.4lamprey/12.1.3lamprey/12.1.2lamprey/12.1.1lamprey/12.1.0lamprey/12.0.1koi_11.0.5koi_11.0.4koi/11.0.5koi/11.0.413.93.012.93.012.92.012.91.012.90.112.1.612.1.512.1.412.1.312.1.212.1.112.1.012.0.111.0.511.0.4

Signed-off-by: George Kiagiadakis <george.kiagiadakis@collabora.com>

2 files changed, 86 insertions, 0 deletions

diff --git a/README.md b/README.md
index 97d88c2..558c360 100644
--- a/README.md
+++ b/README.md
@@ -87,6 +87,23 @@ To demo it with `libpipewire-module-protocol-ic-ipc` being the server, use:
  * `send SUSPEND` - suspend playback on the host
  * `send RESUME` - resume playback on the host
 
+## Writing IC apps that use libicipc
+
+IC apps that need to use this SUSPEND/RESUME mechanism for sound, should
+directly use libicipc.
+
+For API documentation, refer to `lib/client.h`. Clients should use only
+the API provided in this file.
+
+To link to libicipc, use the provided `icipc-0.1` pkg-config package:
+```
+$ pkg-config --cflags --libs icipc-0.1
+```
+
+By default, the libicipc library is built statically. If you wish to build
+a dynamically linked version, pass the `-Ddefault_library=dynamic` option to
+meson when compiling `pipewire-ic-ipc`
+
 ## Compilation & Running
 
 To compile:
diff --git a/lib/client.h b/lib/client.h
index 226d87a..3f5c368 100644
--- a/lib/client.h
+++ b/lib/client.h
@@ -18,17 +18,67 @@
 extern "C" {
 #endif
 
+/*!
+ * \brief Casts icipc_client* to icipc_sender*
+ * icipc_client is a subclass of icipc_sender and can be cast to it
+ * at any time with this macro
+ */
 #define icipc_client_to_sender(self) ((struct icipc_sender *)(self))
 
 struct icipc_client;
 struct icipc_data;
 
+/*!
+ * \brief Creates a new client
+ * \param path the name of the socket file to use for the connection; this
+ *   may be an absolute path, or just a filename that will be looked for in
+ *   the standard socket directories: PIPEWIRE_RUNTIME_DIR / XDG_RUNTIME_DIR / HOME
+ * \param connect set to \c true to also connect to the server. If connection
+ *   fails, there is no indication; use icipc_client_is_connected() to check
+ *   the connection status afterwards. Alternatively, pass \c false here and
+ *   call icipc_client_connect() manually.
+ * \return the new icipc_client
+ */
 ICIPC_API
 struct icipc_client *icipc_client_new(const char *path, bool connect);
 
+/*!
+ * \brief Destroys the client
+ * The client also gracefully disconnects if it was connected.
+ */
 ICIPC_API
 void icipc_client_free(struct icipc_client *self);
 
+/*!
+ * \brief Checks if the client is connected
+ * \return a boolean value
+ */
+#define icipc_client_is_connected(c) \
+        icipc_sender_is_connected(icipc_client_to_sender(c))
+
+/*!
+ * \brief Connects to the server, if not already connected
+ * \return a boolean value: \c true if connection succeeded or if the client
+ *   was already connected, \c false if connection failed
+ */
+#define icipc_client_connect(c) \
+        icipc_sender_connect(icipc_client_to_sender(c))
+
+/*!
+ * \brief Disconnects from the server
+ */
+#define icipc_client_disconnect(c) \
+        icipc_sender_disconnect(icipc_client_to_sender(c))
+
+/*!
+ * \brief Sends a request to the server
+ * \param self the client instance
+ * \param name the name of the request to send
+ * \param args arguments of the request, or NULL
+ * \param reply a callback, which is called when the server replies to this request
+ * \param data additional user-defined data to pass to the \a reply callback
+ * \return \c true if the request was sent, \c false if there was an error
+ */
 ICIPC_API
 bool icipc_client_send_request(
                 struct icipc_client *self,
@@ -39,6 +89,25 @@ bool icipc_client_send_request(
 
 /* for reply handlers only */
 
+/*!
+ * \brief Finish the request and extract the reply
+ *
+ * This is meant to be called in the `icipc_sender_reply_func_t` reply callback
+ * that was passed on to icipc_client_send_request()
+ *
+ * If the request succeeded, this extracts the reply and returns it. Even for
+ * replies that do not return any value, the returned pointer is guaranteed
+ * to be non-NULL on success.
+ *
+ * If the request failed, the returned pointer is NULL and the \a error is set
+ * to a string that can be printed for debugging the problem.
+ *
+ * \param self the client instance
+ * \param buffer the buffer of the reply (argument to the reply callback)
+ * \param size the size of the buffer (argument to the reply callback)
+ * \param error return location for an error string
+ * \return NULL on failure, non-NULL return value of the reply on success
+ */
 ICIPC_API
 const struct icipc_data *icipc_client_send_request_finish(
                 struct icipc_sender *self,