add new apis

gp_camera_list_config, gp_camera_set_single_config, gp_camera_get_single_config

4 files changed, 180 insertions, 0 deletions

diff --git a/NEWS b/NEWS
index 859dff343..5cab904fa 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,9 @@
 libgphoto2 2.5.9.1 development tree
 
+libgphoto2:
+* added gp_camera_list_config, gp_camera_get_single_config, gp_camera_set_single_config
+  additional configuration APIs for faster access to single configuration values
+
 ptp2:
 * allow generic opcode commands with parameters, config variable "opcode"
 * fixed pretending that Nikon Coolpix S series is a Nikon 1 S.
diff --git a/gphoto2/gphoto2-camera.h b/gphoto2/gphoto2-camera.h
index d03a94943..45f9e7976 100644
--- a/gphoto2/gphoto2-camera.h
+++ b/gphoto2/gphoto2-camera.h
@@ -136,6 +136,7 @@ typedef enum {
  * \returns a gphoto error code 
  */
 typedef int (*CameraExitFunc)      (Camera *camera, GPContext *context);
+
 /**
  * \brief Get a configuration tree for the camera and its driver
  *
@@ -158,6 +159,55 @@ typedef int (*CameraExitFunc)      (Camera *camera, GPContext *context);
 typedef int (*CameraGetConfigFunc) (Camera *camera, CameraWidget **widget,
 				    GPContext *context);
 /**
+ * \brief Get a configuration widget for a specific configuration
+ *
+ * \param camera the current camera
+ * \param name the name of the widget
+ * \param widget pointer to store the toplevel widget of the tree
+ * \param context the active #GPContext
+ *
+ * A camera driver can support configuration of either its own behaviour
+ * or the camera device itself. To allow a flexible driver framework,
+ * the camera driver provides a generic configuration widget tree to the
+ * frontend, which then renders it, allows user input and sends it back
+ * via the #CameraSetConfigFunc function to have the driver configure itself
+ * or the camera.
+ * 
+ * This specific function retrieves one specific named entry, and not the full
+ * tree to allow for querying specific settings faster.
+ *
+ * If you do not have configuration ability, there is no need to specify this
+ * function.
+ *
+ * \returns a gphoto error code
+ */
+typedef int (*CameraGetSingleConfigFunc) (Camera *camera, const char *name, CameraWidget **widget,
+				    GPContext *context);
+/**
+ * \brief List all configuration widgets for a specific configuration
+ *
+ * \param camera the current camera
+ * \param list the list of widgets available
+ * \param context the active #GPContext
+ *
+ * A camera driver can support configuration of either its own behaviour
+ * or the camera device itself. To allow a flexible driver framework,
+ * the camera driver provides a generic configuration widget tree to the
+ * frontend, which then renders it, allows user input and sends it back
+ * via the #CameraSetConfigFunc function to have the driver configure itself
+ * or the camera.
+ * 
+ * This specific function retrieves all the available configuration values in a flat list.
+ *
+ * This is different than the GetConfigFunc, which returns a configuration tree.
+ *
+ * If you do not have configuration ability, there is no need to specify this
+ * function.
+ *
+ * \returns a gphoto error code
+ */
+typedef int (*CameraListConfigFunc) (Camera *camera, CameraList *list, GPContext *context);
+/**
  * \brief Set the configuration in the camera
  *
  * \param camera the current camera 
@@ -172,6 +222,21 @@ typedef int (*CameraGetConfigFunc) (Camera *camera, CameraWidget **widget,
  */
 typedef int (*CameraSetConfigFunc) (Camera *camera, CameraWidget  *widget,
 				    GPContext *context);
+/**
+ * \brief Set a single configuration variable in the camera
+ *
+ * \param camera the current camera 
+ * \param name the widget to set
+ * \param widget the configuration widget tree that was changed
+ * \param context the active #GPContext
+ *
+ * This function is called in the driver after the configuration value is set.
+ * 
+ * \returns a gphoto error code
+ */
+typedef int (*CameraSetSingleConfigFunc) (Camera *camera, const char *name, CameraWidget  *widget,
+				    GPContext *context);
+
 typedef int (*CameraCaptureFunc)   (Camera *camera, CameraCaptureType type,
 				    CameraFilePath *path, GPContext *context);
 typedef int (*CameraTriggerCaptureFunc)   (Camera *camera, GPContext *context);
@@ -227,6 +292,10 @@ typedef struct _CameraFunctions {
 	CameraGetConfigFunc       get_config;	/**< \brief Called for requesting the configuration widgets. */
 	CameraSetConfigFunc       set_config;	/**< \brief Called after a configuration was changed */
 
+	CameraListConfigFunc      list_config;	/**< \brief Called for listing the available configuration widgets. */
+	CameraGetSingleConfigFunc get_single_config;	/**< \brief Called for requesteing a single widget. */
+	CameraSetSingleConfigFunc set_single_config;	/**< \brief Called for setting a single configuration widget. */
+
 	/* Capturing */
 	CameraCaptureFunc        capture;	/**< \brief Remote control the camera to capture */
 	CameraTriggerCaptureFunc trigger_capture;/**< \brief Remote control the camera to trigger capture */
@@ -316,8 +385,14 @@ int gp_camera_free 		 (Camera *camera);
 
 int gp_camera_get_config	 (Camera *camera, CameraWidget **window,
 				  GPContext *context);
+int gp_camera_list_config	 (Camera *camera, CameraList *list,
+				  GPContext *context);
+int gp_camera_get_single_config	 (Camera *camera, const char *name, CameraWidget **widget,
+				  GPContext *context);
 int gp_camera_set_config	 (Camera *camera, CameraWidget  *window,
 				  GPContext *context);
+int gp_camera_set_single_config	 (Camera *camera, const char *name, CameraWidget  *widget,
+				  GPContext *context);
 int gp_camera_get_summary	 (Camera *camera, CameraText *summary,
 				  GPContext *context);
 int gp_camera_get_manual	 (Camera *camera, CameraText *manual,
diff --git a/libgphoto2/gphoto2-camera.c b/libgphoto2/gphoto2-camera.c
index 2ff39fcb6..80effe435 100644
--- a/libgphoto2/gphoto2-camera.c
+++ b/libgphoto2/gphoto2-camera.c
@@ -876,6 +876,71 @@ gp_camera_get_config (Camera *camera, CameraWidget **window, GPContext *context)
 
 
 /**
+ * Retrieve a single configuration \c widget for the \c camera.
+ *
+ * @param camera a #Camera
+ * @param name the name of a configuration widget
+ * @param widget a #CameraWidget
+ * @param context a #GPContext
+ * @return gphoto2 error code
+ *
+ * This \c widget will then contain the current and the possible values and the type.
+ *
+ */
+int
+gp_camera_get_single_config (Camera *camera, const char *name, CameraWidget **widget, GPContext *context)
+{
+	C_PARAMS (camera);
+	CHECK_INIT (camera, context);
+
+	if (!camera->functions->get_single_config) {
+		gp_context_error (context, _("This camera does "
+			"not provide any configuration options."));
+		CAMERA_UNUSED (camera, context);
+                return (GP_ERROR_NOT_SUPPORTED);
+	}
+
+	CHECK_RESULT_OPEN_CLOSE (camera, camera->functions->get_single_config (
+					camera, name, widget, context), context);
+
+	CAMERA_UNUSED (camera, context);
+	return (GP_OK);
+}
+
+
+/**
+ * Retrieve a configuration \c list for the \c camera.
+ *
+ * @param camera a #Camera
+ * @param list a #CameraList
+ * @param context a #GPContext
+ * @return gphoto2 error code
+ *
+ * The names in list can be used for the single set and get configuration calls.
+ *
+ */
+int
+gp_camera_list_config (Camera *camera, CameraList *list, GPContext *context)
+{
+	C_PARAMS (camera);
+	CHECK_INIT (camera, context);
+
+	if (!camera->functions->list_config) {
+		gp_context_error (context, _("This camera does "
+			"not provide any configuration options."));
+		CAMERA_UNUSED (camera, context);
+                return (GP_ERROR_NOT_SUPPORTED);
+	}
+
+	CHECK_RESULT_OPEN_CLOSE (camera, camera->functions->list_config (
+					camera, list, context), context);
+
+	CAMERA_UNUSED (camera, context);
+	return (GP_OK);
+}
+
+
+/**
  * Sets the configuration.
  *
  * @param camera a #Camera
@@ -908,6 +973,39 @@ gp_camera_set_config (Camera *camera, CameraWidget *window, GPContext *context)
 }
 
 /**
+ * Set a single configuration \c widget for the \c camera.
+ *
+ * @param camera a #Camera
+ * @param name the name of a configuration widget
+ * @param widget a #CameraWidget
+ * @param context a #GPContext
+ * @return gphoto2 error code
+ *
+ * This \c widget contains the new value of the widget to set.
+ *
+ */
+int
+gp_camera_set_single_config (Camera *camera, const char *name, CameraWidget *widget, GPContext *context)
+{
+	C_PARAMS (camera);
+	CHECK_INIT (camera, context);
+
+	if (!camera->functions->set_single_config) {
+		gp_context_error (context, _("This camera does "
+			"not provide any configuration options."));
+		CAMERA_UNUSED (camera, context);
+                return (GP_ERROR_NOT_SUPPORTED);
+	}
+
+	CHECK_RESULT_OPEN_CLOSE (camera, camera->functions->set_single_config (
+					camera, name, widget, context), context);
+
+	CAMERA_UNUSED (camera, context);
+	return (GP_OK);
+}
+
+
+/**
  * Retrieves a camera summary.
  *
  * @param camera a #Camera
diff --git a/libgphoto2/libgphoto2.sym b/libgphoto2/libgphoto2.sym
index 96fbc19d7..3f7067344 100644
--- a/libgphoto2/libgphoto2.sym
+++ b/libgphoto2/libgphoto2.sym
@@ -32,15 +32,18 @@ gp_camera_free
 gp_camera_get_abilities
 gp_camera_get_about
 gp_camera_get_config
+gp_camera_get_single_config
 gp_camera_get_manual
 gp_camera_get_port_info
 gp_camera_get_port_speed
 gp_camera_get_summary
 gp_camera_init
+gp_camera_list_config
 gp_camera_new
 gp_camera_ref
 gp_camera_set_abilities
 gp_camera_set_config
+gp_camera_set_single_config
 gp_camera_set_port_info
 gp_camera_set_port_speed
 gp_camera_set_timeout_funcs