diff options
| -rw-r--r-- | doc/api/tmpl/gphoto2-context.sgml | 216 | ||||
| -rw-r--r-- | libgphoto2/gphoto2-camera.c | 19 | ||||
| -rw-r--r-- | libgphoto2/gphoto2-context.c | 5 | ||||
| -rw-r--r-- | libgphoto2/gphoto2-filesys.c | 16 |
4 files changed, 256 insertions, 0 deletions
diff --git a/doc/api/tmpl/gphoto2-context.sgml b/doc/api/tmpl/gphoto2-context.sgml new file mode 100644 index 000000000..ce94eb5a0 --- /dev/null +++ b/doc/api/tmpl/gphoto2-context.sgml @@ -0,0 +1,216 @@ +<!-- ##### SECTION Title ##### --> +GPContext + +<!-- ##### SECTION Short_Description ##### --> +The structure giving you control over operations + +<!-- ##### SECTION Long_Description ##### --> +<para> + This section describes how to monitor and control operations. +</para> + +<para> + Operations that involve communication with digital cameras can + take some time. For example, downloading an image over a slow serial + line can take several minutes. In order to be able to keep the frontend + responsive, to give the user the possibility to cancel operations, and in + order to be able to + report detailed error messages, #GPContext has been introduced. +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### STRUCT GPContext ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION gp_context_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION gp_context_ref ##### --> +<para> + +</para> + +@context: + + +<!-- ##### FUNCTION gp_context_unref ##### --> +<para> + +</para> + +@context: + + +<!-- ##### FUNCTION gp_context_set_progress_funcs ##### --> +<para> + +</para> + +@context: +@start_func: +@update_func: +@stop_func: +@data: + + +<!-- ##### FUNCTION gp_context_set_cancel_func ##### --> +<para> + +</para> + +@context: +@func: +@data: + + +<!-- ##### FUNCTION gp_context_set_question_func ##### --> +<para> + +</para> + +@context: +@func: +@data: + + +<!-- ##### FUNCTION gp_context_set_message_func ##### --> +<para> + +</para> + +@context: +@func: +@data: + + +<!-- ##### FUNCTION gp_context_set_idle_func ##### --> +<para> + +</para> + +@context: +@func: +@data: + + +<!-- ##### FUNCTION gp_context_set_error_func ##### --> +<para> + +</para> + +@context: +@func: +@data: + + +<!-- ##### FUNCTION gp_context_set_status_func ##### --> +<para> + +</para> + +@context: +@func: +@data: + + +<!-- ##### FUNCTION gp_context_progress_start ##### --> +<para> + +</para> + +@context: +@target: +@format: +@Varargs: +@Returns: + + +<!-- ##### FUNCTION gp_context_progress_update ##### --> +<para> + +</para> + +@context: +@id: +@current: + + +<!-- ##### FUNCTION gp_context_progress_stop ##### --> +<para> + +</para> + +@context: +@id: + + +<!-- ##### FUNCTION gp_context_message ##### --> +<para> + +</para> + +@context: +@format: +@Varargs: + + +<!-- ##### FUNCTION gp_context_status ##### --> +<para> + +</para> + +@context: +@format: +@Varargs: + + +<!-- ##### FUNCTION gp_context_question ##### --> +<para> + +</para> + +@context: +@format: +@Varargs: +@Returns: + + +<!-- ##### FUNCTION gp_context_error ##### --> +<para> + +</para> + +@context: +@format: +@Varargs: + + +<!-- ##### FUNCTION gp_context_idle ##### --> +<para> + +</para> + +@context: + + +<!-- ##### FUNCTION gp_context_cancel ##### --> +<para> + +</para> + +@context: +@Returns: + + diff --git a/libgphoto2/gphoto2-camera.c b/libgphoto2/gphoto2-camera.c index 754d774ab..23b0a61e4 100644 --- a/libgphoto2/gphoto2-camera.c +++ b/libgphoto2/gphoto2-camera.c @@ -242,6 +242,7 @@ struct _CameraPrivateCore { /** * gp_camera_exit: * @camera: a #Camera + * @context: a #GPContext * * Closes a connection to the camera and therefore gives other application * the possibility to access the camera, too. It is recommended that you @@ -603,6 +604,7 @@ gp_camera_free (Camera *camera) /** * gp_camera_init: * @camera: a #camera + * @context: a #GPContext * * Initiates a connection to the camera. Before calling this function, the * @camera should be set up using #gp_camera_set_port_path or @@ -767,6 +769,7 @@ gp_camera_init (Camera *camera, GPContext *context) * gp_camera_get_config: * @camera: a #Camera * @window: + * @context: a #GPContext * * Retrieves a configuration @window for the @camera. This window can be * used for construction of a configuration dialog. @@ -797,6 +800,7 @@ gp_camera_get_config (Camera *camera, CameraWidget **window, GPContext *context) * gp_camera_set_config: * @camera: a #Camera * @window: a #CameraWidget + * @context: a #GPContext * * Sets the configuration. Typically, a @window is retrieved using * #gp_camera_get_config and passed to this function in order to adjust @@ -828,6 +832,7 @@ gp_camera_set_config (Camera *camera, CameraWidget *window, GPContext *context) * gp_camera_get_summary: * @camera: a #Camera * @summary: a #CameraText + * @context: a #GPContext * * Retrieves a camera @summary. This summary typically contains information * like manufacturer, pictures taken, or generally information that is @@ -859,6 +864,7 @@ gp_camera_get_summary (Camera *camera, CameraText *summary, GPContext *context) * gp_camera_get_manual: * @camera: a #Camera * @manual: a #CameraText + * @context: a #GPContext * * Retrieves the @manual for given @camera. This manual typically contains * information about using the camera. @@ -889,6 +895,7 @@ gp_camera_get_manual (Camera *camera, CameraText *manual, GPContext *context) * gp_camera_get_about: * @camera: a #Camera * @about: a #CameraText + * @context: a #GPContext * * Retrieves information about the camera driver. Typically, this information * contains name and address of the author, acknowledgements, etc. @@ -920,6 +927,7 @@ gp_camera_get_about (Camera *camera, CameraText *about, GPContext *context) * @camera: a #Camera * @type: a #CameraCaptureType * @path: a #CameraFilePath + * @context: a #GPContext * * Captures an image, movie, or sound clip depending on the given @type. * The resulting file will be stored on the camera. The location gets stored @@ -951,6 +959,7 @@ gp_camera_capture (Camera *camera, CameraCaptureType type, * gp_camera_capture_preview: * @camera: a #Camera * @file: a #CameraFile + * @context: a #GPContext * * Captures a preview that won't be stored on the camera but returned in * supplied @file. For example, you could use #gp_capture_preview for @@ -985,6 +994,7 @@ gp_camera_capture_preview (Camera *camera, CameraFile *file, GPContext *context) * @camera: a #Camera * @folder: a folder * @list: a #CameraList + * @context: a #GPContext * * Lists the files in supplied @folder. * @@ -1014,6 +1024,7 @@ gp_camera_folder_list_files (Camera *camera, const char *folder, * @camera: a #Camera * @folder: a folder * @list: a #CameraList + * @context: a #GPContext * * Lists the folders in supplied @folder. * @@ -1042,6 +1053,7 @@ gp_camera_folder_list_folders (Camera *camera, const char* folder, * gp_camera_folder_delete_all: * @camera: a #Camera * @folder: a folder + * @context: a #GPContext * * Deletes all files in a given @folder. * @@ -1069,6 +1081,7 @@ gp_camera_folder_delete_all (Camera *camera, const char *folder, * @camera: a #Camera * @folder: a folder * @file: a #CameraFile + * @context: a #GPContext * * Uploads a file into given @folder. * @@ -1097,6 +1110,7 @@ gp_camera_folder_put_file (Camera *camera, const char *folder, * @folder: a folder * @file: the name of the file * @info: + * @context: a #GPContext * * Retrieves information about a @file. * @@ -1168,6 +1182,7 @@ gp_camera_file_get_info (Camera *camera, const char *folder, * @folder: a folder * @file: the name of a file * @info: the #CameraFileInfo + * @context: a #GPContext * * Sets some file properties like name or permissions. * @@ -1195,6 +1210,7 @@ gp_camera_file_set_info (Camera *camera, const char *folder, * @file: the name of a file * @type: the #CameraFileType * @camera_file: a #CameraFile + * @context: a #GPContext * * Retrieves a @file from the @camera. * @@ -1235,6 +1251,7 @@ gp_camera_file_get (Camera *camera, const char *folder, const char *file, * @camera: a #Camera * @folder: a folder * @file: the name of a file + * @context: a #GPContext * * Deletes the @file from a @folder. * @@ -1262,6 +1279,7 @@ gp_camera_file_delete (Camera *camera, const char *folder, const char *file, * @camera: a #Camera * @folder: the location where to create the new directory * @name: the name of the directory to be created + * @context: a #GPContext * * Creates a new directory called @name in given @folder. * @@ -1286,6 +1304,7 @@ gp_camera_folder_make_dir (Camera *camera, const char *folder, * @camera: a #Camera * @folder: the folder from which to remove the directory * @name: the name of the directory to be removed + * @context: a #GPContext * * Removes an (empty) directory called @name from the given @folder. * diff --git a/libgphoto2/gphoto2-context.c b/libgphoto2/gphoto2-context.c index 173da96a6..b14113eaf 100644 --- a/libgphoto2/gphoto2-context.c +++ b/libgphoto2/gphoto2-context.c @@ -26,6 +26,11 @@ #include <gphoto2-port-log.h> +/** + * GPContext: + * + * The internals of this structure are private. + **/ struct _GPContext { GPContextIdleFunc idle_func; diff --git a/libgphoto2/gphoto2-filesys.c b/libgphoto2/gphoto2-filesys.c index 27e79e37c..d399bdc5b 100644 --- a/libgphoto2/gphoto2-filesys.c +++ b/libgphoto2/gphoto2-filesys.c @@ -549,6 +549,7 @@ gp_filesystem_folder_number (CameraFilesystem *fs, const char *folder, * @fs: a #CameraFilesystem * @folder: the folder where to put the file in * @filename: filename of the file + * @context: a #GPContext * * Tells the @fs that there is a file called @filename in folder * called @folder. Usually, camera drivers will call this function after @@ -699,6 +700,7 @@ gp_filesystem_delete_all_one_by_one (CameraFilesystem *fs, const char *folder, * gp_filesystem_delete_all * @fs: a #CameraFilesystem * @folder: the folder in which to delete all files + * @context: a #GPContext * * Deletes all files in the given @folder from the @fs. If the @fs has not * been supplied with a delete_all_func, it tries to delete the files @@ -761,6 +763,7 @@ gp_filesystem_delete_all (CameraFilesystem *fs, const char *folder, * @fs: a #CameraFilesystem * @folder: a folder of which a file list should be generated * @list: a #CameraList where to put the list of files into + * @context: a #GPContext * * Lists the files in @folder using either cached values or (if there * aren't any) the file_list_func which (hopefully) has been previously @@ -823,6 +826,7 @@ gp_filesystem_list_files (CameraFilesystem *fs, const char *folder, * @fs: a #CameraFilesystem * @folder: a folder * @list: a #CameraList where subfolders should be listed + * @context: a #GPContext * * Generates a list of subfolders of the supplied @folder either using * cached values (if there are any) or the folder_list_func if it has been @@ -917,6 +921,7 @@ gp_filesystem_list_folders (CameraFilesystem *fs, const char *folder, * gp_filesystem_count: * @fs: a #CameraFilesystem * @folder: a folder in which to count the files + * @context: a #GPContext * * Counts the files in the @folder. * @@ -942,6 +947,7 @@ gp_filesystem_count (CameraFilesystem *fs, const char *folder, * @fs: a #CameraFilesystem * @folder: a folder in which to delete the file * @filename: the name of the file to delete + * @context: a #GPContext * * If a delete_file_func has been supplied to the @fs, this function will * be called and, if this function returns without error, the file will be @@ -1002,6 +1008,7 @@ gp_filesystem_delete_file_noop (CameraFilesystem *fs, const char *folder, * @fs: a #CameraFilesystem * @folder: the folder in which the directory should be created * @name: the name of the directory to be created + * @context: a #GPContext * * Creates a new directory called @name in given @folder. * @@ -1087,6 +1094,7 @@ gp_filesystem_remove_dir (CameraFilesystem *fs, const char *folder, * @fs: a #CameraFilesystem * @folder: the folder where to put the @file into * @file: the file + * @context: a #GPContext * * Uploads a file to the camera if a put_file_func has been previously * supplied to the @fs. If the upload is successful, the file will get @@ -1127,6 +1135,7 @@ gp_filesystem_put_file (CameraFilesystem *fs, const char *folder, * @folder: the folder where to look up the file with the @filenumber * @filenumber: the number of the file * @filename: + * @context: a #GPContext * * Looks up the @filename of file with given @filenumber in given @folder. * See gp_filesystem_number for exactly the opposite functionality. @@ -1161,6 +1170,7 @@ gp_filesystem_name (CameraFilesystem *fs, const char *folder, int filenumber, * @fs: a #CameraFilesystem * @folder: the folder where to look for file called @filename * @filename: the file to look for + * @context: a #GPContext * * Looks for a file called @filename in the given @folder. See * gp_filesystem_name for exactly the opposite functionality. @@ -1240,6 +1250,7 @@ gp_filesystem_scan (CameraFilesystem *fs, const char *folder, * @fs: a #CameraFilesystem * @filename: the name of the file to search in the @fs * @folder: + * @context: a #GPContext * * Searches a file called @filename in the @fs and returns the first * occurrency. This functionality is needed for camera drivers that cannot @@ -1461,6 +1472,7 @@ gp_filesystem_get_file_impl (CameraFilesystem *fs, const char *folder, * @filename: the name of the file to download * @type: the type of the file * @file: + * @context: a #GPContext * * Downloads the file called @filename from the @folder using the * get_file_func if such a function has been previously supplied. If the @@ -1618,6 +1630,7 @@ gp_filesystem_set_info_funcs (CameraFilesystem *fs, * @folder: * @filename: * @info: + * @context: a #GPContext * * Return value: a gphoto2 error code. **/ @@ -1681,6 +1694,7 @@ gp_filesystem_get_info (CameraFilesystem *fs, const char *folder, * @fs: a #CameraFilesystem * @folder: * @file: a #CameraFile + * @context: a #GPContext * * Tells the @fs about a file. Typically, camera drivers will call this * function in case they get information about a file (i.e. preview) "for free" @@ -1776,6 +1790,7 @@ gp_filesystem_set_file_noop (CameraFilesystem *fs, const char *folder, * @fs: a #CameraFilesystem * @folder: * @info: + * @context: a #GPContext * * In contrast to #gp_filesystem_set_info, #gp_filesystem_set_info_noop * will only change the file information in the @fs. Typically, camera @@ -1810,6 +1825,7 @@ gp_filesystem_set_info_noop (CameraFilesystem *fs, const char *folder, * @folder: * @filename: * @info: + * @context: a #GPContext * * Return value: a gphoto2 error code. **/ |