minor bump

logs fatal, frees dyn memory and exits with EXIT_FAILURE

include/util.h

@@ -19,6 +19,5 @@ char *kind_as_string(char *s, int kind, int n);
 char *version_as_string(char *s, long v, int n);
 bool is_comment(char *s);
 struct quickcommand *command_in_quickcommands(const char *command, const struct quickcommand *quickcommands, int n);
-void clear(PT_VMR vmr, bool (*f)(PT_VMR));
 
 #endif /* __UTIL_H__ */

include/wrapper.h

@@ -32,7 +32,7 @@ long version(PT_VMR vmr, long *version);
 
 bool is_pdirty(PT_VMR vmr);
 long get_parameter_float(PT_VMR vmr, char *param, float *f);
-long get_parameter_string(PT_VMR vmr, char *param, unsigned short *s);
+long get_parameter_string(PT_VMR vmr, char *param, wchar_t *s);
 long set_parameter_float(PT_VMR vmr, char *param, float val);
 long set_parameter_string(PT_VMR vmr, char *param, char *s);
 long set_parameters(PT_VMR vmr, char *command);
@@ -41,4 +41,6 @@ bool is_mdirty(PT_VMR vmr);
 long macrobutton_getstatus(PT_VMR vmr, long n, float *val, long mode);
 long macrobutton_setstatus(PT_VMR vmr, long n, float val, long mode);
 
+void clear(PT_VMR vmr, bool (*f)(PT_VMR));
+
 #endif /* __WRAPPER_H__ */

src/interface.c

@@ -1,9 +1,9 @@
 /**
- * @file ivmr.c
+ * @file interface.c
  * @author Vincent Burel, Onyx and Iris (code@onyxandiris.online)
  * @brief Functions for initializing the iVMR interface.
  * Defines a single public function that returns a pointer to the interface.
- * @version 0.9.0
+ * @version 0.11.0
  * @date 2024-07-06
  *
  * @copyright Vincent Burel(c)2015-2021 All Rights Reserved
@@ -13,10 +13,8 @@
  * https://github.com/onyx-and-iris/vmrcli/blob/main/LICENSE
  */
 
-#include <stdbool.h>
-#include <stdio.h>
 #include <windows.h>
-#include "ivmr.h"
+#include "interface.h"
 #include "util.h"
 #include "log.h"
 
@@ -27,34 +25,37 @@
 #define PRAGMA_Pop \
     _Pragma("GCC diagnostic pop")
 
-static T_VBVMR_INTERFACE iVMR;
-
 static long initialize_dll_interfaces(PT_VMR vmr);
