Add versioned API (#128)

Author: btzy

src/include/nfd.h

@@ -29,6 +29,9 @@
 
 #ifdef __cplusplus
 extern "C" {
+#define NFD_INLINE inline
+#else
+#define NFD_INLINE static inline
 #endif  // __cplusplus
 
 #include <stddef.h>
@@ -93,6 +96,59 @@ typedef struct {
 typedef nfdu8filteritem_t nfdnfilteritem_t;
 #endif  // _WIN32
 
+typedef size_t nfdversion_t;
+
+typedef struct {
+    const nfdu8filteritem_t* filterList;
+    nfdfiltersize_t filterCount;
+    const nfdu8char_t* defaultPath;
+} nfdopendialogu8args_t;
+
+#ifdef _WIN32
+typedef struct {
+    const nfdnfilteritem_t* filterList;
+    nfdfiltersize_t filterCount;
+    const nfdnchar_t* defaultPath;
+} nfdopendialognargs_t;
+#else
+typedef nfdopendialogu8args_t nfdopendialognargs_t;
+#endif  // _WIN32
+
+typedef struct {
+    const nfdu8filteritem_t* filterList;
+    nfdfiltersize_t filterCount;
+    const nfdu8char_t* defaultPath;
+    const nfdu8char_t* defaultName;
+} nfdsavedialogu8args_t;
+
+#ifdef _WIN32
+typedef struct {
+    const nfdnfilteritem_t* filterList;
+    nfdfiltersize_t filterCount;
+    const nfdnchar_t* defaultPath;
+    const nfdnchar_t* defaultName;
+} nfdsavedialognargs_t;
+#else
+typedef nfdsavedialogu8args_t nfdsavedialognargs_t;
+#endif  // _WIN32
+
+typedef struct {
+    const nfdu8char_t* defaultPath;
+} nfdpickfolderu8args_t;
+
+#ifdef _WIN32
+typedef struct {
+    const nfdnchar_t* defaultPath;
+} nfdpickfoldernargs_t;
+#else
+typedef nfdpickfolderu8args_t nfdpickfoldernargs_t;
+#endif  // _WIN32
+
+// This is a unique identifier tagged to all the NFD_*With() function calls, for backward
+// compatibility purposes.  There is usually no need to use this directly, unless you want to use
+// NFD differently depending on the version you're building with.
+#define NFD_INTERFACE_VERSION 1
+
 /** Free a file path that was returned by the dialogs.
  *
  *  Note: use NFD_PathSet_FreePathN() to free path from pathset instead of this function. */
@@ -134,6 +190,35 @@ NFD_API nfdresult_t NFD_OpenDialogU8(nfdu8char_t** outPath,
                                      nfdfiltersize_t filterCount,
                                      const nfdu8char_t* defaultPath);
 
+/** This function is a library implementation detail.  Please use NFD_OpenDialogN_With() instead. */
+NFD_API nfdresult_t NFD_OpenDialogN_With_Impl(nfdversion_t version,
+                                              nfdnchar_t** outPath,
+                                              const nfdopendialognargs_t* args);
+
+/** Single file open dialog, with additional parameters.
+ *
+ *  It is the caller's responsibility to free `outPath` via NFD_FreePathN() if this function
+ *  returns NFD_OKAY.  See documentation of nfdopendialognargs_t for details. */
+NFD_INLINE nfdresult_t NFD_OpenDialogN_With(nfdnchar_t** outPath,
+                                            const nfdopendialognargs_t* args) {
+    return NFD_OpenDialogN_With_Impl(NFD_INTERFACE_VERSION, outPath, args);
+}
+
+/** This function is a library implementation detail.  Please use NFD_OpenDialogU8_With() instead.
+ */
+NFD_API nfdresult_t NFD_OpenDialogU8_With_Impl(nfdversion_t version,
+                                               nfdu8char_t** outPath,
+                                               const nfdopendialogu8args_t* args);
+
+/** Single file open dialog, with additional parameters.
+ *
+ *  It is the caller's responsibility to free `outPath` via NFD_FreePathU8() if this function
+ *  returns NFD_OKAY.  See documentation of nfdopendialogu8args_t for details. */
+NFD_INLINE nfdresult_t NFD_OpenDialogU8_With(nfdu8char_t** outPath,
+                                             const nfdopendialogu8args_t* args) {
+    return NFD_OpenDialogU8_With_Impl(NFD_INTERFACE_VERSION, outPath, args);
+}
+
 /** Multiple file open dialog
  *
  *  It is the caller's responsibility to free `outPaths` via NFD_PathSet_FreeN() if this function
@@ -158,6 +243,36 @@ NFD_API nfdresult_t NFD_OpenDialogMultipleU8(const nfdpathset_t** outPaths,
                                              nfdfiltersize_t filterCount,
                                              const nfdu8char_t* defaultPath);
 
+/** This function is a library implementation detail.  Please use NFD_OpenDialogMultipleN_With()
+ * instead. */
+NFD_API nfdresult_t NFD_OpenDialogMultipleN_With_Impl(nfdversion_t version,
+                                                      const nfdpathset_t** outPaths,
+                                                      const nfdopendialognargs_t* args);
+
+/** Multiple file open dialog, with additional parameters.
+ *
+ *  It is the caller's responsibility to free `outPaths` via NFD_PathSet_FreeN() if this function
+ *  returns NFD_OKAY.  See documentation of nfdopendialognargs_t for details. */
+NFD_INLINE nfdresult_t NFD_OpenDialogMultipleN_With(const nfdpathset_t** outPaths,
+                                                    const nfdopendialognargs_t* args) {
+    return NFD_OpenDialogMultipleN_With_Impl(NFD_INTERFACE_VERSION, outPaths, args);
+}
+
+/** This function is a library implementation detail.  Please use NFD_OpenDialogU8_With() instead.
+ */
+NFD_API nfdresult_t NFD_OpenDialogMultipleU8_With_Impl(nfdversion_t version,
+                                                       const nfdpathset_t** outPaths,
+                                                       const nfdopendialogu8args_t* args);
+
+/** Multiple file open dialog, with additional parameters.
+ *
+ *  It is the caller's responsibility to free `outPaths` via NFD_PathSet_FreeU8() if this function
+ *  returns NFD_OKAY.  See documentation of nfdopendialogu8args_t for details. */
+NFD_INLINE nfdresult_t NFD_OpenDialogMultipleU8_With(const nfdpathset_t** outPaths,
+                                                     const nfdopendialogu8args_t* args) {
+    return NFD_OpenDialogMultipleU8_With_Impl(NFD_INTERFACE_VERSION, outPaths, args);
+}
+
 /** Save dialog
  *
  *  It is the caller's responsibility to free `outPath` via NFD_FreePathN() if this function returns
@@ -184,22 +299,80 @@ NFD_API nfdresult_t NFD_SaveDialogU8(nfdu8char_t** outPath,
                                      const nfdu8char_t* defaultPath,
                                      const nfdu8char_t* defaultName);
 
-/** Select folder dialog
+/** This function is a library implementation detail.  Please use NFD_SaveDialogN_With() instead. */
+NFD_API nfdresult_t NFD_SaveDialogN_With_Impl(nfdversion_t version,
+                                              nfdnchar_t** outPath,
+                                              const nfdsavedialognargs_t* args);
+
+/** Single file save dialog, with additional parameters.
+ *
+ *  It is the caller's responsibility to free `outPath` via NFD_FreePathN() if this function
+ *  returns NFD_OKAY.  See documentation of nfdsavedialognargs_t for details. */
+NFD_INLINE nfdresult_t NFD_SaveDialogN_With(nfdnchar_t** outPath,
+                                            const nfdsavedialognargs_t* args) {
+    return NFD_SaveDialogN_With_Impl(NFD_INTERFACE_VERSION, outPath, args);
+}
+
+/** This function is a library implementation detail.  Please use NFD_SaveDialogU8_With() instead.
+ */
+NFD_API nfdresult_t NFD_SaveDialogU8_With_Impl(nfdversion_t version,
+                                               nfdu8char_t** outPath,
+                                               const nfdsavedialogu8args_t* args);
+
+/** Single file save dialog, with additional parameters.
+ *
+ *  It is the caller's responsibility to free `outPath` via NFD_FreePathU8() if this function
+ *  returns NFD_OKAY.  See documentation of nfdsavedialogu8args_t for details. */
+NFD_INLINE nfdresult_t NFD_SaveDialogU8_With(nfdu8char_t** outPath,
+                                             const nfdsavedialogu8args_t* args) {
+    return NFD_SaveDialogU8_With_Impl(NFD_INTERFACE_VERSION, outPath, args);
+}
+
+/** Select single folder dialog
  *
  *  It is the caller's responsibility to free `outPath` via NFD_FreePathN() if this function returns
  *  NFD_OKAY.
  *  @param[out] outPath
  *  @param defaultPath If null, the operating system will decide. */
 NFD_API nfdresult_t NFD_PickFolderN(nfdnchar_t** outPath, const nfdnchar_t* defaultPath);
 
-/** Select folder dialog
+/** Select single folder dialog
  *
  *  It is the caller's responsibility to free `outPath` via NFD_FreePathU8() if this function
  *  returns NFD_OKAY.
  *  @param[out] outPath
  *  @param defaultPath If null, the operating system will decide. */
 NFD_API nfdresult_t NFD_PickFolderU8(nfdu8char_t** outPath, const nfdu8char_t* defaultPath);
 
+/** This function is a library implementation detail.  Please use NFD_PickFolderN_With() instead. */
+NFD_API nfdresult_t NFD_PickFolderN_With_Impl(nfdversion_t version,
+                                              nfdnchar_t** outPath,
+                                              const nfdpickfoldernargs_t* args);
+
+/** Select single folder dialog, with additional parameters.
+ *
+ *  It is the caller's responsibility to free `outPath` via NFD_FreePathN() if this function
+ *  returns NFD_OKAY.  See documentation of nfdpickfoldernargs_t for details. */
+NFD_INLINE nfdresult_t NFD_PickFolderN_With(nfdnchar_t** outPath,
+                                            const nfdpickfoldernargs_t* args) {
+    return NFD_PickFolderN_With_Impl(NFD_INTERFACE_VERSION, outPath, args);
+}
+
+/** This function is a library implementation detail.  Please use NFD_PickFolderU8_With() instead.
+ */
+NFD_API nfdresult_t NFD_PickFolderU8_With_Impl(nfdversion_t version,
+                                               nfdu8char_t** outPath,
+                                               const nfdpickfolderu8args_t* args);
+
+/** Select single folder dialog, with additional parameters.
+ *
+ *  It is the caller's responsibility to free `outPath` via NFD_FreePathU8() if this function
+ *  returns NFD_OKAY.  See documentation of nfdpickfolderu8args_t for details. */
+NFD_INLINE nfdresult_t NFD_PickFolderU8_With(nfdu8char_t** outPath,
+                                             const nfdpickfolderu8args_t* args) {
+    return NFD_PickFolderU8_With_Impl(NFD_INTERFACE_VERSION, outPath, args);
+}
+
 /** Get the last error
  *
  *  This is set when a function returns NFD_ERROR.
@@ -308,6 +481,7 @@ typedef nfdu8filteritem_t nfdfilteritem_t;
 #define NFD_PathSet_EnumNext NFD_PathSet_EnumNextU8
 #endif  // NFD_NATIVE
 
+#undef NFD_INLINE
 #ifdef __cplusplus
 }
 #endif  // __cplusplus

src/include/nfd.hpp

@@ -38,27 +38,31 @@ inline nfdresult_t OpenDialog(nfdnchar_t*& outPath,
                               const nfdnfilteritem_t* filterList = nullptr,
                               nfdfiltersize_t filterCount = 0,
                               const nfdnchar_t* defaultPath = nullptr) noexcept {
-    return ::NFD_OpenDialogN(&outPath, filterList, filterCount, defaultPath);
+    const nfdopendialognargs_t args{filterList, filterCount, defaultPath};
+    return ::NFD_OpenDialogN_With(&outPath, &args);
 }
 
 inline nfdresult_t OpenDialogMultiple(const nfdpathset_t*& outPaths,
                                       const nfdnfilteritem_t* filterList = nullptr,
                                       nfdfiltersize_t filterCount = 0,
                                       const nfdnchar_t* defaultPath = nullptr) noexcept {
-    return ::NFD_OpenDialogMultipleN(&outPaths, filterList, filterCount, defaultPath);
+    const nfdopendialognargs_t args{filterList, filterCount, defaultPath};
+    return ::NFD_OpenDialogMultipleN_With(&outPaths, &args);
 }
 
 inline nfdresult_t SaveDialog(nfdnchar_t*& outPath,
                               const nfdnfilteritem_t* filterList = nullptr,
                               nfdfiltersize_t filterCount = 0,
                               const nfdnchar_t* defaultPath = nullptr,
                               const nfdnchar_t* defaultName = nullptr) noexcept {
-    return ::NFD_SaveDialogN(&outPath, filterList, filterCount, defaultPath, defaultName);
+    const nfdsavedialognargs_t args{filterList, filterCount, defaultPath, defaultName};
+    return ::NFD_SaveDialogN_With(&outPath, &args);
 }
 
 inline nfdresult_t PickFolder(nfdnchar_t*& outPath,
                               const nfdnchar_t* defaultPath = nullptr) noexcept {
-    return ::NFD_PickFolderN(&outPath, defaultPath);
+    const nfdpickfoldernargs_t args{defaultPath};
+    return ::NFD_PickFolderN_With(&outPath, &args);
 }
 
 inline const char* GetError() noexcept {
@@ -99,29 +103,33 @@ inline void FreePath(nfdu8char_t* outPath) noexcept {
 
 inline nfdresult_t OpenDialog(nfdu8char_t*& outPath,
                               const nfdu8filteritem_t* filterList = nullptr,
-                              nfdfiltersize_t count = 0,
+                              nfdfiltersize_t filterCount = 0,
                               const nfdu8char_t* defaultPath = nullptr) noexcept {
-    return ::NFD_OpenDialogU8(&outPath, filterList, count, defaultPath);
+    const nfdopendialogu8args_t args{filterList, filterCount, defaultPath};
+    return ::NFD_OpenDialogU8_With(&outPath, &args);
 }
 
 inline nfdresult_t OpenDialogMultiple(const nfdpathset_t*& outPaths,
                                       const nfdu8filteritem_t* filterList = nullptr,
-                                      nfdfiltersize_t count = 0,
+                                      nfdfiltersize_t filterCount = 0,
                                       const nfdu8char_t* defaultPath = nullptr) noexcept {
-    return ::NFD_OpenDialogMultipleU8(&outPaths, filterList, count, defaultPath);
+    const nfdopendialogu8args_t args{filterList, filterCount, defaultPath};
+    return ::NFD_OpenDialogMultipleU8_With(&outPaths, &args);
 }
 
 inline nfdresult_t SaveDialog(nfdu8char_t*& outPath,
                               const nfdu8filteritem_t* filterList = nullptr,
-                              nfdfiltersize_t count = 0,
+                              nfdfiltersize_t filterCount = 0,
                               const nfdu8char_t* defaultPath = nullptr,
                               const nfdu8char_t* defaultName = nullptr) noexcept {
-    return ::NFD_SaveDialogU8(&outPath, filterList, count, defaultPath, defaultName);
+    const nfdsavedialogu8args_t args{filterList, filterCount, defaultPath, defaultName};
+    return ::NFD_SaveDialogU8_With(&outPath, &args);
 }
 
 inline nfdresult_t PickFolder(nfdu8char_t*& outPath,
                               const nfdu8char_t* defaultPath = nullptr) noexcept {
-    return ::NFD_PickFolderU8(&outPath, defaultPath);
+    const nfdpickfolderu8args_t args{defaultPath};
+    return ::NFD_PickFolderU8_With(&outPath, &args);
 }
 
 namespace PathSet {