From 42dc42be81dfd3ebb8b1e337ddc2acf7d2b9555c Mon Sep 17 00:00:00 2001 From: Lutz Mueller Date: Sat, 27 Oct 2001 16:37:51 +0000 Subject: [PATCH] Again, documentation fixes git-svn-id: https://svn.code.sf.net/p/gphoto/code/trunk/libgphoto2@2802 67ed7778-7388-44ab-90cf-0a291f65f57c --- camlibs/canon/canon.c | 30 ----- doc/api/gphoto2-sections.txt | 12 -- doc/api/tmpl/gphoto2-camera.sgml | 102 -------------- doc/api/tmpl/gphoto2-unused.sgml | 93 +++++++++++++ frontends/command-line/gphoto2-cmd-config.c | 29 +--- frontends/command-line/gphoto2-cmd-config.h | 2 +- frontends/command-line/main.c | 2 +- libgphoto2/gphoto2-camera.c | 119 ----------------- libgphoto2/gphoto2-camera.h | 139 +++++++++++++++----- 9 files changed, 205 insertions(+), 323 deletions(-) diff --git a/camlibs/canon/canon.c b/camlibs/canon/canon.c index ee3dbee71..d256087ea 100644 --- a/camlibs/canon/canon.c +++ b/camlibs/canon/canon.c @@ -1480,32 +1480,6 @@ get_info_func (CameraFilesystem * fs, const char *folder, const char *filename, /****************************************************************************/ -static int -camera_file_get_config (Camera *camera, const char *folder, - const char *filename, CameraWidget ** window) -{ - return GP_ERROR_NOT_SUPPORTED; -} - -static int -camera_file_set_config (Camera *camera, const char *folder, - const char *filename, CameraWidget * window) -{ - return GP_ERROR_NOT_SUPPORTED; -} - -static int -camera_folder_get_config (Camera *camera, const char *folder, CameraWidget ** window) -{ - return GP_ERROR_NOT_SUPPORTED; -} - -static int -camera_folder_set_config (Camera *camera, const char *folder, CameraWidget * window) -{ - return GP_ERROR_NOT_SUPPORTED; -} - /** * This routine initializes the serial/USB port and also load the * camera settings. Right now it is only the speed that is @@ -1523,10 +1497,6 @@ camera_init (Camera *camera) camera->functions->exit = camera_exit; camera->functions->get_config = camera_get_config; camera->functions->set_config = camera_set_config; - camera->functions->file_get_config = camera_file_get_config; - camera->functions->file_set_config = camera_file_set_config; - camera->functions->folder_get_config = camera_folder_get_config; - camera->functions->folder_set_config = camera_folder_set_config; camera->functions->summary = camera_summary; camera->functions->manual = camera_manual; camera->functions->about = camera_about; diff --git a/doc/api/gphoto2-sections.txt b/doc/api/gphoto2-sections.txt index 5d7db23ba..8f33c9869 100644 --- a/doc/api/gphoto2-sections.txt +++ b/doc/api/gphoto2-sections.txt @@ -41,10 +41,6 @@ CameraExitFunc CameraGetConfigFunc CameraSetConfigFunc -CameraFolderGetConfigFunc -CameraFolderSetConfigFunc -CameraFileGetConfigFunc -CameraFileSetConfigFunc CameraCaptureFunc CameraCapturePreviewFunc @@ -53,8 +49,6 @@ CameraSummaryFunc CameraManualFunc CameraAboutFunc -CameraResultFunc - CameraPrivateLibrary CameraPrivateCore @@ -108,18 +102,12 @@ gp_camera_folder_list_folders gp_camera_folder_put_file gp_camera_folder_delete_all -gp_camera_folder_get_config -gp_camera_folder_set_config - gp_camera_file_get gp_camera_file_delete gp_camera_file_get_info gp_camera_file_set_info -gp_camera_file_get_config -gp_camera_file_set_config - gp_camera_get_manual gp_camera_get_summary gp_camera_get_about diff --git a/doc/api/tmpl/gphoto2-camera.sgml b/doc/api/tmpl/gphoto2-camera.sgml index 059dded53..d921d05c3 100644 --- a/doc/api/tmpl/gphoto2-camera.sgml +++ b/doc/api/tmpl/gphoto2-camera.sgml @@ -89,52 +89,6 @@ Error reporting can be performed using #gp_camera_set_error and #gp_camera_get_e @Returns: - - - - - -@camera: -@folder: -@widget: -@Returns: - - - - - - - -@camera: -@folder: -@widget: -@Returns: - - - - - - - -@camera: -@folder: -@file: -@widget: -@Returns: - - - - - - - -@camera: -@folder: -@file: -@widget: -@Returns: - - @@ -186,16 +140,6 @@ Error reporting can be performed using #gp_camera_set_error and #gp_camera_get_e @Returns: - - - - - -@camera: -@result: -@Returns: - - @@ -549,28 +493,6 @@ Error reporting can be performed using #gp_camera_set_error and #gp_camera_get_e @Returns: - - - - - -@camera: -@folder: -@window: -@Returns: - - - - - - - -@camera: -@folder: -@window: -@Returns: - - @@ -619,30 +541,6 @@ Error reporting can be performed using #gp_camera_set_error and #gp_camera_get_e @Returns: - - - - - -@camera: -@folder: -@file: -@window: -@Returns: - - - - - - - -@camera: -@folder: -@file: -@window: -@Returns: - - diff --git a/doc/api/tmpl/gphoto2-unused.sgml b/doc/api/tmpl/gphoto2-unused.sgml index 22d6eb71b..9dd2330af 100644 --- a/doc/api/tmpl/gphoto2-unused.sgml +++ b/doc/api/tmpl/gphoto2-unused.sgml @@ -38,9 +38,102 @@ CameraAbilities CameraAbilities + + + + + +@camera: +@folder: +@file: +@widget: +@Returns: + + + + + + +@camera: +@folder: +@file: +@widget: +@Returns: + + + + + + +@camera: +@folder: +@widget: +@Returns: + + + + + + +@camera: +@folder: +@widget: +@Returns: + + + + + + +@camera: +@result: +@Returns: + + + + + + +@camera: +@folder: +@file: +@window: +@Returns: + + + + + + +@camera: +@folder: +@file: +@window: +@Returns: + + + + + + +@camera: +@folder: +@window: +@Returns: + + + + + + +@camera: +@folder: +@window: +@Returns: + diff --git a/frontends/command-line/gphoto2-cmd-config.c b/frontends/command-line/gphoto2-cmd-config.c index 97b60d343..65035e7d0 100644 --- a/frontends/command-line/gphoto2-cmd-config.c +++ b/frontends/command-line/gphoto2-cmd-config.c @@ -48,8 +48,6 @@ typedef struct { Camera *camera; CDKSCREEN *screen; - const char *folder; - const char *file; CameraWidget *window; } CmdConfig; @@ -58,18 +56,7 @@ static int show_widget (CmdConfig *cmd_config, CameraWidget *widget); static int set_config (CmdConfig *cmd_config) { - if (cmd_config->file) - return (gp_camera_file_set_config (cmd_config->camera, - cmd_config->folder, - cmd_config->file, - cmd_config->window)); - else if (cmd_config->folder) - return (gp_camera_folder_set_config (cmd_config->camera, - cmd_config->folder, - cmd_config->window)); - else - return (gp_camera_set_config (cmd_config->camera, - cmd_config->window)); + return (gp_camera_set_config (cmd_config->camera, cmd_config->window)); } static int @@ -284,7 +271,7 @@ status_func (Camera *camera, const char *status, void *data) } int -gp_cmd_config (Camera *camera, const char *folder, const char *file) +gp_cmd_config (Camera *camera) { CmdConfig cmd_config; CameraWidget *config; @@ -295,15 +282,7 @@ gp_cmd_config (Camera *camera, const char *folder, const char *file) if (!camera) return (GP_ERROR_BAD_PARAMETERS); - if (file) { - if (!folder) - return (GP_ERROR_BAD_PARAMETERS); - result = gp_camera_file_get_config (camera, folder, file, - &config); - } else if (folder) - result = gp_camera_folder_get_config (camera, folder, &config); - else - result = gp_camera_get_config (camera, &config); + result = gp_camera_get_config (camera, &config); if (result < 0) return (result); @@ -316,8 +295,6 @@ gp_cmd_config (Camera *camera, const char *folder, const char *file) /* Go! */ cmd_config.camera = camera; - cmd_config.folder = folder; - cmd_config.file = file; cmd_config.screen = screen; cmd_config.window = config; gp_camera_set_status_func (camera, status_func, &cmd_config); diff --git a/frontends/command-line/gphoto2-cmd-config.h b/frontends/command-line/gphoto2-cmd-config.h index ffc35010c..b0ea9ff97 100644 --- a/frontends/command-line/gphoto2-cmd-config.h +++ b/frontends/command-line/gphoto2-cmd-config.h @@ -23,6 +23,6 @@ #include -int gp_cmd_config (Camera *camera, const char *folder, const char *file); +int gp_cmd_config (Camera *camera); #endif /* __GPHOTO2_CMD_CONFIG_H__ */ diff --git a/frontends/command-line/main.c b/frontends/command-line/main.c index edea26b01..a556f7425 100644 --- a/frontends/command-line/main.c +++ b/frontends/command-line/main.c @@ -590,7 +590,7 @@ OPTION_CALLBACK(config) { CHECK_RESULT (set_globals ()); - CHECK_RESULT (gp_cmd_config (glob_camera, NULL, NULL)); + CHECK_RESULT (gp_cmd_config (glob_camera)); return (GP_OK); } diff --git a/libgphoto2/gphoto2-camera.c b/libgphoto2/gphoto2-camera.c index ef21f3e91..de64baa8d 100644 --- a/libgphoto2/gphoto2-camera.c +++ b/libgphoto2/gphoto2-camera.c @@ -961,66 +961,6 @@ gp_camera_folder_put_file (Camera *camera, const char *folder, CameraFile *file) return (GP_OK); } -/** - * gp_camera_folder_get_config: - * @camera: a #Camera - * @folder: a folder - * @window: a #CameraWidget - * - * Retrieves the configuration @window of a @folder. This function is similar - * to #gp_camera_get_config. The only difference is that it operates on a - * folder. - * - * Return value: a gphoto2 error code - **/ -int -gp_camera_folder_get_config (Camera *camera, const char *folder, - CameraWidget **window) -{ - CHECK_NULL (camera && folder && window); - - if (!camera->functions->folder_get_config) { - gp_log (GP_LOG_ERROR, "gphoto2-camera", _("The camera does " - "not offer any configuration options for folders")); - return (GP_ERROR_NOT_SUPPORTED); - } - - CHECK_RESULT_OPEN_CLOSE (camera, camera->functions->folder_get_config ( - camera, folder, window)); - - return (GP_OK); -} - -/** - * gp_camera_folder_set_config: - * @camera: a #Camera - * @folder: a folder - * @window: a #CameraWidget - * - * Sets the folder configuration. See #gp_camera_set_config and - * #gp_camera_folder_get_config for details. - * - * Return value: a gphoto2 error code - **/ -int -gp_camera_folder_set_config (Camera *camera, const char *folder, - CameraWidget *window) -{ - CHECK_NULL (camera && folder && window); - - if (!camera->functions->folder_set_config) { - gp_log (GP_LOG_ERROR, "gphoto2-camera", _("The camera does " - "not support setting configuration options on " - "folders")); - return (GP_ERROR_NOT_SUPPORTED); - } - - CHECK_RESULT_OPEN_CLOSE (camera, camera->functions->folder_set_config ( - camera, folder, window)); - - return (GP_OK); -} - /** * gp_camera_file_get_info: * @camera: a #Camera @@ -1160,65 +1100,6 @@ gp_camera_file_get (Camera *camera, const char *folder, const char *file, return (GP_OK); } -/** - * gp_camera_file_get_config: - * @camera: a #Camera - * @folder: a folder - * @file: the name of a file - * @window: - * - * Gets a configuration window for a given @file. See #gp_camera_get_config - * and #gp_camera_set_config. - * - * Return value: a gphoto2 error code - **/ -int -gp_camera_file_get_config (Camera *camera, const char *folder, - const char *file, CameraWidget **window) -{ - CHECK_NULL (camera && folder && file && window); - - if (!camera->functions->file_get_config) { - gp_log (GP_LOG_ERROR, "gphoto2-camera", _("This camera does " - "not offer configuration options for files")); - return (GP_ERROR_NOT_SUPPORTED); - } - - CHECK_RESULT_OPEN_CLOSE (camera, camera->functions->file_get_config ( - camera, folder, file, window)); - - return (GP_OK); -} - -/** - * gp_camera_file_set_config: - * @camera: a #Camera - * @folder: a folder - * @file: the name of a file - * @window: a #CameraWidget - * - * Sets the configuration of a file. See #gp_camera_set_config. - * - * Return value: a gphoto2 error code - **/ -int -gp_camera_file_set_config (Camera *camera, const char *folder, - const char *file, CameraWidget *window) -{ - CHECK_NULL (camera && window && folder && file); - - if (!camera->functions->file_set_config) { - gp_log (GP_LOG_ERROR, "gphoto2-camera", _("This camera does " - "not support setting configuration options on files")); - return (GP_ERROR_NOT_SUPPORTED); - } - - CHECK_RESULT_OPEN_CLOSE (camera, camera->functions->file_set_config ( - camera, folder, file, window)); - - return (GP_OK); -} - /** * gp_camera_file_delete: * @camera: a #Camera diff --git a/libgphoto2/gphoto2-camera.h b/libgphoto2/gphoto2-camera.h index bbd7307aa..30a3d08be 100644 --- a/libgphoto2/gphoto2-camera.h +++ b/libgphoto2/gphoto2-camera.h @@ -48,44 +48,131 @@ typedef enum { GP_CAPTURE_SOUND } CameraCaptureType; +/** + * CameraExitFunc: + * @camera: a #Camera + * + * Implement this function in camera drivers if you need to clean up on + * exit. You need this function for example if you use camera->pl and + * allocated memory for that on #camera_init. Then, you would free the + * memory here. + * + * Return value: a gphoto2 error code + **/ typedef int (*CameraExitFunc) (Camera *camera); -/* Configuration */ +/** + * CameraGetConfigFunc: + * @camera: a #Camera + * @widget: + * + * Implement this function if your camera supports some configuration + * operations (like adjusting exposure). + * + * Return value: a gphoto2 error code + **/ typedef int (*CameraGetConfigFunc) (Camera *camera, CameraWidget **widget); -typedef int (*CameraSetConfigFunc) (Camera *camera, CameraWidget *widget); -typedef int (*CameraFolderGetConfigFunc) (Camera *camera, const char *folder, - CameraWidget **widget); -typedef int (*CameraFolderSetConfigFunc) (Camera *camera, const char *folder, - CameraWidget *widget); -typedef int (*CameraFileGetConfigFunc) (Camera *camera, const char *folder, - const char *file, - CameraWidget **widget); -typedef int (*CameraFileSetConfigFunc) (Camera *camera, const char *folder, - const char *file, CameraWidget *widget); -/* Capturing */ +/** + * CameraSetConfigFunc: + * @camera: a #Camera + * @widget: a #CameraWidget + * + * If you implement the #CameraGetConfigFunc, you should also implement this + * function in order to make it possible for frontends to actually adjust + * configuration options. Parse the @widget tree and check for each item + * if the value has been changed (using #gp_widget_changed). If this is the + * case, adjust this configuration option on the camera. + * + * Return value: a gphoto2 error code + **/ +typedef int (*CameraSetConfigFunc) (Camera *camera, CameraWidget *widget); + +/** + * CameraCaptureFunc: + * @camera: a #Camera + * @type: a #CameraCaptureType + * @path: a #CameraFilePath + * + * Implement this function if your camera supports remote capturing of images. + * When capturing an image, this image needs to be saved on the camera. The + * location of the image on the camera should then be written into + * supplied @path so that the frontend will know where to get the + * newly captured image from. Don't forget to tell the #CameraFilesystem + * (camera->fs) that a new picture is on the camera using + * #gp_filesystem_append. + * + * Return value: a gphoto2 error code + **/ typedef int (*CameraCaptureFunc) (Camera *camera, CameraCaptureType type, CameraFilePath *path); + +/** + * CameraCapturePreviewFunc: + * @camera: a #Camera + * @file: a #CameraFile + * + * Implement this function if your camera supports capturing + * previews of low resolution. Those previews must not be stored on the camera. + * They need to be written to the supplied @file (using for example + * #gp_file_set_data_and_size). + * + * Return value: a gphoto2 error code + **/ typedef int (*CameraCapturePreviewFunc) (Camera *camera, CameraFile *file); -/* Textual information */ +/** + * CameraSummaryFunc: + * @camera: a #Camera + * @text: a #CameraText + * + * Implement this function if your camera provides static information and + * non-configurable data like serial number or number of pictures taken. All + * configurable data should be displayed through #CameraGetConfigFunc + * instead. + * + * Return value: a gphoto2 error code + **/ typedef int (*CameraSummaryFunc) (Camera *camera, CameraText *text); + +/** + * CameraManualFunc: + * @camera: a #Camera + * @text: a #CameraText + * + * Implement this function if you need to give the user instructions on + * how to use his camera. Here, you can for example inform the user about known + * limitations of the protocol. + * + * Return value: a gphoto2 error code + **/ typedef int (*CameraManualFunc) (Camera *camera, CameraText *text); + +/** + * CameraAboutFunc: + * @camera: a #Camera + * @text: a #CameraText + * + * Implement this function if you want to give frontends the possibility to + * inform users who wrote this driver or who contributed to it. + * + * Return value: a gphoto2 error code + **/ typedef int (*CameraAboutFunc) (Camera *camera, CameraText *text); -/* Error reporting */ -typedef const char *(*CameraResultFunc) (Camera *camera, int result); - +/** + * CameraFunctions: + * + * Those functions are optionally. Depending on the features of the protocol, + * you would implement some functions and leave others out. Tell gphoto2 + * what functions you provide on #camera_init. + **/ typedef struct { CameraExitFunc exit; /* Configuration */ CameraGetConfigFunc get_config; CameraSetConfigFunc set_config; - CameraFolderGetConfigFunc folder_get_config; - CameraFolderSetConfigFunc folder_set_config; - CameraFileGetConfigFunc file_get_config; - CameraFileSetConfigFunc file_set_config; /* Capturing */ CameraCaptureFunc capture; @@ -169,8 +256,6 @@ int gp_camera_capture_preview (Camera *camera, CameraFile *file); * - list_folders: Get a list of folders in this folder * * - delete_all : Delete all files in this folder * * - put_file : Upload a file into this folder * - * - get_config : Get configuration options of a folder * - * - set_config : Set those configuration options * ************************************************************************/ int gp_camera_folder_list_files (Camera *camera, const char *folder, @@ -180,10 +265,6 @@ int gp_camera_folder_list_folders (Camera *camera, const char *folder, int gp_camera_folder_delete_all (Camera *camera, const char *folder); int gp_camera_folder_put_file (Camera *camera, const char *folder, CameraFile *file); -int gp_camera_folder_get_config (Camera *camera, const char *folder, - CameraWidget **window); -int gp_camera_folder_set_config (Camera *camera, const char *folder, - CameraWidget *window); /************************************************************************ * Part III: * @@ -192,8 +273,6 @@ int gp_camera_folder_set_config (Camera *camera, const char *folder, * - get_info : Get specific information about a file * * - set_info : Set specific parameters of a file * * - get_file : Get a file * - * - get_config : Get additional configuration options of a file * - * - set_config : Set those additional configuration options * * - delete : Delete a file * ************************************************************************/ @@ -204,10 +283,6 @@ int gp_camera_file_set_info (Camera *camera, const char *folder, int gp_camera_file_get (Camera *camera, const char *folder, const char *file, CameraFileType type, CameraFile *camera_file); -int gp_camera_file_get_config (Camera *camera, const char *folder, - const char *file, CameraWidget **window); -int gp_camera_file_set_config (Camera *camera, const char *folder, - const char *file, CameraWidget *window); int gp_camera_file_delete (Camera *camera, const char *folder, const char *file);