-static bool registry_get_voicemeeter_folder(char *szDir);
+static bool registry_get_voicemeeter_folder(char *dll_fullpath);
 
 /**
  * @brief Create an interface object
  *
  * @return PT_VMR Pointer to the iVMR interface
+ * May return NULL if the interface fails to initialize
  */
 PT_VMR create_interface()
 {
-    PT_VMR vmr = &iVMR;
-    int rep;
+    PT_VMR vmr = malloc(sizeof(T_VBVMR_INTERFACE));
+    if (vmr == NULL)
+    {
+        log_error("malloc failed to allocate memory");
+        return NULL;
+    }
 
-    rep = initialize_dll_interfaces(vmr);
+    LONG rep = initialize_dll_interfaces(vmr);
     if (rep < 0)
     {
         if (rep == -100)
         {
             log_fatal("Voicemeeter is not installed");
-            exit(EXIT_FAILURE);
         }
         else
         {
-            log_fatal("Error loading Voicemeeter dll with code %d\n", rep);
-            exit(EXIT_FAILURE);
+            log_fatal("Error loading Voicemeeter dll with code %d", rep);
         }
+        free(vmr);
+        vmr = NULL;
     }
 
     return vmr;
@@ -63,26 +64,30 @@ PT_VMR create_interface()
 /*******************************************************************************/
 /**                                GET DLL INTERFACE                          **/
 /*******************************************************************************/
+#define DLL_FULLPATH_SZ 1024
+#define DLL64_NAME "\\VoicemeeterRemote64.dll"
+#define DLL32_NAME "\\VoicemeeterRemote.dll"
+
 static long initialize_dll_interfaces(PT_VMR vmr)
 {
     HMODULE G_H_Module = NULL;
-    char szDllName[1024];
+    char dll_fullpath[DLL_FULLPATH_SZ];
     memset(vmr, 0, sizeof(T_VBVMR_INTERFACE));
 
     // get Voicemeeter installation directory
-    if (!registry_get_voicemeeter_folder(szDllName))
+    if (!registry_get_voicemeeter_folder(dll_fullpath))
     {
         // Voicemeeter not installed
         return -100;
     }
     // use right dll according to O/S type
     if (sizeof(void *) == 8)
-        strcat(szDllName, "\\VoicemeeterRemote64.dll");
+        strncat(dll_fullpath, DLL64_NAME, DLL_FULLPATH_SZ - strlen(DLL64_NAME) - 1);
     else
-        strcat(szDllName, "\\VoicemeeterRemote.dll");
+        strncat(dll_fullpath, DLL32_NAME, DLL_FULLPATH_SZ - strlen(DLL32_NAME) - 1);
 
     // Load Dll
-    G_H_Module = LoadLibrary(szDllName);
+    G_H_Module = LoadLibrary(dll_fullpath);
     if (G_H_Module == NULL)
         return -101;
 
@@ -127,33 +132,33 @@ static long initialize_dll_interfaces(PT_VMR vmr)
     if (vmr->VBVMR_Logout == NULL)
         return -2;
     if (vmr->VBVMR_RunVoicemeeter == NULL)
-        return -2;
-    if (vmr->VBVMR_GetVoicemeeterType == NULL)
         return -3;
-    if (vmr->VBVMR_GetVoicemeeterVersion == NULL)
+    if (vmr->VBVMR_GetVoicemeeterType == NULL)
         return -4;
-    if (vmr->VBVMR_IsParametersDirty == NULL)
+    if (vmr->VBVMR_GetVoicemeeterVersion == NULL)
         return -5;
-    if (vmr->VBVMR_GetParameterFloat == NULL)
+    if (vmr->VBVMR_IsParametersDirty == NULL)
         return -6;
-    if (vmr->VBVMR_GetParameterStringA == NULL)
+    if (vmr->VBVMR_GetParameterFloat == NULL)
         return -7;
-    if (vmr->VBVMR_GetParameterStringW == NULL)
+    if (vmr->VBVMR_GetParameterStringA == NULL)
         return -8;
-    if (vmr->VBVMR_GetLevel == NULL)
+    if (vmr->VBVMR_GetParameterStringW == NULL)
         return -9;
-    if (vmr->VBVMR_SetParameterFloat == NULL)
+    if (vmr->VBVMR_GetLevel == NULL)
         return -10;
-    if (vmr->VBVMR_SetParameters == NULL)
+    if (vmr->VBVMR_SetParameterFloat == NULL)
         return -11;
-    if (vmr->VBVMR_SetParametersW == NULL)
+    if (vmr->VBVMR_SetParameters == NULL)
         return -12;
-    if (vmr->VBVMR_SetParameterStringA == NULL)
+    if (vmr->VBVMR_SetParametersW == NULL)
         return -13;
-    if (vmr->VBVMR_SetParameterStringW == NULL)
+    if (vmr->VBVMR_SetParameterStringA == NULL)
         return -14;
-    if (vmr->VBVMR_GetMidiMessage == NULL)
+    if (vmr->VBVMR_SetParameterStringW == NULL)
         return -15;
+    if (vmr->VBVMR_GetMidiMessage == NULL)
+        return -16;
 
     if (vmr->VBVMR_Output_GetDeviceNumber == NULL)
         return -30;
@@ -182,50 +187,48 @@ static long initialize_dll_interfaces(PT_VMR vmr)
 /**                           GET VOICEMEETER DIRECTORY                       **/
 /*******************************************************************************/
 
+#define INSTALLER_DIR_KEY "SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall"
 #define INSTALLER_UNINST_KEY "VB:Voicemeeter {17359A74-1236-5467}"
 
 #ifndef KEY_WOW64_32KEY
 #define KEY_WOW64_32KEY 0x0200
 #endif
 
-static bool registry_get_voicemeeter_folder(char *szDir)
-{
-    char szKey[256];
-    char sss[1024];
-    DWORD nnsize = 1024;
-    HKEY hkResult;
-    LONG rep;
-    DWORD pptype = REG_SZ;
-    sss[0] = 0;
-    const char uninstDirKey[] = "SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall";
+#define UNINSTALL_KEY_SZ 256
+#define UNINSTALL_PATH_SZ 1024
 
+static bool registry_get_voicemeeter_folder(char *dll_fullpath)
+{
     // build Voicemeeter uninstallation key
-    strcpy(szKey, uninstDirKey);
-    strcat(szKey, "\\");
-    strcat(szKey, INSTALLER_UNINST_KEY);
+    char uninstall_key[UNINSTALL_KEY_SZ];
+    snprintf(uninstall_key, UNINSTALL_KEY_SZ, "%s\\%s", INSTALLER_DIR_KEY, INSTALLER_UNINST_KEY);
 
     // open key
-    rep = RegOpenKeyEx(HKEY_LOCAL_MACHINE, szKey, 0, KEY_READ, &hkResult);
+    HKEY result;
+    LONG rep = RegOpenKeyEx(HKEY_LOCAL_MACHINE, uninstall_key, 0, KEY_READ, &result);
     if (rep != ERROR_SUCCESS)
     {
         // if not present we consider running in 64bit mode and force to read 32bit registry
-        rep = RegOpenKeyEx(HKEY_LOCAL_MACHINE, szKey, 0, KEY_READ | KEY_WOW64_32KEY, &hkResult);
+        rep = RegOpenKeyEx(HKEY_LOCAL_MACHINE, uninstall_key, 0, KEY_READ | KEY_WOW64_32KEY, &result);
     }
     if (rep != ERROR_SUCCESS)
         return false;
+
     // read uninstall path from registry
-    rep = RegQueryValueEx(hkResult, "UninstallString", 0, &pptype, (unsigned char *)sss, &nnsize);
-    RegCloseKey(hkResult);
+    DWORD pptype = REG_SZ;
+    DWORD len_uninstall_path = UNINSTALL_PATH_SZ;
+    char uninstall_path[UNINSTALL_PATH_SZ] = {0};
+    rep = RegQueryValueEx(result, "UninstallString", 0, &pptype, (unsigned char *)uninstall_path, &len_uninstall_path);
+    RegCloseKey(result);
 
     if (pptype != REG_SZ)
         return false;
     if (rep != ERROR_SUCCESS)
         return false;
+
     // remove name to get the path only
-    remove_last_part_of_path(sss);
-    if (nnsize > 512)
-        nnsize = 512;
-    strncpy(szDir, sss, nnsize);
+    remove_last_part_of_path(uninstall_path);
+    snprintf(dll_fullpath, DLL_FULLPATH_SZ, uninstall_path);
 
     return true;
 }

src/util.c

@@ -2,25 +2,21 @@
  * @file util.c
  * @author Onyx and Iris (code@onyxandiris.online)
  * @brief Utility functions.
- * @version 0.9.0
+ * @version 0.11.0
  * @date 2024-07-06
  *
  * @copyright Copyright (c) 2024
  * https://github.com/onyx-and-iris/vmrcli/blob/main/LICENSE
  */
 
-#include <stddef.h>
 #include <stdio.h>
 #include <string.h>
-#include <ctype.h>
-#include <windows.h>
-#include "wrapper.h"
 #include "util.h"
 
 /**
  * @brief Removes the last part of a path
  *
- * @param fullpath The entire path
+ * @param fullpath
  */
 void remove_last_part_of_path(char *fullpath)
 {
@@ -35,7 +31,7 @@ void remove_last_part_of_path(char *fullpath)
 /**
  * @brief Converts Voicemeeter's kind into a string.
  *
- * @param s Pointer to a character buffer
+ * @param s Pointer to a character buffer receiving the kind
  * @param kind The kind of Voicemeeter.
  * @param n Maximum number of characters to be written to the buffer
  * @return char* String representation of the kind of Voicemeeter.
@@ -57,7 +53,7 @@ char *kind_as_string(char *s, int kind, int n)
 /**
  * @brief Converts Voicemeeter's version into a string.
  *
- * @param s Pointer to a character buffer
+ * @param s Pointer to a character buffer receiving the version
  * @param v Unprocessed version as a long int
  * @param n Maximum number of characters to be written to the buffer
  * @return char* String representation of the Voicemeeter version
@@ -105,16 +101,3 @@ struct quickcommand *command_in_quickcommands(const char *command_key, const str
     }
     return NULL;
 }
-
-/**
- * @brief Continuously polls an is_{}dirty function until it clears.
- *
- * @param vmr Pointer to the iVMR interface
- * @param f Pointer to a polling function
- */
-void clear(PT_VMR vmr, bool (*f)(PT_VMR))
-{
-    Sleep(30);
-    while (f(vmr))
-        Sleep(1);
-}

src/vmrcli.c

@@ -2,7 +2,7 @@
  * @file vmrcli.c
  * @author Onyx and Iris (code@onyxandiris.online)
  * @brief A Voicemeeter Remote Command Line Interface
- * @version 0.9.0
+ * @version 0.11.0
  * @date 2024-07-06
  *
  * @copyright Copyright (c) 2024
@@ -11,12 +11,9 @@
 
 #include <stdio.h>
 #include <stdlib.h>
-#include <stdbool.h>
 #include <getopt.h>
-#include <string.h>
-#include <ctype.h>
 #include <windows.h>
-#include "ivmr.h"
+#include "interface.h"
 #include "wrapper.h"
 #include "log.h"
 #include "util.h"
@@ -47,7 +44,9 @@ enum restype : int
 };
 
 /**
- * @struct A struct holding the result of a get call.
+ * @struct A struct used for:
+ * - tracking the type of value stored
+ * - storing the result of a get call
  */
 struct result
 {
@@ -61,12 +60,13 @@ struct result
 
 static bool vflag = false;
 
+static void terminate(PT_VMR vmr, char *msg);
 static void usage();
-enum kind set_kind(char *kval);
-void interactive(PT_VMR vmr, bool with_prompt);
-void parse_input(PT_VMR vmr, char *input);
-void parse_command(PT_VMR vmr, char *command);
-void get(PT_VMR vmr, char *command, struct result *res);
+static enum kind set_kind(char *kval);
+static void interactive(PT_VMR vmr, bool with_prompt);
+static void parse_input(PT_VMR vmr, char *input);
+static void parse_command(PT_VMR vmr, char *command);
+static void get(PT_VMR vmr, char *command, struct result *res);
 
 int main(int argc, char *argv[])
 {
@@ -150,30 +150,36 @@ int main(int argc, char *argv[])
     }
 
     PT_VMR vmr = create_interface();
+    if (vmr == NULL)
+    {
+        exit(EXIT_FAILURE);
+    }
 
     long rep = login(vmr, kind);
     if (rep != 0)
     {
-        log_fatal("Error logging into the Voicemeeter API");
-        exit(EXIT_FAILURE);
+        if (rep == -2)
+            terminate(vmr, "Timeout logging into the API.");
+        else
+            terminate(vmr, "Error logging into the Voicemeeter API");
     }
 
     if (mflag)
     {
-        log_info("MacroButtons app launched");
         run_voicemeeter(vmr, MACROBUTTONS);
+        log_info("MacroButtons app launched");
     }
 
     if (sflag)
     {
-        log_info("StreamerView app launched");
         run_voicemeeter(vmr, STREAMERVIEW);
+        log_info("StreamerView app launched");
     }
 
     if (cflag)
     {
-        log_info("Profile %s loaded", cvalue);
         set_parameter_string(vmr, "command.load", cvalue);
+        log_info("Profile %s loaded", cvalue);
         Sleep(300);
         clear(vmr, is_pdirty);
     }
@@ -194,17 +200,29 @@ int main(int argc, char *argv[])
     rep = logout(vmr);
     if (rep != 0)
     {
-        log_fatal("Error logging out of the Voicemeeter API");
-        return EXIT_FAILURE;
+        terminate(vmr, "Error logging out of the Voicemeeter API");
     }
-    else
-    {
+
+    log_info("Successfully logged out of the Voicemeeter API");
+    free(vmr);
     return EXIT_SUCCESS;
 }
-}
 
 /**
- * @brief prints the help message
+ * @brief Write fatal error log, free dyn allocated memory then exit
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param msg Fatal error message
+ */
+static void terminate(PT_VMR vmr, char *msg)
+{
+    log_fatal(msg);
+    free(vmr);
+    exit(EXIT_FAILURE);
+}
+
+/**
+ * @brief Prints the help message
  */
 static void usage()
 {
@@ -219,7 +237,7 @@ static void usage()
  * @param kval Value of the -k flag
  * @return enum kind
  */
-enum kind set_kind(char *kval)
+static enum kind set_kind(char *kval)
 {
     if (strcmp(kval, "basic") == 0)
         return sizeof(void *) == 8 ? BASICX64 : BASIC;
@@ -239,7 +257,7 @@ enum kind set_kind(char *kval)
  * @param vmr Pointer to the iVMR interface
  * @param with_prompt If true, prints the interactive prompt '>>'
  */
-void interactive(PT_VMR vmr, bool with_prompt)
+static void interactive(PT_VMR vmr, bool with_prompt)
 {
     char input[MAX_LINE];
     size_t len;
@@ -268,7 +286,7 @@ void interactive(PT_VMR vmr, bool with_prompt)
  * @param vmr Pointer to the iVMR interface
  * @param input Each input line, from stdin or CLI args
  */
-void parse_input(PT_VMR vmr, char *input)
+static void parse_input(PT_VMR vmr, char *input)
 {
     if (is_comment(input))
         return;
@@ -291,7 +309,7 @@ void parse_input(PT_VMR vmr, char *input)
  * @param vmr Pointer to the iVMR interface
  * @param command Each token from the input line as its own command string
  */
-void parse_command(PT_VMR vmr, char *command)
+static void parse_command(PT_VMR vmr, char *command)
 {
     log_debug("Parsing %s", command);
 
@@ -369,9 +387,9 @@ void parse_command(PT_VMR vmr, char *command)
  *
  * @param vmr Pointer to the iVMR interface
  * @param command A parsed 'get' command as a string
- * @param res A struct holding the result of the API call.
+ * @param res Pointer to a struct holding the result of the API call.
  */
-void get(PT_VMR vmr, char *command, struct result *res)
+static void get(PT_VMR vmr, char *command, struct result *res)
 {
     clear(vmr, is_pdirty);
     if (get_parameter_float(vmr, command, &res->val.f) != 0)

src/wrapper.c

@@ -2,7 +2,7 @@
  * @file wrapper.c
  * @author Onyx and Iris (code@onyxandiris.online)
  * @brief Provides public functions that wrap the iVMR calls
- * @version 0.9.0
+ * @version 0.11.0
  * @date 2024-07-06
  *
  * @copyright Copyright (c) 2024
@@ -10,8 +10,6 @@
  */
 
 #include <windows.h>
-#include <stdio.h>
-#include <time.h>
 #include "wrapper.h"
 #include "log.h"
 #include "util.h"
@@ -27,7 +25,9 @@
  *
  * @param vmr Pointer to the iVMR interface
  * @param kind The kind of Voicemeeter Gui to launch.
- * @return long VBVMR_Login return value
+ * @return long
+ *  0: OK (no error).
+ * -2: Login timed out.
  */
 long login(PT_VMR vmr, int kind)
 {
@@ -54,15 +54,12 @@ long login(PT_VMR vmr, int kind)
             log_info(
                 "Successfully logged into the Voicemeeter API v%s",
                 version_as_string(version_s, v, VERSION_STR_LEN));
+            clear(vmr, is_pdirty);
             break;
         }
         Sleep(50);
     } while (difftime(time(NULL), start) < LOGIN_TIMEOUT);
 
-    if (rep == 0)
-    {
-        clear(vmr, is_pdirty);
-    }
     return rep;
 }
 
@@ -71,88 +68,201 @@ long login(PT_VMR vmr, int kind)
  * final instruction to complete.
  *
  * @param vmr Pointer to the iVMR interface
- * @return long VBVMR_Logout return value
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L56
  */
 long logout(PT_VMR vmr)
 {
-    long rep;
-
     Sleep(20); /* give time for last command */
     log_trace("VBVMR_Logout()");
-    rep = vmr->VBVMR_Logout();
-    if (rep == 0)
-        log_info("Successfully logged out of the Voicemeeter API");
-    return rep;
+    return vmr->VBVMR_Logout();
 }
 
+/**
+ * @brief Launches Voicemeeter or other utility apps
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param kind The kind of app to launch
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L66
+ */
 long run_voicemeeter(PT_VMR vmr, int kind)
 {
     log_trace("VBVMR_RunVoicemeeter(%d)", kind);
     return vmr->VBVMR_RunVoicemeeter((long)kind);
 }
 
+/**
+ * @brief Get Voicemeeter type
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param type Pointer to a long object receiving the type
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L107
+ */
 long type(PT_VMR vmr, long *type)
 {
     log_trace("VBVMR_GetVoicemeeterType(<long> *t)");
     return vmr->VBVMR_GetVoicemeeterType(type);
 }
 
+/**
+ * @brief Get Voicemeeter version
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param version Pointer to a long object receiving the version
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L122
+ */
 long version(PT_VMR vmr, long *version)
 {
     log_trace("VBVMR_GetVoicemeeterVersion(<long> *v)");
     return vmr->VBVMR_GetVoicemeeterVersion(version);
 }
 
+/**
+ * @brief Polling function, use it to determine if there are parameter
+ * states to be updated.
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @return true New parameters yet to be updated
+ * @return false No new parameters, safe to make a get call
+ */
 bool is_pdirty(PT_VMR vmr)
 {
     log_trace("VBVMR_IsParametersDirty()");
     return vmr->VBVMR_IsParametersDirty() == 1;
 }
 
+/**
+ * @brief Get the parameter float object
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param param The parameter to be queried
+ * @param f Pointer to a float object receiving the value
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L159
+ */
 long get_parameter_float(PT_VMR vmr, char *param, float *f)
 {
     log_trace("VBVMR_GetParameterFloat(%s, <float> *f)", param);
     return vmr->VBVMR_GetParameterFloat(param, f);
 }
 
-long get_parameter_string(PT_VMR vmr, char *param, unsigned short *s)
+/**
+ * @brief Get the parameter string object
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param param The parameter to be queried
+ * @param s Pointer to a character buffer receiving the string value
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L173
+ */
+long get_parameter_string(PT_VMR vmr, char *param, wchar_t *s)
 {
-    log_trace("VBVMR_GetParameterStringW(%s, <unsigned short> *s)", param);
+    log_trace("VBVMR_GetParameterStringW(%s, <wchar_t> *s)", param);
     return vmr->VBVMR_GetParameterStringW(param, s);
 }
 
+/**
+ * @brief Set the parameter float object
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param param The parameter to be updated
+ * @param val The new value
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L309
+ */
 long set_parameter_float(PT_VMR vmr, char *param, float val)
 {
     log_trace("VBVMR_SetParameterFloat(%s, %.1f)", param, val);
     return vmr->VBVMR_SetParameterFloat(param, val);
 }
 
+/**
+ * @brief Set the parameter string object
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param param The parameter to be updated
+ * @param s Pointer to a char[] object containing the new value
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L327
+ */
 long set_parameter_string(PT_VMR vmr, char *param, char *s)
 {
     log_trace("VBVMR_SetParameterStringA(%s, %s)", param, s);
     return vmr->VBVMR_SetParameterStringA(param, s);
 }
 
+/**
+ * @brief Run a script possibly containing multiple instructions
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param command Pointer to a char[] object containing the script
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L351
+ */
 long set_parameters(PT_VMR vmr, char *command)
 {
     log_trace("VBVMR_SetParameters(%s)", command);
     return vmr->VBVMR_SetParameters(command);
 }
 
+/**
+ * @brief Polling function, use it to determine if there are macrobutton
+ * states to be updated.
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @return true Macrobutton states yet to be udpated
+ * @return false No new macrobutton states
+ */
 bool is_mdirty(PT_VMR vmr)
 {
     log_trace("VBVMR_MacroButton_IsDirty()");
-    return vmr->VBVMR_MacroButton_IsDirty() == 1;
+    return vmr->VBVMR_MacroButton_IsDirty() >= 0;
 }
 
+/**
+ * @brief Get the current status of macrobutton[n].{mode}
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param n Index of the macrobutton
+ * @param val Pointer to a float object the current value will be stored in
+ * @param mode The mode (stateonly, state, trigger)
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L663
+ */
 long macrobutton_getstatus(PT_VMR vmr, long n, float *val, long mode)
 {
     log_trace("VBVMR_MacroButton_GetStatus(%ld, <float> *v, %ld)", n, mode);
     return vmr->VBVMR_MacroButton_GetStatus(n, val, mode);
 }
 
+/**
+ * @brief Set the current status of macrobutton[n].{mode}
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param n Index of the macrobutton
+ * @param val Value to be updated
+ * @param mode The mode (stateonly, state, trigger)
+ * @return long See:
+ * https://github.com/onyx-and-iris/vmrcli/blob/main/include/VoicemeeterRemote.h#L677
+ */
 long macrobutton_setstatus(PT_VMR vmr, long n, float val, long mode)
 {
     log_trace("VBVMR_MacroButton_SetStatus(%ld, %d, %ld)", n, (int)val, mode);
     return vmr->VBVMR_MacroButton_SetStatus(n, val, mode);
 }
+
+/**
+ * @brief Continuously polls an is_{}dirty function until it clears.
+ *
+ * @param vmr Pointer to the iVMR interface
+ * @param f Pointer to a polling function
+ */
+void clear(PT_VMR vmr, bool (*f)(PT_VMR))
+{
+    Sleep(30);
+    while (f(vmr))
+        Sleep(1);
+}