From 023fdc5150deffde1ccfeb56d3bf4bddcd59177f Mon Sep 17 00:00:00 2001 From: Caelan Sayler Date: Fri, 27 Jun 2025 12:28:19 +0100 Subject: [PATCH] Update the lib-cpp rust docs --- src/lib-cpp/include/Velopack.h | 107 ++++++++++++++++++++++++++++----- src/lib-cpp/src/lib.rs | 99 ++++++++++++++++++++++++++---- src/lib-cpp/src/types.rs | 2 +- 3 files changed, 182 insertions(+), 26 deletions(-) diff --git a/src/lib-cpp/include/Velopack.h b/src/lib-cpp/include/Velopack.h index 7c0f1aa9..93824928 100644 --- a/src/lib-cpp/include/Velopack.h +++ b/src/lib-cpp/include/Velopack.h @@ -107,7 +107,7 @@ typedef struct vpkc_update_options_t { */ bool AllowVersionDowngrade; /** - * **This option should usually be left None**. + * **This option should usually be left None/NULL**. * Overrides the default channel used to fetch updates. * The default channel will be whatever channel was specified on the command line when building this release. * For example, if the current release was packaged with '--channel beta', then the default channel will be 'beta'. @@ -209,11 +209,15 @@ extern "C" { /** * Create a new FileSource update source for a given file path. + * @param psz_file_path The path to a local directory containing updates. + * @returns A new vpkc_update_source_t instance, or null on error. */ vpkc_update_source_t *vpkc_new_source_file(const char *psz_file_path); /** * Create a new HttpSource update source for a given HTTP URL. + * @param psz_http_url The URL to a remote update server. + * @returns A new vpkc_update_source_t instance, or null on error. */ vpkc_update_source_t *vpkc_new_source_http_url(const char *psz_http_url); @@ -223,6 +227,11 @@ vpkc_update_source_t *vpkc_new_source_http_url(const char *psz_http_url); * for the lifetime of any UpdateManager's that use this source. You should call `vpkc_free_source` to free the source, * but note that if the source is still in use by an UpdateManager, it will not be freed until the UpdateManager is freed. * Therefore to avoid possible issues, it is recommended to create this type of source once for the lifetime of your application. + * @param cb_release_feed A callback to fetch the release feed. + * @param cb_free_release_feed A callback to free the memory allocated by `cb_release_feed`. + * @param cb_download_entry A callback to download an asset. + * @param p_user_data Optional user data to be passed to the callbacks. + * @returns A new vpkc_update_source_t instance, or null on error. */ vpkc_update_source_t *vpkc_new_source_custom_callback(vpkc_release_feed_delegate_t cb_release_feed, vpkc_free_release_feed_t cb_free_release_feed, @@ -232,19 +241,24 @@ vpkc_update_source_t *vpkc_new_source_custom_callback(vpkc_release_feed_delegate /** * Sends a progress update to the callback with the specified ID. This is used by custom * update sources created with `vpkc_new_source_custom_callback` to report download progress. + * @param progress_callback_id The ID of the progress callback to send the update to. + * @param progress The progress value to send (0-100). */ void vpkc_source_report_progress(size_t progress_callback_id, int16_t progress); /** * Frees a vpkc_update_source_t instance. + * @param p_source The source to free. */ void vpkc_free_source(vpkc_update_source_t *p_source); /** * Create a new UpdateManager instance. - * @param urlOrPath Location of the update server or path to the local update directory. - * @param options Optional extra configuration for update manager. - * @param locator Override the default locator configuration (usually used for testing / mocks). + * @param psz_url_or_path Location of the http update server url or path to the local update directory. + * @param p_options Optional extra configuration for update manager. + * @param p_locator Optional explicit path configuration for Velopack. If null, the default locator will be used. + * @param p_manager A pointer to where the new vpkc_update_manager_t* instance will be stored. + * @returns True if the update manager was created successfully, false otherwise. If false, the error will be available via `vpkc_get_last_error`. */ bool vpkc_new_update_manager(const char *psz_url_or_path, struct vpkc_update_options_t *p_options, @@ -253,9 +267,11 @@ bool vpkc_new_update_manager(const char *psz_url_or_path, /** * Create a new UpdateManager instance with a custom UpdateSource. - * @param urlOrPath Location of the update server or path to the local update directory. - * @param options Optional extra configuration for update manager. - * @param locator Override the default locator configuration (usually used for testing / mocks). + * @param p_source A pointer to a custom UpdateSource. + * @param p_options Optional extra configuration for update manager. + * @param p_locator Optional explicit path configuration for Velopack. If null, the default locator will be used. + * @param p_manager A pointer to where the new vpkc_update_manager_t* instance will be stored. + * @returns True if the update manager was created successfully, false otherwise. If false, the error will be available via `vpkc_get_last_error`. */ bool vpkc_new_update_manager_with_source(vpkc_update_source_t *p_source, struct vpkc_update_options_t *p_options, @@ -264,6 +280,10 @@ bool vpkc_new_update_manager_with_source(vpkc_update_source_t *p_source, /** * Returns the currently installed version of the app. + * @param p_manager The update manager instance. + * @param psz_version A buffer to store the version string. + * @param c_version The size of the `psz_version` buffer. + * @returns The number of characters written to `psz_version` (including null terminator), or the required buffer size if the buffer is too small. */ size_t vpkc_get_current_version(vpkc_update_manager_t *p_manager, char *psz_version, @@ -271,24 +291,38 @@ size_t vpkc_get_current_version(vpkc_update_manager_t *p_manager, /** * Returns the currently installed app id. + * @param p_manager The update manager instance. + * @param psz_id A buffer to store the app id string. + * @param c_id The size of the `psz_id` buffer. + * @returns The number of characters written to `psz_id` (including null terminator), or the required buffer size if the buffer is too small. */ -size_t vpkc_get_app_id(vpkc_update_manager_t *p_manager, char *psz_id, size_t c_id); +size_t vpkc_get_app_id(vpkc_update_manager_t *p_manager, + char *psz_id, + size_t c_id); /** * Returns whether the app is in portable mode. On Windows this can be true or false. * On MacOS and Linux this will always be true. + * @param p_manager The update manager instance. + * @returns True if the app is in portable mode, false otherwise. */ bool vpkc_is_portable(vpkc_update_manager_t *p_manager); /** - * Returns an UpdateInfo object if there is an update downloaded which still needs to be applied. - * You can pass the UpdateInfo object to waitExitThenApplyUpdate to apply the update. + * Returns an asset if there is an update downloaded which still needs to be applied. + * You can pass this asset to `vpkc_wait_exit_then_apply_updates` to apply the update. + * @param p_manager The update manager instance. + * @param p_asset A pointer to where the new vpkc_asset_t* instance will be stored. + * @returns True if there is an update pending restart, false otherwise. */ bool vpkc_update_pending_restart(vpkc_update_manager_t *p_manager, struct vpkc_asset_t **p_asset); /** - * Checks for updates, returning None if there are none available. If there are updates available, this method will return an + * Checks for updates. If there are updates available, this method will return an * UpdateInfo object containing the latest available release, and any delta updates that can be applied if they are available. + * @param p_manager The update manager instance. + * @param p_update A pointer to where the new vpkc_update_info_t* instance will be stored if an update is available. + * @returns A `vpkc_update_check_t` value indicating the result of the check. If an update is available, the value will be `HasUpdate` and `p_update` will be populated. */ vpkc_update_check_t vpkc_check_for_updates(vpkc_update_manager_t *p_manager, struct vpkc_update_info_t **p_update); @@ -300,6 +334,11 @@ vpkc_update_check_t vpkc_check_for_updates(vpkc_update_manager_t *p_manager, * this method will attempt to unpack and prepare them. * - If there is no delta update available, or there is an error preparing delta * packages, this method will fall back to downloading the full version of the update. + * @param p_manager The update manager instance. + * @param p_update The update info object from `vpkc_check_for_updates`. + * @param cb_progress An optional callback to report download progress (0-100). + * @param p_user_data Optional user data to be passed to the progress callback. + * @returns true on success, false on failure. If false, the error will be available via `vpkc_get_last_error`. */ bool vpkc_download_updates(vpkc_update_manager_t *p_manager, struct vpkc_update_info_t *p_update, @@ -309,7 +348,14 @@ bool vpkc_download_updates(vpkc_update_manager_t *p_manager, /** * This will launch the Velopack updater and tell it to wait for this program to exit gracefully. * You should then clean up any state and exit your app. The updater will apply updates and then - * optionally restart your app. The updater will only wait for 60 seconds before giving up. + * (if specified) restart your app. The updater will only wait for 60 seconds before giving up. + * @param p_manager The update manager instance. + * @param p_asset The asset to apply. This can be from `vpkc_update_pending_restart` or `vpkc_update_info_get_target_asset`. + * @param b_silent True to attempt to apply the update without showing any UI. + * @param b_restart True to restart the app after the update is applied. + * @param p_restart_args An array of command line arguments to pass to the new process when it's restarted. + * @param c_restart_args The number of arguments in `p_restart_args`. + * @returns true on success, false on failure. If false, the error will be available via `vpkc_get_last_error`. */ bool vpkc_wait_exit_then_apply_updates(vpkc_update_manager_t *p_manager, struct vpkc_asset_t *p_asset, @@ -323,6 +369,14 @@ bool vpkc_wait_exit_then_apply_updates(vpkc_update_manager_t *p_manager, * This method is unsafe because it does not necessarily wait for any / the correct process to exit * before applying updates. The `vpkc_wait_exit_then_apply_updates` method is recommended for most use cases. * If dw_wait_pid is 0, the updater will not wait for any process to exit before applying updates (Not Recommended). + * @param p_manager The update manager instance. + * @param p_asset The asset to apply. This can be from `vpkc_update_pending_restart` or `vpkc_update_info_get_target_asset`. + * @param b_silent True to attempt to apply the update without showing any UI. + * @param dw_wait_pid The process ID to wait for before applying updates. If 0, the updater will not wait. + * @param b_restart True to restart the app after the update is applied. + * @param p_restart_args An array of command line arguments to pass to the new process when it's restarted. + * @param c_restart_args The number of arguments in `p_restart_args`. + * @returns true on success, false on failure. If false, the error will be available via `vpkc_get_last_error`. */ bool vpkc_unsafe_apply_updates(vpkc_update_manager_t *p_manager, struct vpkc_asset_t *p_asset, @@ -334,90 +388,115 @@ bool vpkc_unsafe_apply_updates(vpkc_update_manager_t *p_manager, /** * Frees a vpkc_update_manager_t instance. + * @param p_manager The update manager instance to free. */ void vpkc_free_update_manager(vpkc_update_manager_t *p_manager); /** * Frees a vpkc_update_info_t instance. + * @param p_update_info The update info instance to free. */ void vpkc_free_update_info(struct vpkc_update_info_t *p_update_info); /** * Frees a vpkc_asset_t instance. + * @param p_asset The asset instance to free. */ void vpkc_free_asset(struct vpkc_asset_t *p_asset); /** * VelopackApp helps you to handle app activation events correctly. * This should be used as early as possible in your application startup code. - * (eg. the beginning of main() or wherever your entry point is) + * (eg. the beginning of main() or wherever your entry point is). + * This function will not return in some cases. + * @param p_user_data Optional user data to be passed to the callbacks. */ void vpkc_app_run(void *p_user_data); /** * Set whether to automatically apply downloaded updates on startup. This is ON by default. + * @param b_auto_apply True to automatically apply updates, false otherwise. */ void vpkc_app_set_auto_apply_on_startup(bool b_auto_apply); /** * Override the command line arguments used by VelopackApp. (by default this is env::args().skip(1)) + * @param p_args An array of command line arguments. + * @param c_args The number of arguments in `p_args`. */ void vpkc_app_set_args(char **p_args, size_t c_args); /** * VelopackLocator provides some utility functions for locating the current app important paths (eg. path to packages, update binary, and so forth). + * @param p_locator The locator configuration to use. */ void vpkc_app_set_locator(struct vpkc_locator_config_t *p_locator); /** + * Sets a callback to be run after the app is installed. * WARNING: FastCallback hooks are run during critical stages of Velopack operations. * Your code will be run and then the process will exit. * If your code has not completed within 30 seconds, it will be terminated. * Only supported on windows; On other operating systems, this will never be called. + * @param cb_after_install The callback to run after the app is installed. The callback takes a user data pointer and the version of the app as a string. */ void vpkc_app_set_hook_after_install(vpkc_hook_callback_t cb_after_install); /** + * Sets a callback to be run before the app is uninstalled. * WARNING: FastCallback hooks are run during critical stages of Velopack operations. * Your code will be run and then the process will exit. * If your code has not completed within 30 seconds, it will be terminated. * Only supported on windows; On other operating systems, this will never be called. + * @param cb_before_uninstall The callback to run before the app is uninstalled. The callback takes a user data pointer and the version of the app as a string. */ void vpkc_app_set_hook_before_uninstall(vpkc_hook_callback_t cb_before_uninstall); /** + * Sets a callback to be run before the app is updated. * WARNING: FastCallback hooks are run during critical stages of Velopack operations. * Your code will be run and then the process will exit. * If your code has not completed within 30 seconds, it will be terminated. * Only supported on windows; On other operating systems, this will never be called. + * @param cb_before_update The callback to run before the app is updated. The callback takes a user data pointer and the version of the app as a string. */ void vpkc_app_set_hook_before_update(vpkc_hook_callback_t cb_before_update); /** + * Sets a callback to be run after the app is updated. * WARNING: FastCallback hooks are run during critical stages of Velopack operations. * Your code will be run and then the process will exit. * If your code has not completed within 30 seconds, it will be terminated. * Only supported on windows; On other operating systems, this will never be called. + * @param cb_after_update The callback to run after the app is updated. The callback takes a user data pointer and the version of the app as a string. */ void vpkc_app_set_hook_after_update(vpkc_hook_callback_t cb_after_update); /** * This hook is triggered when the application is started for the first time after installation. + * @param cb_first_run The callback to run on first run. The callback takes a user data pointer and the version of the app as a string. */ void vpkc_app_set_hook_first_run(vpkc_hook_callback_t cb_first_run); /** * This hook is triggered when the application is restarted by Velopack after installing updates. + * @param cb_restarted The callback to run after the app is restarted. The callback takes a user data pointer and the version of the app as a string. */ void vpkc_app_set_hook_restarted(vpkc_hook_callback_t cb_restarted); /** * Get the last error message that occurred in the Velopack library. + * @param psz_error A buffer to store the error message. + * @param c_error The size of the `psz_error` buffer. + * @returns The number of characters written to `psz_error` (including null terminator). If the return value is greater than `c_error`, the buffer was too small and the message was truncated. */ -size_t vpkc_get_last_error(char *psz_error, size_t c_error); +size_t vpkc_get_last_error(char *psz_error, + size_t c_error); /** * Set a custom log callback. This will be called for all log messages generated by the Velopack library. + * @param cb_log The callback to call with log messages. The callback takes a user data pointer, a log level, and the log message as a string. + * @param p_user_data Optional user data to be passed to the callback. */ void vpkc_set_logger(vpkc_log_callback_t cb_log, void *p_user_data); diff --git a/src/lib-cpp/src/lib.rs b/src/lib-cpp/src/lib.rs index ffe16e16..b68734f1 100644 --- a/src/lib-cpp/src/lib.rs +++ b/src/lib-cpp/src/lib.rs @@ -20,6 +20,8 @@ use velopack::logging::{default_logfile_path, init_logging}; use velopack::{sources, ApplyWaitMode, Error as VelopackError, UpdateCheck, UpdateManager, VelopackApp}; /// Create a new FileSource update source for a given file path. +/// @param psz_file_path The path to a local directory containing updates. +/// @returns A new vpkc_update_source_t instance, or null on error. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -33,6 +35,8 @@ pub extern "C" fn vpkc_new_source_file(psz_file_path: *const c_char) -> *mut vpk } /// Create a new HttpSource update source for a given HTTP URL. +/// @param psz_http_url The URL to a remote update server. +/// @returns A new vpkc_update_source_t instance, or null on error. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -50,6 +54,11 @@ pub extern "C" fn vpkc_new_source_http_url(psz_http_url: *const c_char) -> *mut /// for the lifetime of any UpdateManager's that use this source. You should call `vpkc_free_source` to free the source, /// but note that if the source is still in use by an UpdateManager, it will not be freed until the UpdateManager is freed. /// Therefore to avoid possible issues, it is recommended to create this type of source once for the lifetime of your application. +/// @param cb_release_feed A callback to fetch the release feed. +/// @param cb_free_release_feed A callback to free the memory allocated by `cb_release_feed`. +/// @param cb_download_entry A callback to download an asset. +/// @param p_user_data Optional user data to be passed to the callbacks. +/// @returns A new vpkc_update_source_t instance, or null on error. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -76,12 +85,15 @@ pub extern "C" fn vpkc_new_source_custom_callback( /// Sends a progress update to the callback with the specified ID. This is used by custom /// update sources created with `vpkc_new_source_custom_callback` to report download progress. +/// @param progress_callback_id The ID of the progress callback to send the update to. +/// @param progress The progress value to send (0-100). #[no_mangle] pub extern "C" fn vpkc_source_report_progress(progress_callback_id: size_t, progress: i16) { report_csource_progress(progress_callback_id, progress); } /// Frees a vpkc_update_source_t instance. +/// @param p_source The source to free. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -90,9 +102,11 @@ pub extern "C" fn vpkc_free_source(p_source: *mut vpkc_update_source_t) { } /// Create a new UpdateManager instance. -/// @param urlOrPath Location of the update server or path to the local update directory. -/// @param options Optional extra configuration for update manager. -/// @param locator Override the default locator configuration (usually used for testing / mocks). +/// @param psz_url_or_path Location of the http update server url or path to the local update directory. +/// @param p_options Optional extra configuration for update manager. +/// @param p_locator Optional explicit path configuration for Velopack. If null, the default locator will be used. +/// @param p_manager A pointer to where the new vpkc_update_manager_t* instance will be stored. +/// @returns True if the update manager was created successfully, false otherwise. If false, the error will be available via `vpkc_get_last_error`. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -114,9 +128,11 @@ pub extern "C" fn vpkc_new_update_manager( } /// Create a new UpdateManager instance with a custom UpdateSource. -/// @param urlOrPath Location of the update server or path to the local update directory. -/// @param options Optional extra configuration for update manager. -/// @param locator Override the default locator configuration (usually used for testing / mocks). +/// @param p_source A pointer to a custom UpdateSource. +/// @param p_options Optional extra configuration for update manager. +/// @param p_locator Optional explicit path configuration for Velopack. If null, the default locator will be used. +/// @param p_manager A pointer to where the new vpkc_update_manager_t* instance will be stored. +/// @returns True if the update manager was created successfully, false otherwise. If false, the error will be available via `vpkc_get_last_error`. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -137,6 +153,10 @@ pub extern "C" fn vpkc_new_update_manager_with_source( } /// Returns the currently installed version of the app. +/// @param p_manager The update manager instance. +/// @param psz_version A buffer to store the version string. +/// @param c_version The size of the `psz_version` buffer. +/// @returns The number of characters written to `psz_version` (including null terminator), or the required buffer size if the buffer is too small. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -151,6 +171,10 @@ pub extern "C" fn vpkc_get_current_version(p_manager: *mut vpkc_update_manager_t } /// Returns the currently installed app id. +/// @param p_manager The update manager instance. +/// @param psz_id A buffer to store the app id string. +/// @param c_id The size of the `psz_id` buffer. +/// @returns The number of characters written to `psz_id` (including null terminator), or the required buffer size if the buffer is too small. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -166,6 +190,8 @@ pub extern "C" fn vpkc_get_app_id(p_manager: *mut vpkc_update_manager_t, psz_id: /// Returns whether the app is in portable mode. On Windows this can be true or false. /// On MacOS and Linux this will always be true. +/// @param p_manager The update manager instance. +/// @returns True if the app is in portable mode, false otherwise. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -176,8 +202,11 @@ pub extern "C" fn vpkc_is_portable(p_manager: *mut vpkc_update_manager_t) -> boo } } -/// Returns an UpdateInfo object if there is an update downloaded which still needs to be applied. -/// You can pass the UpdateInfo object to waitExitThenApplyUpdate to apply the update. +/// Returns an asset if there is an update downloaded which still needs to be applied. +/// You can pass this asset to `vpkc_wait_exit_then_apply_updates` to apply the update. +/// @param p_manager The update manager instance. +/// @param p_asset A pointer to where the new vpkc_asset_t* instance will be stored. +/// @returns True if there is an update pending restart, false otherwise. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -194,8 +223,11 @@ pub extern "C" fn vpkc_update_pending_restart(p_manager: *mut vpkc_update_manage } } -/// Checks for updates, returning None if there are none available. If there are updates available, this method will return an +/// Checks for updates. If there are updates available, this method will return an /// UpdateInfo object containing the latest available release, and any delta updates that can be applied if they are available. +/// @param p_manager The update manager instance. +/// @param p_update A pointer to where the new vpkc_update_info_t* instance will be stored if an update is available. +/// @returns A `vpkc_update_check_t` value indicating the result of the check. If an update is available, the value will be `HasUpdate` and `p_update` will be populated. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -229,6 +261,12 @@ pub extern "C" fn vpkc_check_for_updates( /// this method will attempt to unpack and prepare them. /// - If there is no delta update available, or there is an error preparing delta /// packages, this method will fall back to downloading the full version of the update. +/// @param p_manager The update manager instance. +/// @param p_update The update info object from `vpkc_check_for_updates`. +/// @param cb_progress An optional callback to report download progress (0-100). +/// @param p_user_data Optional user data to be passed to the progress callback. +/// @returns true on success, false on failure. If false, the error will be available via `vpkc_get_last_error`. + #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -294,7 +332,14 @@ pub extern "C" fn vpkc_download_updates( /// This will launch the Velopack updater and tell it to wait for this program to exit gracefully. /// You should then clean up any state and exit your app. The updater will apply updates and then -/// optionally restart your app. The updater will only wait for 60 seconds before giving up. +/// (if specified) restart your app. The updater will only wait for 60 seconds before giving up. +/// @param p_manager The update manager instance. +/// @param p_asset The asset to apply. This can be from `vpkc_update_pending_restart` or `vpkc_update_info_get_target_asset`. +/// @param b_silent True to attempt to apply the update without showing any UI. +/// @param b_restart True to restart the app after the update is applied. +/// @param p_restart_args An array of command line arguments to pass to the new process when it's restarted. +/// @param c_restart_args The number of arguments in `p_restart_args`. +/// @returns true on success, false on failure. If false, the error will be available via `vpkc_get_last_error`. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -323,6 +368,14 @@ pub extern "C" fn vpkc_wait_exit_then_apply_updates( /// This method is unsafe because it does not necessarily wait for any / the correct process to exit /// before applying updates. The `vpkc_wait_exit_then_apply_updates` method is recommended for most use cases. /// If dw_wait_pid is 0, the updater will not wait for any process to exit before applying updates (Not Recommended). +/// @param p_manager The update manager instance. +/// @param p_asset The asset to apply. This can be from `vpkc_update_pending_restart` or `vpkc_update_info_get_target_asset`. +/// @param b_silent True to attempt to apply the update without showing any UI. +/// @param dw_wait_pid The process ID to wait for before applying updates. If 0, the updater will not wait. +/// @param b_restart True to restart the app after the update is applied. +/// @param p_restart_args An array of command line arguments to pass to the new process when it's restarted. +/// @param c_restart_args The number of arguments in `p_restart_args`. +/// @returns true on success, false on failure. If false, the error will be available via `vpkc_get_last_error`. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -346,6 +399,7 @@ pub extern "C" fn vpkc_unsafe_apply_updates( } /// Frees a vpkc_update_manager_t instance. +/// @param p_manager The update manager instance to free. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -354,6 +408,7 @@ pub extern "C" fn vpkc_free_update_manager(p_manager: *mut vpkc_update_manager_t } /// Frees a vpkc_update_info_t instance. +/// @param p_update_info The update info instance to free. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -362,6 +417,7 @@ pub extern "C" fn vpkc_free_update_info(p_update_info: *mut vpkc_update_info_t) } /// Frees a vpkc_asset_t instance. +/// @param p_asset The asset instance to free. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -371,7 +427,9 @@ pub extern "C" fn vpkc_free_asset(p_asset: *mut vpkc_asset_t) { /// VelopackApp helps you to handle app activation events correctly. /// This should be used as early as possible in your application startup code. -/// (eg. the beginning of main() or wherever your entry point is) +/// (eg. the beginning of main() or wherever your entry point is). +/// This function will not return in some cases. +/// @param p_user_data Optional user data to be passed to the callbacks. #[no_mangle] #[logfn(Trace)] #[logfn_inputs(Trace)] @@ -449,6 +507,7 @@ pub extern "C" fn vpkc_app_run(p_user_data: *mut c_void) { } /// Set whether to automatically apply downloaded updates on startup. This is ON by default. +/// @param b_auto_apply True to automatically apply updates, false otherwise. #[no_mangle] pub extern "C" fn vpkc_app_set_auto_apply_on_startup(b_auto_apply: bool) { update_app_options(|opt| { @@ -457,6 +516,8 @@ pub extern "C" fn vpkc_app_set_auto_apply_on_startup(b_auto_apply: bool) { } /// Override the command line arguments used by VelopackApp. (by default this is env::args().skip(1)) +/// @param p_args An array of command line arguments. +/// @param c_args The number of arguments in `p_args`. #[no_mangle] pub extern "C" fn vpkc_app_set_args(p_args: *mut *mut c_char, c_args: size_t) { update_app_options(|opt| { @@ -465,6 +526,7 @@ pub extern "C" fn vpkc_app_set_args(p_args: *mut *mut c_char, c_args: size_t) { } /// VelopackLocator provides some utility functions for locating the current app important paths (eg. path to packages, update binary, and so forth). +/// @param p_locator The locator configuration to use. #[no_mangle] pub extern "C" fn vpkc_app_set_locator(p_locator: *mut vpkc_locator_config_t) { update_app_options(|opt| { @@ -472,10 +534,12 @@ pub extern "C" fn vpkc_app_set_locator(p_locator: *mut vpkc_locator_config_t) { }); } +/// Sets a callback to be run after the app is installed. /// WARNING: FastCallback hooks are run during critical stages of Velopack operations. /// Your code will be run and then the process will exit. /// If your code has not completed within 30 seconds, it will be terminated. /// Only supported on windows; On other operating systems, this will never be called. +/// @param cb_after_install The callback to run after the app is installed. The callback takes a user data pointer and the version of the app as a string. #[no_mangle] pub extern "C" fn vpkc_app_set_hook_after_install(cb_after_install: vpkc_hook_callback_t) { update_app_options(|opt| { @@ -483,10 +547,12 @@ pub extern "C" fn vpkc_app_set_hook_after_install(cb_after_install: vpkc_hook_ca }); } +/// Sets a callback to be run before the app is uninstalled. /// WARNING: FastCallback hooks are run during critical stages of Velopack operations. /// Your code will be run and then the process will exit. /// If your code has not completed within 30 seconds, it will be terminated. /// Only supported on windows; On other operating systems, this will never be called. +/// @param cb_before_uninstall The callback to run before the app is uninstalled. The callback takes a user data pointer and the version of the app as a string. #[no_mangle] pub extern "C" fn vpkc_app_set_hook_before_uninstall(cb_before_uninstall: vpkc_hook_callback_t) { update_app_options(|opt| { @@ -494,10 +560,12 @@ pub extern "C" fn vpkc_app_set_hook_before_uninstall(cb_before_uninstall: vpkc_h }); } +/// Sets a callback to be run before the app is updated. /// WARNING: FastCallback hooks are run during critical stages of Velopack operations. /// Your code will be run and then the process will exit. /// If your code has not completed within 30 seconds, it will be terminated. /// Only supported on windows; On other operating systems, this will never be called. +/// @param cb_before_update The callback to run before the app is updated. The callback takes a user data pointer and the version of the app as a string. #[no_mangle] pub extern "C" fn vpkc_app_set_hook_before_update(cb_before_update: vpkc_hook_callback_t) { update_app_options(|opt| { @@ -505,10 +573,12 @@ pub extern "C" fn vpkc_app_set_hook_before_update(cb_before_update: vpkc_hook_ca }); } +/// Sets a callback to be run after the app is updated. /// WARNING: FastCallback hooks are run during critical stages of Velopack operations. /// Your code will be run and then the process will exit. /// If your code has not completed within 30 seconds, it will be terminated. /// Only supported on windows; On other operating systems, this will never be called. +/// @param cb_after_update The callback to run after the app is updated. The callback takes a user data pointer and the version of the app as a string. #[no_mangle] pub extern "C" fn vpkc_app_set_hook_after_update(cb_after_update: vpkc_hook_callback_t) { update_app_options(|opt| { @@ -517,6 +587,7 @@ pub extern "C" fn vpkc_app_set_hook_after_update(cb_after_update: vpkc_hook_call } /// This hook is triggered when the application is started for the first time after installation. +/// @param cb_first_run The callback to run on first run. The callback takes a user data pointer and the version of the app as a string. #[no_mangle] pub extern "C" fn vpkc_app_set_hook_first_run(cb_first_run: vpkc_hook_callback_t) { update_app_options(|opt| { @@ -525,6 +596,7 @@ pub extern "C" fn vpkc_app_set_hook_first_run(cb_first_run: vpkc_hook_callback_t } /// This hook is triggered when the application is restarted by Velopack after installing updates. +/// @param cb_restarted The callback to run after the app is restarted. The callback takes a user data pointer and the version of the app as a string. #[no_mangle] pub extern "C" fn vpkc_app_set_hook_restarted(cb_restarted: vpkc_hook_callback_t) { update_app_options(|opt| { @@ -533,6 +605,9 @@ pub extern "C" fn vpkc_app_set_hook_restarted(cb_restarted: vpkc_hook_callback_t } /// Get the last error message that occurred in the Velopack library. +/// @param psz_error A buffer to store the error message. +/// @param c_error The size of the `psz_error` buffer. +/// @returns The number of characters written to `psz_error` (including null terminator). If the return value is greater than `c_error`, the buffer was too small and the message was truncated. #[no_mangle] pub extern "C" fn vpkc_get_last_error(psz_error: *mut c_char, c_error: size_t) -> size_t { let error = get_last_error(); @@ -540,6 +615,8 @@ pub extern "C" fn vpkc_get_last_error(psz_error: *mut c_char, c_error: size_t) - } /// Set a custom log callback. This will be called for all log messages generated by the Velopack library. +/// @param cb_log The callback to call with log messages. The callback takes a user data pointer, a log level, and the log message as a string. +/// @param p_user_data Optional user data to be passed to the callback. #[no_mangle] pub extern "C" fn vpkc_set_logger(cb_log: vpkc_log_callback_t, p_user_data: *mut c_void) { set_log_callback(cb_log, p_user_data); diff --git a/src/lib-cpp/src/types.rs b/src/lib-cpp/src/types.rs index 48d45c9e..d7a36bf4 100644 --- a/src/lib-cpp/src/types.rs +++ b/src/lib-cpp/src/types.rs @@ -446,7 +446,7 @@ pub struct vpkc_update_options_t { /// ExplicitChannel to switch channels to another channel where the latest version on that /// channel is lower than the current version. pub AllowVersionDowngrade: bool, - /// **This option should usually be left None**. + /// **This option should usually be left None/NULL**. /// Overrides the default channel used to fetch updates. /// The default channel will be whatever channel was specified on the command line when building this release. /// For example, if the current release was packaged with '--channel beta', then the default channel will be 'beta'.