SarasasChipWorkshop/wfassoc
1
0
Fork 0
Code Activity

refactor: move generated header location

Browse Source
This commit is contained in:
yyc12345
2026-08-15 09:02:53 +08:00
parent 4fcdf902f7
commit 64ccc083fb
3 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wfassoc-cdylib/cbinding/Findwfassoc.cmake
+101
View File
@@ -0,0 +1,101 @@
# Findwfassoc.cmake
# ----------------
# Find wfassoc library and headers.
#
# This module requires the user to set wfassoc_ROOT to the installation
# directory of wfassoc. The directory structure under wfassoc_ROOT must be:
# bin/ - contains wfassoc_cdylib.dll
# include/ - contains wfassoc.h and wfassoc++.h
# lib/ - contains wfassoc_cdylib.dll.lib (import library)
#
# This module defines the following variables:
# wfassoc_FOUND - True if wfassoc was found
# wfassoc_INCLUDE_DIRS - Path to wfassoc include directory
# wfassoc_LIBRARIES - Path to wfassoc import library
# wfassoc_DLL - Path to wfassoc DLL
# wfassoc_ROOT - The root directory (user-provided)
#
# This module also creates the following imported targets:
# wfassoc::wfassoc - Main wfassoc library (includes both include and link)
#
set(wfassoc_FOUND FALSE)
# Require user to set wfassoc_ROOT
if(NOT wfassoc_ROOT)
message(FATAL_ERROR "wfassoc_ROOT must be set to the installation directory of wfassoc")
endif()
# Check existence of required subdirectories
if(NOT EXISTS ${wfassoc_ROOT})
message(FATAL_ERROR "wfassoc_ROOT directory does not exist: ${wfassoc_ROOT}")
endif()
set(wfassoc_INCLUDE_DIR ${wfassoc_ROOT}/include)
set(wfassoc_LIB_DIR ${wfassoc_ROOT}/lib)
set(wfassoc_BIN_DIR ${wfassoc_ROOT}/bin)
# Find header files
if(EXISTS ${wfassoc_INCLUDE_DIR}/wfassoc.h AND EXISTS ${wfassoc_INCLUDE_DIR}/wfassoc++.h)
set(wfassoc_INCLUDE_DIRS ${wfassoc_INCLUDE_DIR})
else()
message(SEND_ERROR "Missing wfassoc header files in ${wfassoc_INCLUDE_DIR}")
return()
endif()
# Find import library (.lib)
find_file(wfassoc_LIBRARIES
NAMES wfassoc_cdylib.dll.lib
PATHS ${wfassoc_LIB_DIR}
NO_DEFAULT_PATH
DOC "wfassoc import library"
)
if(NOT wfassoc_LIBRARIES)
message(SEND_ERROR "Missing wfassoc import library (wfassoc_cdylib.dll.lib) in ${wfassoc_LIB_DIR}")
return()
endif()
# Find DLL file
find_file(wfassoc_DLL
NAMES wfassoc_cdylib.dll
PATHS ${wfassoc_BIN_DIR}
NO_DEFAULT_PATH
DOC "wfassoc dynamic library"
)
if(NOT wfassoc_DLL)
message(SEND_ERROR "Missing wfassoc DLL (wfassoc_cdylib.dll) in ${wfassoc_BIN_DIR}")
return()
endif()
# Everything found
set(wfassoc_FOUND TRUE)
# Mark variables as advanced for ccmake/cmake-gui
mark_as_advanced(wfassoc_INCLUDE_DIRS wfassoc_LIBRARIES wfassoc_DLL)
# Create imported target for wfassoc
if(wfassoc_FOUND AND NOT TARGET wfassoc::wfassoc)
add_library(wfassoc::wfassoc SHARED IMPORTED)
# Set include directories
set_target_properties(wfassoc::wfassoc PROPERTIES
INTERFACE_INCLUDE_DIRECTORIES ${wfassoc_INCLUDE_DIRS}
)
# Set import library location
set_target_properties(wfassoc::wfassoc PROPERTIES
IMPORTED_IMPLIB "${wfassoc_LIBRARIES}"
IMPORTED_LOCATION "${wfassoc_DLL}"
)
endif()
# Optional: Print status message
if(wfassoc_FOUND)
message(STATUS "Found wfassoc:")
message(STATUS " Root : ${wfassoc_ROOT}")
message(STATUS " Include : ${wfassoc_INCLUDE_DIRS}")
message(STATUS " Library : ${wfassoc_LIBRARIES}")
message(STATUS " DLL : ${wfassoc_DLL}")
endif()
wfassoc-cdylib/cbinding/wfassoc++.h
+693
View File
@@ -0,0 +1,693 @@
/**
* @file wfassoc++.h
* @brief Windows File Association C++ API header
*
* This header provides C++ API for managing Windows file associations,
* based on its C-compatible API.
* The API is designed to work with at least C++17.
*/
#pragma once
#ifndef WFASSOCPP_H_
#define WFASSOCPP_H_
#include "wfassoc.h"
#include <optional>
#include <stdexcept>
#include <string>
#include <utility>
/**
* @brief Windows File Association C++ API namespace
*
* Provides C++ RAII wrappers around the C-compatible wfassoc API.
*/
namespace wfassocpp {
/** @brief Type representing a null-terminated UTF-8 C-style string */
using CString = wfassoc::WFCString;
/**
* @brief Type representing a handle/token for managed objects
*
* This library uses an object pool to manage any objects created during calling.
* This type is exposed as an opaque handle for visiting your created object.
*/
using Token = wfassoc::WFToken;
/**
* @brief Type representing an icon handle (opaque pointer)
*
* This type is equivalent to the Win32 HICON type.
*/
using HICON = wfassoc::WFHICON;
/** @brief Invalid icon handle value */
using INVALID_HICON = wfassoc::WF_INVALID_HICON;
/** @brief Invalid index value used for error conditions */
using INVALID_INDEX = wfassoc::WF_INVALID_INDEX;
/**
* @brief Registration scope for file associations
*
* Determines whether a program is registered for the current user or system-wide.
*/
using Scope = wfassoc::WFScope;
/**
* @brief View mode for querying file association status
*
* Determines how the association status is viewed/queried.
*/
using View = wfassoc::WFView;
/**
* @private
* @brief Check the result of a C API call and throw on failure
*
* @param[in] result Boolean result from a C API call
* @throws std::runtime_error if result is false, with the error message from WFGetLastError()
*/
inline void _Check(bool result) {
if (!result) {
throw std::runtime_error(wfassoc::WFGetLastError());
}
}
/**
* @private
* @brief Get the invalid token value
*
* In theory, invalid token value should be a constant value.
* However, due to the library used in Rust side, this value can only be fetched at runtime.
* This function caches the value on first call for subsequent use.
*
* @return An invalid token value
*/
inline Token _INVALID_TOKEN() {
static Token v = wfassoc::WFInvalidToken();
return v;
}
/**
* @brief Schema object for defining a program's file association configuration
*
* A Schema is a sketchpad of a complete program.
* Create a Schema object first, then convert it to a Program object for following operations.
*
* This class is move-only (non-copyable).
*/
class Schema {
public:
/**
* @brief Construct a new Schema object
* @throws std::runtime_error if schema creation fails
*/
Schema() { _Check(wfassoc::WFSchemaCreate(&_token)); }
/**
* @brief Destroy the Schema object
*
* Releases resources associated with the Schema object.
*/
~Schema() {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFSchemaDestroy(_token);
}
}
/** @brief Non-copyable */
Schema(const Schema&) = delete;
/** @brief Non-copyable */
Schema& operator=(const Schema&) = delete;
/** @brief Move constructor */
Schema(Schema&& other) noexcept : _token(other._token) { other._token = _INVALID_TOKEN(); }
/** @brief Move assignment operator */
Schema& operator=(Schema&& other) noexcept {
if (this != &other) {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFSchemaDestroy(_token);
}
_token = other._token;
other._token = _INVALID_TOKEN();
}
return *this;
}
/**
* @brief Set the program identifier for this Schema
*
* @param[in] value Null-terminated UTF-8 string containing the identifier.
* This identifier should not be empty, must start with alphabet character,
* and follow with alphabet characters, digits, underline, or hyphens.
* @throws std::runtime_error if the operation fails
*/
void SetIdentifier(const char* value) { _Check(wfassoc::WFSchemaSetIdentifier(_token, value)); }
/**
* @brief Set the program path for this Schema
*
* @param[in] value Null-terminated UTF-8 string containing the program path.
* This path should be the fully qualified path to the application.
* @throws std::runtime_error if the operation fails
*/
void SetPath(const char* value) { _Check(wfassoc::WFSchemaSetPath(_token, value)); }
/**
* @brief Set the program CLSID for this Schema
*
* @param[in] value Null-terminated UTF-8 string containing the CLSID.
* This CLSID string should be in the format of @c {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}.
* Please note that curly braces are required.
* @throws std::runtime_error if the operation fails
*/
void SetClsid(const char* value) { _Check(wfassoc::WFSchemaSetClsid(_token, value)); }
/**
* @brief Set the program name for this Schema (optional)
*
* @param[in] value Null-terminated UTF-8 string containing the name, or nullptr to clear
* @throws std::runtime_error if the operation fails
*/
void SetName(const char* value) { _Check(wfassoc::WFSchemaSetName(_token, value)); }
/**
* @brief Set the program icon for this Schema (optional)
*
* @param[in] value Null-terminated UTF-8 string containing the icon path, or nullptr to clear
* @throws std::runtime_error if the operation fails
*/
void SetIcon(const char* value) { _Check(wfassoc::WFSchemaSetIcon(_token, value)); }
/**
* @brief Set the program behavior for this Schema (optional)
*
* @param[in] value Null-terminated UTF-8 string containing the behavior command, or nullptr to clear
* @throws std::runtime_error if the operation fails
*/
void SetBehavior(const char* value) { _Check(wfassoc::WFSchemaSetBehavior(_token, value)); }
/**
* @brief Add a string resource entry to this Schema
*
* @param[in] name Null-terminated UTF-8 string containing the name of this entry
* @param[in] value Null-terminated UTF-8 string containing the value of this entry.
* It can be a plain string or a reference string to resource.
* @throws std::runtime_error if the operation fails
*/
void AddStr(const char* name, const char* value) { _Check(wfassoc::WFSchemaAddStr(_token, name, value)); }
/**
* @brief Add an icon registry entry to this Schema
*
* @param[in] name Null-terminated UTF-8 string containing the name of this entry
* @param[in] value Null-terminated UTF-8 string containing the value of this entry.
* It can be a path to icon or a reference string to resource.
* @throws std::runtime_error if the operation fails
*/
void AddIcon(const char* name, const char* value) { _Check(wfassoc::WFSchemaAddIcon(_token, name, value)); }
/**
* @brief Add a behavior registry entry to this Schema
*
* @param[in] name Null-terminated UTF-8 string containing the name of this entry
* @param[in] value Null-terminated UTF-8 string containing the value of this entry.
* It should be a valid command line string which uses @c %1, @c %2, etc. to represent parameters.
* @throws std::runtime_error if the operation fails
*/
void AddBehavior(const char* name, const char* value) { _Check(wfassoc::WFSchemaAddBehavior(_token, name, value)); }
/**
* @brief Add a file extension to this Schema
*
* @param[in] ext Null-terminated UTF-8 string containing the file extension name (without leading dot)
* @param[in] ext_name Null-terminated UTF-8 string containing the name pointing to associated name for this extension.
* This name should be registered by calling AddStr().
* @param[in] ext_icon Null-terminated UTF-8 string containing the name pointing to associated icon for this extension.
* This name should be registered by calling AddIcon().
* @param[in] ext_behavior Null-terminated UTF-8 string containing the name pointing to associated behavior for this extension.
* This name should be registered by calling AddBehavior().
* @throws std::runtime_error if the operation fails
*/
void AddExt(const char* ext, const char* ext_name, const char* ext_icon, const char* ext_behavior) {
_Check(wfassoc::WFSchemaAddExt(_token, ext, ext_name, ext_icon, ext_behavior));
}
private:
friend class Program;
/**
* @private
* @brief Release ownership of the token
*
* @return The released token
*/
Token Release() noexcept {
Token t = _token;
_token = _INVALID_TOKEN();
return t;
}
Token _token;
};
/**
* @brief Icon resource object for managing icon handles
*
* This class wraps an icon resource token and provides access to the icon handle.
* The icon handle will be freed when this object is destroyed.
*
* This class is move-only (non-copyable).
*/
class IconRc {
public:
/**
* @brief Construct an IconRc from an existing token
*
* @param[in] token The icon resource token to wrap
*/
explicit IconRc(Token token) : _token(token) {}
/**
* @brief Destroy the IconRc object
*
* Releases resources associated with the icon resource.
*/
~IconRc() {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFIconRcDestroy(_token);
}
}
/** @brief Non-copyable */
IconRc(const IconRc&) = delete;
/** @brief Non-copyable */
IconRc& operator=(const IconRc&) = delete;
/** @brief Move constructor */
IconRc(IconRc&& other) noexcept : _token(other._token) { other._token = _INVALID_TOKEN(); }
/** @brief Move assignment operator */
IconRc& operator=(IconRc&& other) noexcept {
if (this != &other) {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFIconRcDestroy(_token);
}
_token = other._token;
other._token = _INVALID_TOKEN();
}
return *this;
}
/**
* @brief Get the icon handle from this icon resource
*
* @return The icon handle. This handle will be freed when this object is destroyed.
* Please make a copy immediately if you need to use it longer.
* @throws std::runtime_error if the operation fails
*/
HICON GetIcon() {
HICON icon = nullptr;
_Check(wfassoc::WFIconRcGetIcon(_token, &icon));
return icon;
}
private:
Token _token;
};
/**
* @brief Extension status object for querying file extension registration status
*
* This class wraps an extension status token and provides access to extension details.
* The extension status object will be freed when this object is destroyed.
*
* This class is move-only (non-copyable).
*/
class ExtStatus {
public:
/**
* @brief Construct an ExtStatus from an existing token
*
* @param[in] token The extension status token to wrap
*/
explicit ExtStatus(Token token) : _token(token) {}
/**
* @brief Destroy the ExtStatus object
*
* Releases resources associated with the extension status.
*/
~ExtStatus() {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFExtStatusDestroy(_token);
}
}
/** @brief Non-copyable */
ExtStatus(const ExtStatus&) = delete;
/** @brief Non-copyable */
ExtStatus& operator=(const ExtStatus&) = delete;
/** @brief Move constructor */
ExtStatus(ExtStatus&& other) noexcept : _token(other._token) { other._token = _INVALID_TOKEN(); }
/** @brief Move assignment operator */
ExtStatus& operator=(ExtStatus&& other) noexcept {
if (this != &other) {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFExtStatusDestroy(_token);
}
_token = other._token;
other._token = _INVALID_TOKEN();
}
return *this;
}
/**
* @brief Get the display name from this extension status
*
* The display name will be user specified first, then fallback to its ProgId verbatim.
* The library will try to use localized name first, then use raw ProgId name if localized name is not available.
*
* @return The display name string. There is no possibility that this value is empty.
* @throws std::runtime_error if the operation fails
*/
std::string GetName() {
const char* name = nullptr;
_Check(wfassoc::WFExtStatusGetName(_token, &name));
return std::string(name);
}
/**
* @brief Get the icon from this extension status
*
* The icon will be user specified first, then fallback to the system default file icon.
*
* @return The icon handle. This handle will be freed when this object is destroyed.
* Please make a copy immediately if you need to use it longer.
* @throws std::runtime_error if the operation fails
*/
HICON GetIcon() {
HICON icon = nullptr;
_Check(wfassoc::WFExtStatusGetIcon(_token, &icon));
return icon;
}
private:
Token _token;
};
/**
* @brief Self extension status object for accessing program-provided extension details
*
* This class wraps a self extension status token and provides access to extension details
* as defined by the program itself.
*
* This class is move-only (non-copyable).
*/
class SelfExtStatus {
public:
/**
* @brief Construct a SelfExtStatus from an existing token
*
* @param[in] token The self extension status token to wrap
*/
explicit SelfExtStatus(Token token) : _token(token) {}
/**
* @brief Destroy the SelfExtStatus object
*
* Releases resources associated with the self extension status.
*/
~SelfExtStatus() {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFSelfExtStatusDestroy(_token);
}
}
/** @brief Non-copyable */
SelfExtStatus(const SelfExtStatus&) = delete;
/** @brief Non-copyable */
SelfExtStatus& operator=(const SelfExtStatus&) = delete;
/** @brief Move constructor */
SelfExtStatus(SelfExtStatus&& other) noexcept : _token(other._token) { other._token = _INVALID_TOKEN(); }
/** @brief Move assignment operator */
SelfExtStatus& operator=(SelfExtStatus&& other) noexcept {
if (this != &other) {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFSelfExtStatusDestroy(_token);
}
_token = other._token;
other._token = _INVALID_TOKEN();
}
return *this;
}
/**
* @brief Get the display name from this self extension status
*
* The display name will be user specified first, then fallback to its ProgId verbatim.
*
* @return The display name string. There is no possibility that this value is empty.
* @throws std::runtime_error if the operation fails
*/
std::string GetName() {
const char* name = nullptr;
_Check(wfassoc::WFSelfExtStatusGetName(_token, &name));
return std::string(name);
}
/**
* @brief Get the icon from this self extension status
*
* The icon will be user specified first, then fallback to the system default file icon.
*
* @return The icon handle. This handle will be freed when this object is destroyed.
* Please make a copy immediately if you need to use it longer.
* @throws std::runtime_error if the operation fails
*/
HICON GetIcon() {
HICON icon = nullptr;
_Check(wfassoc::WFSelfExtStatusGetIcon(_token, &icon));
return icon;
}
/**
* @brief Get the extension string (without leading dot) from this self extension status
*
* @return The file extension name (without leading dot). There is no possibility that this value is empty.
* @throws std::runtime_error if the operation fails
*/
std::string GetExt() {
const char* inner = nullptr;
_Check(wfassoc::WFSelfExtStatusGetExt(_token, &inner));
return std::string(inner);
}
/**
* @brief Get the dotted extension string (with leading dot) from this self extension status
*
* @return The file extension string (with leading dot). There is no possibility that this value is empty.
* @throws std::runtime_error if the operation fails
*/
std::string GetDottedExt() {
const char* inner = nullptr;
_Check(wfassoc::WFSelfExtStatusGetDottedExt(_token, &inner));
return std::string(inner);
}
private:
Token _token;
};
/**
* @brief Program object for managing file association registration
*
* A Program is created from a Schema and provides methods for registering,
* unregistering, and querying file associations.
*
* This class is move-only (non-copyable).
*/
class Program {
public:
/**
* @brief Construct a Program from a Schema
*
* This constructor consumes the Schema object.
* The Schema object cannot be used after this call.
*
* @param[in] schema The Schema to create the Program from (will be consumed)
* @throws std::runtime_error if program creation fails
*/
explicit Program(Schema&& schema) {
_Check(wfassoc::WFProgramCreate(schema.Release(), &_token));
}
/**
* @brief Destroy the Program object
*
* Releases resources associated with the Program.
*/
~Program() {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFProgramDestroy(_token);
}
}
/** @brief Non-copyable */
Program(const Program&) = delete;
/** @brief Non-copyable */
Program& operator=(const Program&) = delete;
/** @brief Move constructor */
Program(Program&& other) noexcept : _token(other._token) { other._token = _INVALID_TOKEN(); }
/** @brief Move assignment operator */
Program& operator=(Program&& other) noexcept {
if (this != &other) {
if (_token != _INVALID_TOKEN()) {
wfassoc::WFProgramDestroy(_token);
}
_token = other._token;
other._token = _INVALID_TOKEN();
}
return *this;
}
/**
* @brief Resolve the provided program name of this Program
*
* The name will be user specified first,
* then fallback to program manifest file specified name,
* and finally fallback to the file name of executable.
*
* @return The resolved program name. There is no possibility that this value is empty.
* @throws std::runtime_error if the operation fails
*/
std::string ResolveName() {
const char* name = nullptr;
_Check(wfassoc::WFProgramResolveName(_token, &name));
return std::string(name);
}
/**
* @brief Resolve the Program icon resource
*
* The icon will be user specified first,
* then fallback to the first icon of program,
* and finally fallback to the system default executable icon.
*
* @return An IconRc object containing the resolved icon
* @throws std::runtime_error if the operation fails
*/
IconRc ResolveIcon() {
Token token = _INVALID_TOKEN();
_Check(wfassoc::WFProgramResolveIcon(_token, &token));
return IconRc(token);
}
/**
* @brief Get the number of file extensions in the Program
*
* @return The number of extensions
* @throws std::runtime_error if the operation fails
*/
size_t ExtsLen() {
size_t len = 0;
_Check(wfassoc::WFProgramExtsLen(_token, &len));
return len;
}
/**
* @brief Find a file extension by its body (extension string)
*
* @param[in] body Null-terminated UTF-8 string containing the file extension name (without leading dot) to find
* @return The index of the extension, or INVALID_INDEX if not found
* @throws std::runtime_error if the operation fails
*/
size_t FindExt(const char* body) {
size_t index = INVALID_INDEX;
_Check(wfassoc::WFProgramFindExt(_token, body, &index));
return index;
}
/**
* @brief Resolve this program provided extension's details by index
*
* @param[in] index Index of the extension to resolve
* @return A SelfExtStatus object containing the extension details
* @throws std::runtime_error if the operation fails
*/
SelfExtStatus ResolveExt(size_t index) {
Token token = _INVALID_TOKEN();
_Check(wfassoc::WFProgramResolveExt(_token, index, &token));
return SelfExtStatus(token);
}
/**
* @brief Register the Program in the specified scope
*
* @param[in] scope Registration scope
* @throws std::runtime_error if the operation fails
*/
void Register(Scope scope) { _Check(wfassoc::WFProgramRegister(_token, scope)); }
/**
* @brief Unregister the Program from the specified scope
*
* @param[in] scope Registration scope
* @throws std::runtime_error if the operation fails
*/
void Unregister(Scope scope) { _Check(wfassoc::WFProgramUnregister(_token, scope)); }
/**
* @brief Check if the Program is registered in the specified scope
*
* @param[in] scope Registration scope for checking
* @return true if the Program is registered in the specified scope, false otherwise
* @throws std::runtime_error if the operation fails
*/
bool IsRegistered(Scope scope) {
bool result = false;
_Check(wfassoc::WFProgramIsRegistered(_token, scope, &result));
return result;
}
/**
* @brief Link a file extension in the specified scope
*
* @param[in] scope Registration scope
* @param[in] index Index of the extension to link
* @throws std::runtime_error if the operation fails
*/
void LinkExt(Scope scope, size_t index) { _Check(wfassoc::WFProgramLinkExt(_token, scope, index)); }
/**
* @brief Unlink a file extension in the specified scope
*
* @param[in] scope Registration scope
* @param[in] index Index of the extension to unlink
* @throws std::runtime_error if the operation fails
*/
void UnlinkExt(Scope scope, size_t index) { _Check(wfassoc::WFProgramUnlinkExt(_token, scope, index)); }
/**
* @brief Query the status of a file extension
*
* @param[in] view View viewpoint
* @param[in] index Index of the extension to query
* @return An optional ExtStatus object. Returns std::nullopt if the extension is not found
* (usually means that this extension is not registered in the specified scope).
* @throws std::runtime_error if the operation fails
*/
std::optional<ExtStatus> QueryExt(View view, size_t index) {
Token token = _INVALID_TOKEN();
_Check(wfassoc::WFProgramQueryExt(_token, view, index, &token));
if (token == _INVALID_TOKEN()) {
return std::nullopt;
}
return ExtStatus(token);
}
private:
Token _token;
};
} // namespace wfassocpp
#endif // WFASSOCPP_H_
wfassoc-cdylib/cbinding/wfassoc.h
+595
View File
@@ -0,0 +1,595 @@
/**
* @file wfassoc.h
* @brief Windows File Association C API header
*
* This header provides a C-compatible API for managing Windows file associations,
* including schema creation, program registration, and extension management.
* The API is designed to at least work with both C99 and C++17 compilers.
*/
#pragma once
#ifndef WFASSOC_H_
#define WFASSOC_H_
#ifdef __cplusplus
#include <cstddef>
#include <cstdint>
#else // __cplusplus
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#endif // __cplusplus
#ifdef __cplusplus
/**
* @brief Windows File Association C/C++ API namespace
*
* This namespace only provide the raw binding to C-compatible wfassoc API in C++.
* For the C++ RAII wrappers of this, please see @ref wfassocpp namespace.
*/
namespace wfassoc {
#endif // __cplusplus
#ifdef __cplusplus
/** Type representing a null-terminated UTF-8 C-style string */
using WFCString = const char*;
/**
* @brief Type representing a handle/token for managed objects
*
* This library use object pool to manage any objects created during calling.
* And we expose this type as an opaque handle for visiting your created object.
*/
using WFToken = uint64_t;
/**
* @brief Type representing an icon handle (opaque pointer)
*
* This type is equivalent with Win32 HICON type.
*/
using WFHICON = void*;
#else // __cplusplus
typedef const char *WFCString;
typedef uint64_t WFToken;
typedef void *WFHICON;
#endif // __cplusplus
#ifdef __cplusplus
/** Invalid icon handle value */
constexpr WFHICON WF_INVALID_HICON = nullptr;
/** Invalid index value used for error conditions */
constexpr size_t WF_INVALID_INDEX = static_cast<size_t>(-1);
#else // __cplusplus
static const WFHICON WF_INVALID_HICON = NULL;
static const size_t WF_INVALID_INDEX = ((size_t)-1);
#endif // __cplusplus
#ifdef __cplusplus
/**
* @brief Registration scope for file associations
*
* Determines whether a program is registered for the current user or system-wide.
*/
enum class WFScope : uint32_t {
/** Current user scope */
User = 0u,
/** System-wide scope */
System = 1u
};
/**
* @brief View mode for querying file association status
*
* Determines how the association status is viewed/queried.
*/
enum class WFView : uint32_t {
/** User-level view */
User = 0u,
/** System-level view */
System = 1u,
/** Combined hybrid view of both user and system */
Hybrid = 2u
};
#else // __cplusplus
typedef uint32_t WFScope;
/** Current user scope */
static const WFScope WF_SCOPE_USER = 0u;
/** System-wide scope */
static const WFScope WF_SCOPE_SYSTEM = 1u;
typedef uint32_t WFView;
/** User-level view */
static const WFView WF_VIEW_USER = 0u;
/** System-level view */
static const WFView WF_VIEW_SYSTEM = 1u;
/** Combined hybrid view of both user and system */
static const WFView WF_VIEW_HYBRID = 2u;
#endif // __cplusplus
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* @brief Initialize the wfassoc library
*
* This function must be called before using the MOST of any other wfassoc functions.
*
* @return true on success, false on failure.
*/
bool WFStartup(void);
/**
* @brief Shutdown the wfassoc library
*
* Cleans up all allocated resources and object pools.
* Should be called when done using the library.
*
* @return true on success, false on failure.
*/
bool WFShutdown(void);
/**
* @brief Get the last error message
*
* Returns a human-readable error message describing the last error that occurred.
* The returned error message string is valid until the next API call.
*
* For most functions located in this library, except some special function indicated in their notes,
* they return boolean value indicating whether function is successful or not.
* Once they fail, you can call this function to get a human-readable error message.
*
* The execution of this function do not need to be wrapped by WFStartup() and WFShutdown().
*
* The string this function return use different buffer with function return string value.
* So you don't worry about that calling this function may invalidate function function return string value.
*
* @return Null-terminated UTF-8 string containing the error message.
* If no error has occurred, the string is empty.
* There is no possibility of a NULL return value.
*/
WFCString WFGetLastError(void);
/**
* @brief Check if the current process has administrative privileges
*
* This function will not throw any error.
* There is no necessity to call WFGetLastError() after this function.
* The return value only indicates whether the current process has administrative privileges or not.
*
* The execution of this function do not need to be wrapped by WFStartup() and WFShutdown().
*
* @return true if running with admin privileges, false otherwise
*/
bool WFHasPrivilege(void);
/**
* @brief Get an invalid token value
*
* In theory, invalid token value should be a constant value.
* However, due to the library I used in Rust side, this value only can be fetched at runtime.
* So I expose this function to make programmer can fetch this constant value.
* Theoretically, you just need to fetch this function only once at the beginning of your program.
*
* The execution of this function do not need to be wrapped by WFStartup() and WFShutdown().
*
* @return An invalid token value
*/
WFToken WFInvalidWFToken(void);
/**
* @brief Create a new Schema object
*
* A Schema is a sketchpad of a complete program.
* For the user of this library, they should create a Schema object first.
* Then convert it to a Program object for following operations.
*
* @param[out] out_schema Pointer to receive the Schema token.
* The receiver take the ownership of this Schema object.
* And it should be freed by calling WFSchemaDestroy() when it is no longer needed,
* or consumed by creating a Program object via WFProgramCreate().
* @return true on success, false on failure
*/
bool WFSchemaCreate(WFToken *out_schema);
/**
* @brief Destroy a Schema object
*
* Releases resources associated with the Schema object.
*
* Usually you do not need to call this function,
* because the convertion function from Schema to Program will consume given Schema object to produce Program object.
*
* @param[in] in_schema Schema token to destroy
* @return true on success, false on failure
*/
bool WFSchemaDestroy(WFToken in_schema);
/**
* @brief Set the program identifier for a Schema
*
* @param[in] in_schema Schema token
* @param[in] in_value Null-terminated UTF-8 string containing the identifier.
* This identifier should not be empty, must start with alphabet character,
* and follow with alphabet characters, digits, underline, or hyphens.
* @return true on success, false on failure
*/
bool WFSchemaSetIdentifier(WFToken in_schema, WFCString in_value);
/**
* @brief Set the program path for a Schema
*
* @param[in] in_schema Schema token
* @param[in] in_value Null-terminated UTF-8 string containing the program path.
* This path should be the fully qualified path to the application.
* @return true on success, false on failure
*/
bool WFSchemaSetPath(WFToken in_schema, WFCString in_value);
/**
* @brief Set the program CLSID for a Schema
*
* @param[in] in_schema Schema token
* @param[in] in_value Null-terminated UTF-8 string containing the CLSID.
* This CLSID string should be in the format of @c {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} .
* Please note that curly braces are required.
* @return true on success, false on failure
*/
bool WFSchemaSetClsid(WFToken in_schema, WFCString in_value);
/**
* @brief Set the program name for a Schema (optional)
*
* @param[in] in_schema Schema token
* @param[in] in_value Null-terminated UTF-8 string containing the name, or NULL to clear
* @return true on success, false on failure
*/
bool WFSchemaSetName(WFToken in_schema, WFCString in_value);
/**
* @brief Set the program icon for a Schema (optional)
*
* @param[in] in_schema Schema token
* @param[in] in_value Null-terminated UTF-8 string containing the icon path, or NULL to clear
* @return true on success, false on failure
*/
bool WFSchemaSetIcon(WFToken in_schema, WFCString in_value);
/**
* @brief Set the program behavior for a Schema (optional)
*
* @param[in] in_schema Schema token
* @param[in] in_value Null-terminated UTF-8 string containing the behavior command, or NULL to clear
* @return true on success, false on failure
*/
bool WFSchemaSetBehavior(WFToken in_schema, WFCString in_value);
/**
* @brief Add a string resource entry to a Schema
*
* @param[in] in_schema Schema token
* @param[in] in_name Null-terminated UTF-8 string containing the name of this entry
* @param[in] in_value Null-terminated UTF-8 string containing the value of this entry.
* It can be a plain string or a reference string to resource.
* @return true on success, false on failure
*/
bool WFSchemaAddStr(WFToken in_schema, WFCString in_name, WFCString in_value);
/**
* @brief Add an icon registry entry to a Schema
*
* @param[in] in_schema Schema token
* @param[in] in_name Null-terminated UTF-8 string containing the name of this entry
* @param[in] in_value Null-terminated UTF-8 string containing the value of this entry.
* It can be a path to icon or a reference string to resource.
* @return true on success, false on failure
*/
bool WFSchemaAddIcon(WFToken in_schema, WFCString in_name, WFCString in_value);
/**
* @brief Add a behavior registry entry to a Schema
*
* @param[in] in_schema Schema token
* @param[in] in_name Null-terminated UTF-8 string containing the name of this entry
* @param[in] in_value Null-terminated UTF-8 string containing the value of this entry.
* It should be a valid command line string which use \c %1, \c %2, etc. to represent parameters.
* @return true on success, false on failure
*/
bool WFSchemaAddBehavior(WFToken in_schema, WFCString in_name, WFCString in_value);
/**
* @brief Add a file extension to a Schema
*
* @param[in] in_schema Schema token
* @param[in] in_ext Null-terminated UTF-8 string containing the file extension name (without leading dot).
* @param[in] in_ext_name Null-terminated UTF-8 string containing the name pointing to associated name for this extension.
* This name should be registered by calling WFSchemaAddStr().
* @param[in] in_ext_icon Null-terminated UTF-8 string containing the name pointing to associated icon for this extension.
* This name should be registered by calling WFSchemaAddIcon().
* @param[in] in_ext_behavior Null-terminated UTF-8 string containing the name pointing to associated behavior for this extension.
* This name should be registered by calling WFSchemaAddBehavior().
* @return true on success, false on failure
*/
bool WFSchemaAddExt(WFToken in_schema,
WFCString in_ext,
WFCString in_ext_name,
WFCString in_ext_icon,
WFCString in_ext_behavior);
/**
* @brief Create a Program object from a Schema
*
* Please note that this function will consume the Schema object.
* It means that the Schema object cannot be used after this call.
* And you do not need to call WFSchemaDestroy() for this Schema object after this call.
*
* Please note that the given Schema object will always be consumed,
* no matter this function return success or failure.
*
* @param[in] in_schema Schema token (will be consumed)
* @param[out] out_program Pointer to receive the Program token.
* The receiver take the ownership of this Program object.
* And it should be freed by calling WFProgramDestroy() when it is no longer needed.
* @return true on success, false on failure
*/
bool WFProgramCreate(WFToken in_schema, WFToken *out_program);
/**
* @brief Destroy a Program object
*
* Releases resources associated with the Program.
*
* @param[in] in_program Program token to destroy
* @return true on success, false on failure
*/
bool WFProgramDestroy(WFToken in_program);
/**
* @brief Resolve the provided program name of this Program
*
* The name will be user specified first,
* then fallback to program manifest file specified name,
* and finally fallback to the file name of executable.
*
* @param[in] in_program Program token
* @param[out] out_name Pointer to receive the resolved name.
* There is no possibility that this value is NULL.
* This string will be freed at the next API call. Please make a copy immediately if you need to use it longer.
* @return true on success, false on failure
*/
bool WFProgramResolveName(WFToken in_program, WFCString *out_name);
/**
* @brief Resolve the Program icon resource
*
* The icon will be user specified first,
* the fallback to the first icon of program,
* and finally fallback to the system default executable icon.
*
* @param[in] in_program Program token
* @param[out] out_icon_rc Pointer to receive the icon resource token.
* The caller take the ownership of created icon resource object.
* And it should be freed by calling WFIconRcDestroy() when it is no longer needed.
* @return true on success, false on failure
*/
bool WFProgramResolveIcon(WFToken in_program, WFToken *out_icon_rc);
/**
* @brief Get the number of file extensions in the Program
*
* @param[in] in_program Program token
* @param[out] out_len Pointer to receive the number of extensions
* @return true on success, false on failure
*/
bool WFProgramExtsLen(WFToken in_program, size_t *out_len);
/**
* @brief Find a file extension by its body (extension string)
*
* @param[in] in_program Program token
* @param[in] in_body Null-terminated UTF-8 string containing the file extension name (without leading dot) to find.
* @param[out] out_index Pointer to receive the file extension index, or WF_INVALID_INDEX if not found.
* @return true on success, false on failure
*/
bool WFProgramFindExt(WFToken in_program, WFCString in_body, size_t *out_index);
/**
* @brief Resolve this program provided extension's details by index
*
* @param[in] in_program Program token
* @param[in] in_index Index of the extension to resolve
* @param[out] out_self_ext_status Pointer to receive the self extension status token.
* The caller take the ownership of created self extension status object.
* And it should be freed by calling WFSelfExtStatusDestroy() when it is no longer needed.
* @return true on success, false on failure
*/
bool WFProgramResolveExt(WFToken in_program, size_t in_index, WFToken *out_self_ext_status);
/**
* @brief Register the Program in the specified scope
*
* @param[in] in_program Program token
* @param[in] in_scope Registration scope
* @return true on success, false on failure
*/
bool WFProgramRegister(WFToken in_program, WFScope in_scope);
/**
* @brief Unregister the Program from the specified scope
*
* @param[in] in_program Program token
* @param[in] in_scope Registration scope
* @return true on success, false on failure
*/
bool WFProgramUnregister(WFToken in_program, WFScope in_scope);
/**
* @brief Check if the Program is registered in the specified scope
*
* @param[in] in_program Program token
* @param[in] in_scope Registration scope for checking
* @param[out] out_is_registered Pointer to receive the registration status.
* True if the Program is registered in the specified scope, false otherwise.
* @return true on success, false on failure
*/
bool WFProgramIsRegistered(WFToken in_program, WFScope in_scope, bool *out_is_registered);
/**
* @brief Link a file extension in the specified scope
*
* @param[in] in_program Program token
* @param[in] in_scope Registration scope
* @param[in] in_index Index of the extension to link
* @return true on success, false on failure
*/
bool WFProgramLinkExt(WFToken in_program, WFScope in_scope, size_t in_index);
/**
* @brief Unlink a file extension in the specified scope
*
* @param[in] in_program Program token
* @param[in] in_scope Registration scope
* @param[in] in_index Index of the extension to unlink
* @return true on success, false on failure
*/
bool WFProgramUnlinkExt(WFToken in_program, WFScope in_scope, size_t in_index);
/**
* @brief Query the status of a file extension
*
* @param[in] in_program Program token
* @param[in] in_view View viewpoint.
* @param[in] in_index Index of the extension to query
* @param[out] out_ext_status Pointer to receive the extension status token, or invalid token if not found.
* If the extension is not found, it usually means that this extension is not registered in the specified scope.
* The caller take the ownership of created extension status object.
* And it should be freed by calling WFExtStatusDestroy() when it is no longer needed.
* @return true on success, false on failure
*/
bool WFProgramQueryExt(WFToken in_program, WFView in_view, size_t in_index, WFToken *out_ext_status);
/**
* @brief Destroy an extension status object
*
* @param[in] in_ext_status Extension status token to destroy
* @return true on success, false on failure
*/
bool WFExtStatusDestroy(WFToken in_ext_status);
/**
* @brief Get the display name from an extension status object
*
* The display will be user specified first,
* the fallback to its ProgId verbatim.
*
* @param[in] in_ext_status Extension status token
* @param[out] out_name Pointer to receive the name.
* There is no possibility that this value is NULL.
* We will try to use localized name first, then use raw ProgId name if localized name is not available.
* This string will be freed at the next API call. Please make a copy immediately if you need to use it longer.
* @return true on success, false on failure
*/
bool WFExtStatusGetName(WFToken in_ext_status, WFCString *out_name);
/**
* @brief Get the icon from an extension status object
*
* The icon will be user specified first,
* the fallback to the system default file icon.
*
* @param[in] in_ext_status Extension status token
* @param[out] out_icon Pointer to receive the icon handle.
* This icon handle will be freed once this icon resource object is destroyed.
* Please make a copy immediately if you need to use it longer.
* @return true on success, false on failure
*/
bool WFExtStatusGetIcon(WFToken in_ext_status, WFHICON *out_icon);
/**
* @brief Destroy a self extension status object
*
* @param[in] in_self_ext_status Self extension status token to destroy
* @return true on success, false on failure
*/
bool WFSelfExtStatusDestroy(WFToken in_self_ext_status);
/**
* @brief Get the display name from a self extension status object
*
* The display will be user specified first,
* the fallback to its ProgId verbatim.
*
* @param[in] in_self_ext_status Self extension status token
* @param[out] out_name Pointer to receive the name string.
* There is no possibility that this value is NULL.
* This string will be freed at the next API call. Please make a copy immediately if you need to use it longer.
* @return true on success, false on failure
*/
bool WFSelfExtStatusGetName(WFToken in_self_ext_status, WFCString *out_name);
/**
* @brief Get the icon from a self extension status object
*
* The icon will be user specified first,
* the fallback to the system default file icon.
*
* @param[in] in_self_ext_status Self extension status token
* @param[out] out_icon Pointer to receive the icon handle.
* This icon handle will be freed once this self extension status object is destroyed.
* Please make a copy immediately if you need to use it longer.
* @return true on success, false on failure
*/
bool WFSelfExtStatusGetIcon(WFToken in_self_ext_status, WFHICON *out_icon);
/**
* @brief Get the extension string (without leading dot) from a self extension status object
*
* @param[in] in_self_ext_status Self extension status token
* @param[out] out_inner Pointer to receive the file extension name (without leading dot).
* There is no possibility that this value is NULL.
* This string will be freed at the next API call. Please make a copy immediately if you need to use it longer.
* @return true on success, false on failure
*/
bool WFSelfExtStatusGetExt(WFToken in_self_ext_status, WFCString *out_inner);
/**
* @brief Get the dotted extension string (with leading dot) from a self extension status object
*
* @param[in] in_self_ext_status Self extension status token
* @param[out] out_inner Pointer to receive the file extension string (with leading dot).
* There is no possibility that this value is NULL.
* This string will be freed at the next API call. Please make a copy immediately if you need to use it longer.
* @return true on success, false on failure
*/
bool WFSelfExtStatusGetDottedExt(WFToken in_self_ext_status, WFCString *out_inner);
/**
* @brief Destroy an icon resource object
*
* @param[in] in_icon_rc Icon resource token to destroy
* @return true on success, false on failure
*/
bool WFIconRcDestroy(WFToken in_icon_rc);
/**
* @brief Get the icon handle from an icon resource object
*
* @param[in] in_icon_rc Icon resource token
* @param[out] out_icon Pointer to receive the icon handle.
* There is no possibility that this value is WF_INVALID_HICON.
* This icon handle will be freed once this icon resource object is destroyed.
* Please make a copy immediately if you need to use it longer.
* @return true on success, false on failure
*/
bool WFIconRcGetIcon(WFToken in_icon_rc, WFHICON *out_icon);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#ifdef __cplusplus
} // namespace wfassoc
#endif // __cplusplus
#endif // WFASSOC_H_