Additional formats used by BT-656 sensors
[media-ctl.git] / src / mediactl.h
index b53b9cc..cddf272 100644 (file)
@@ -1,5 +1,5 @@
 /*
- * Media controller test application
+ * Media controller interface library
  *
  * Copyright (C) 2010 Ideas on board SPRL <laurent.pinchart@ideasonboard.com>
  *
@@ -38,6 +38,7 @@ struct media_pad {
 };
 
 struct media_entity {
+       struct media_device *media;
        struct media_entity_desc info;
        struct media_pad *pads;
        struct media_link *links;
@@ -53,13 +54,52 @@ struct media_device {
        int fd;
        struct media_entity *entities;
        unsigned int entities_count;
+       void (*debug_handler)(void *, ...);
+       void *debug_priv;
        __u32 padding[6];
 };
 
+#define media_dbg(media, ...) \
+       (media)->debug_handler((media)->debug_priv, __VA_ARGS__)
+
+/**
+ * @brief Set a handler for debug messages.
+ * @param media - device instance.
+ * @param debug_handler - debug message handler
+ * @param debug_priv - first argument to debug message handler
+ *
+ * Set a handler for debug messages that will be called whenever
+ * debugging information is to be printed. The handler expects an
+ * fprintf-like function.
+ */
+void media_debug_set_handler(
+       struct media_device *media, void (*debug_handler)(void *, ...),
+       void *debug_priv);
+
+/**
+ * @brief Open a media device with debugging enabled.
+ * @param name - name (including path) of the device node.
+ * @param debug_handler - debug message handler
+ * @param debug_priv - first argument to debug message handler
+ *
+ * Open the media device referenced by @a name and enumerate entities, pads and
+ * links.
+ *
+ * Calling media_open_debug() instead of media_open() is equivalent to
+ * media_open() and media_debug_set_handler() except that debugging is
+ * also enabled during media_open().
+ *
+ * @return A pointer to a newly allocated media_device structure instance on
+ * success and NULL on failure. The returned pointer must be freed with
+ * media_close when the device isn't needed anymore.
+ */
+struct media_device *media_open_debug(
+       const char *name, void (*debug_handler)(void *, ...),
+       void *debug_priv);
+
 /**
  * @brief Open a media device.
  * @param name - name (including path) of the device node.
- * @param verbose - whether to print verbose information on the standard output.
  *
  * Open the media device referenced by @a name and enumerate entities, pads and
  * links.
@@ -68,7 +108,7 @@ struct media_device {
  * success and NULL on failure. The returned pointer must be freed with
  * media_close when the device isn't needed anymore.
  */
-struct media_device *media_open(const char *name, int verbose);
+struct media_device *media_open(const char *name);
 
 /**
  * @brief Close a media device.
@@ -140,7 +180,9 @@ struct media_entity *media_get_entity_by_id(struct media_device *media,
  *
  * Only the MEDIA_LINK_FLAG_ENABLED flag is writable.
  *
- * @return 0 on success, or a negative error code on failure.
+ * @return 0 on success, -1 on failure:
+ *        -ENOENT: link not found
+ *        - other error codes returned by MEDIA_IOC_SETUP_LINK
  */
 int media_setup_link(struct media_device *media,
        struct media_pad *source, struct media_pad *sink,
@@ -157,4 +199,57 @@ int media_setup_link(struct media_device *media,
  */
 int media_reset_links(struct media_device *media);
 
+/**
+ * @brief Parse string to a pad on the media device.
+ * @param media - media device.
+ * @param p - input string
+ * @param endp - pointer to string where parsing ended
+ *
+ * Parse NULL terminated string describing a pad and return its struct
+ * media_pad instance.
+ *
+ * @return Pointer to struct media_pad on success, NULL on failure.
+ */
+struct media_pad *media_parse_pad(struct media_device *media,
+                                 const char *p, char **endp);
+
+/**
+ * @brief Parse string to a link on the media device.
+ * @param media - media device.
+ * @param p - input string
+ * @param endp - pointer to p where parsing ended
+ *
+ * Parse NULL terminated string p describing a link and return its struct
+ * media_link instance.
+ *
+ * @return Pointer to struct media_link on success, NULL on failure.
+ */
+struct media_link *media_parse_link(struct media_device *media,
+                                   const char *p, char **endp);
+
+/**
+ * @brief Parse string to a link on the media device and set it up.
+ * @param media - media device.
+ * @param p - input string
+ *
+ * Parse NULL terminated string p describing a link and its configuration
+ * and configure the link.
+ *
+ * @return 0 on success, or a negative error code on failure.
+ */
+int media_parse_setup_link(struct media_device *media,
+                          const char *p, char **endp);
+
+/**
+ * @brief Parse string to link(s) on the media device and set it up.
+ * @param media - media device.
+ * @param p - input string
+ *
+ * Parse NULL terminated string p describing link(s) separated by
+ * commas (,) and configure the link(s).
+ *
+ * @return 0 on success, or a negative error code on failure.
+ */
+int media_parse_setup_links(struct media_device *media, const char *p);
+
 #endif