SBIE DLL API

This page describes the callable entrypoints in the SbieDll.dll dynamically-linked library (DLL). These entrypoints expose some functionality of Sandboxie that can be accessed programmatically, that is, through other programs rather than through a person interacting with Sandboxie.

There are three aspects to using Sandboxie programmatically:

Driving some functionality using the Start.exe program. See Start Command Line.
Injecting custom DLLs into sandboxed programs. See InjectDll.
Calling Sandboxie entrypoints from programs running (sandboxed or not). Described here.

The entrypoints described here are all exported by SbieDll.dll. To access an entrypoint, you should dynamically load this DLL into your program, and get the address of the desired entrypoint. For example,

        __declspec(dllexport) void __stdcall InjectDllMain(HINSTANCE hSbieDll, ULONG_PTR UnusedParameter)
    {
        //
            // locate the address of SbieDll_Hook in SbieDll.dll
            //

            typedef void *(__stdcall *P_SbieDll_Hook)(
                    const char *ApiName, void *ApiFunc, void *NewFunc);

            P_SbieDll_Hook p_SbieDll_Hook = GetProcAddress(hSbieDll, "SbieDll_Hook");

        //
            // invoke SbieDll_Hook through the function pointer
            //

            p_SbieDll_Hook(...);
    }

Note the use of InjectDllMain (see Inject Dll) to get a handle to the loaded instance of SbieDll. That is the recommended approach. However, using LoadLibrary or GetModuleHandle to look up SbieDll by name is also fine.

Enumerate Sandbox Names

Prototype:

        typedef LONG (__stdcall *P_SbieApi_EnumBoxes)(
                LONG index,                 // initialize to -1
                WCHAR *box_name);           // pointer to WCHAR [34]

Export Name:
```
        SbieApi_EnumBoxes
```

Parameters:

        index [in] specifies which sandbox to return.  Initialize to -1.
        Sandboxes are enumerated in the order they appear in Sandboxie.ini.

        box_name [out] receives the sandbox name.

        Note:  this function cannot be used by a sandboxed program.

Return Value:

        Returns the next value to use for the index parameter.
        Returns -1 when there is nothing left to enumerate.

Sample Code:

        WCHAR name[34];
        int index = -1;
        while (1) {
                index = SbieApi_EnumBoxes(index, name);
                if (index == -1)
                    break;
                SandboxNames_StringArray.add(name);
        }

Query Sandbox Paths by Sandbox Name

Prototype:

        typedef LONG (__stdcall *P_SbieApi_QueryBoxPath)(
                const WCHAR *box_name,      // pointer to WCHAR [34]
                WCHAR *file_path,
                WCHAR *key_path,
                WCHAR *ipc_path,
                ULONG *file_path_len,
                ULONG *key_path_len,
                ULONG *ipc_path_len);

Export Name:
```
        SbieApi_QueryBoxPath
```
Parameters:
```
                               
```
href="#__codelineno-8-1"> box_name [in] specifies the name of the sandbox for which to return path information. file_path [out] receives the path to the root directory of the sandbox, as set by the FileRootPath setting. The buffer receives at most the number of bytes specified by the file_path_len parameter. Pass NULL to ignore this parameter. key_path [out] receives the path to the root key of the sandbox registry, as set by the KeyRootPath setting. The buffer receives at most the number of bytes specified by the key_path_len parameter. Pass NULL to ignore this parameter. ipc_path [out] receives the path to the root object directory of the sandbox, as set by the IpcRootPath setting. The buffer receives at most the number of bytes specified by the ipc_path_len parameter. Pass NULL to ignore this parameter. file_path_len [in/out] specifies the length in bytes of the file_path buffer. On return, receives the length in bytes needed to receive a complete buffer. key_path_len [in/out] specifies the length in bytes of the key_path buffer. On return, receives the length in bytes needed to receive a complete buffer. ipc_path_len [in/out] specifies the length in bytes of the ipc_path buffer. On return, receives the length in bytes needed to receive a complete buffer.

Return Value:

        Returns zero on success, a non-zero value on error.

Sample Code:

        ULONG FileLen = 0;
        ULONG KeyLen  = 0;
        ULONG IpcLen  = 0;

        SbieApi_QueryBoxPath(
                NULL, NULL, NULL, NULL, &FileLen, &KeyLen, &IpcLen);

        // note that lengths are returned as the number of bytes,
        // rather than number of WCHAR characters

        WCHAR *FileBuf = malloc(FileLen);
        WCHAR *KeyBuf = malloc(KeyLen);
        WCHAR *IpcBuf = malloc(IpcLen);

        SbieApi_QueryBoxPath(
                FileBuf, KeyBuf, IpcBuf, &FileLen, &KeyLen, &IpcLen);

        // now use wcslen to count the number of characters

        FileLen = wcslen(FileBuf);
        KeyLen  = wcslen(KeyBuf);
        IpcLen  = wcslen(IpcBuf);

Query Sandbox Paths by Process ID

Prototype:

        typedef LONG (__stdcall *P_SbieApi_QueryProcessPath)(
                HANDLE process_id,
                WCHAR *file_path,
                WCHAR *key_path,
                WCHAR *ipc_path,
                ULONG *file_path_len,
                ULONG *key_path_len,
                ULONG *ipc_path_len);

Export Name:
```
        SbieApi_QueryProcessPath
```

Parameters:

        process_id [in] specifies the ID of the sandboxed process to query.

        file_path [out]

        key_path [out]

        ipc_path [out]

        file_path_len [in/out]

        key_path_len [in/out]

        ipc_path_len [in/out]

        The last six parameters are similar to the last six parameters for
        the QueryBoxPath function, discussed above.  However, QueryProcessPath
        (this function) returns the sandbox paths that are in use by a running
        program, whereas QueryBoxPath returns the paths as they are recorded
        in the Sandboxie configuration.

        Or put another way:  Suppose a sandboxed program starts with PID 124,
        and then some sandbox path (for instance FileRootPath) is set to a
        new value.  At this point, QueryBoxPath will return the new value, but
        QueryProcessPath for PID 124 will return the old value.

Return Value:

        Returns zero on success, a non-zero value on error.

Enumerate Running Processes

Prototype:

        typedef LONG (__stdcall *P_SbieApi_EnumProcessEx)(
                const WCHAR *box_name,      // pointer to WCHAR [34]
                BOOLEAN all_sessions,
                ULONG which_session,
                ULONG *boxed_pids,         // pointer to ULONG []
                ULONG *boxed_count);

Export Name:
```
        SbieApi_EnumProcessEx
```

Parameters:

        box_name [in] specifies the name of the sandbox in which
        processes will be enumerated.

        all_sessions [in] specifies TRUE to enumerate processes in all
        logon sessions or only in a particular logon session

        which_session [in] specifies the logon session number in which
        processes will be enumerated.  Ignored if all_sessions if TRUE.
        Pass the value -1 to specify the current logon session.

        boxed_pids [out] receives the process ID (PID) numbers.
        The first ULONG receives the number of processes enumerated.
        The second ULONG receives the first PID, the third ULONG receives
        the second PID, and so on.

Return Value:

       Returns zero on success, a non-zero value on error.

Query Process Information

Prototype:

        typedef LONG (__stdcall *P_SbieApi_QueryProcess)(
                HANDLE process_id,
                WCHAR *box_name,            // pointer to WCHAR [34]
                WCHAR *image_name,          // pointer to WCHAR [96]
                WCHAR *sid_string,          // pointer to WCHAR [96]
                ULONG *session_id);

Export Name:
```
        SbieApi_QueryProcess
```

Parameters:

        process_id [in] specifies the ID of the sandboxed process to query.

        box_name [out] receives the name of the sandbox in which the
        process is running.  Pass NULL to ignore this parameter.

        image_name [out] receives the process name.  Pass NULL to ignore
        this parameter.

        sid_string [out] receives the SID string for the process.
        Pass NULL to ignore this parameter.

        session_id [out] receives the logon session number in which
        the process is running.  Pass NULL to ignore this parameter.

Return Value:

        Returns zero on success, a non-zero value on error.

Terminate a Single Sandboxed Process

Prototype:

        typedef BOOLEAN (__stdcall *P_SbieDll_KillOne)(
                HANDLE process_id);

Export Name:
```
        SbieDll_KillOne
```

Parameters:

        process_id [in] specifies the process ID for the sandboxed
        process that should be terminated.

Return Value:

        Returns TRUE on success, FALSE on failure.

        The target process is terminated by the Sandboxie service
        (SbieSvc) with exit code 1 through a call to the Windows API
        TerminateProcess (ProcessId, 1).

Terminate All Sandboxed Processes

Prototype:

        typedef BOOLEAN (__stdcall *P_SbieDll_KillAll)(
                ULONG session_id,
                const WCHAR *box_name);

Export Name:
```
        SbieDll_KillAll
```

Parameters:

        session_id [in] specifies the logon session number in which
        sandboxed programs should be terminated.

        box_name [in] specifies the sandbox name in which sandboxed
        programs should be terminated.  Specify -1 to indicate the
        current logon session.

Return Value:

        Returns TRUE on success, FALSE on failure.

        The target processes are terminated in the fashion described
        above; see SbieDll_KillOne.

Query Configuration from Sandboxie.ini

Prototype:

        typedef LONG (__stdcall *P_SbieApi_QueryConf)(
                const WCHAR *section_name,  // pointer to WCHAR [34]
                const WCHAR *setting_name,  // pointer to WCHAR [66]
                ULONG setting_index,
                WCHAR *value,
                ULONG value_len)

Export Name:
```
        SbieApi_QueryConf
```

Parameters:

        section_name [in] specifies the section name that contains
        the setting to query.

        setting_name [in] specifies the setting name to query.

        setting_index [in] specifies the zero-based index number
        for a setting that may appear multiple times.  The index
        number can be logically OR'ed with these special values:

            0x40000000 - do not scan the [GlobalSettings] section
            if the specified setting name does appear in the
            specified section.

            0x20000000 - do not expand any variables in the result.

            0x10000000 - ignore any settings that originate from
            a template (typically defined in the Templates.ini file).
            only query those settings that appear explicitly in the
            Sandboxie.ini file.

        value [out] receives the value of the specified setting.

        value_len [in] specifies the maximum length in bytes of
        the buffer pointed to by the value parameter.

Return Value:

        Returns zero on success.  Returns 0xC000008B if the setting
        was not found.  Any other return value indicates some other error.

Update Configuration in Sandboxie.ini

Prototype:

        typedef LONG (__stdcall *P_SbieDll_UpdateConf)(
            WCHAR operation_code,
            const WCHAR *password,      // limited to 64 chars
                const WCHAR *section_name,  // limited to 32 chars
                const WCHAR *setting_name,  // limited to 64 chars
                const WCHAR *value)         // limited to 2000 chars

Export Name:
```
        SbieDll_UpdateConf
```

Parameters:

        operation_code [in] specifies how to update the request setting:
        's' to set (overwrite), replacing any existing values
        'a' to append the new value at the bottom of a list of values
            (or simply set the new value if there isn't one already)
        'i' to insert the new value at the top of a list of values
            (or simply set the new value if there isn't one already)
        'd' to delete an existing value in a list of values

        password [in] specifies the password to use if one is required,
        or NULL or an empty string otherwise.

        section_name [in] is a required parameter which specifies the
        section name that contains the setting to set.

        setting_name [in] is a required parameter which specifies the
        setting name to set.

        value [ini] is an optional parameter specifies the new value.

        If operation_code is 's' and value is omitted, the corresponding
        setting in the specified section will be deleted.

        If operation_code is 's' and setting_name is "*" (wildcard star)
        and value is omitted, this function deletes a complete section
        from the configuration file.

Return Value:
```
        Returns zero on success.
```

Reload Configuration from Sandboxie.ini

Prototype:

        typedef LONG (__stdcall *P_SbieApi_ReloadConf)(
                ULONG session_id);

Export Name:
```
        SbieApi_ReloadConf
```

Parameters:

        session_id [in] specifies the logon session number to which
        Sandboxie will log any error messages.  Pass -1 for the current
        logon session.

Return Value:

        Returns zero on success, a non-zero value on error.

Hook a User-Mode Entrypoint

Prototype:

        typedef void *(__stdcall *P_SbieDll_Hook)(
                const char *name,
                void *source_func,
                void *detour_func);

Export Name:
```
        SbieDll_Hook
```

Parameters:

        name [in] specifies an ASCII-string naming the entrypoint to
        be hooked.  In case of error, SbieDll_Hook logs a Sandboxie
        error message which includes this descriptive name.

        source_func [in] pointer to the function to hook.

        detour_func [in] pointer to the hook code.

        This function will cause the source function to invoke the detour
        function.  In other words, the detour function will intercept all
        calls to the source function.

Return Value:

        Returns a function pointer which can be used by the detour
        function to invoke the source function.

Sample Code:

       typedef BOOL (__stdcall *P_DeleteFileW)(const WCHAR *Path);

       P_DeleteFileW pDeleteFileW = NULL;

       BOOL __stdcall MyDeleteFileW(const WCHAR *Path)
        {
            if (Path[0] == L'C') {

                // silently ignore requests to delete any file on drive C

                SetLastError(0);
                return TRUE;

            } else {

                // otherwise invoke the original DeleteFileW function

                return pDeleteFileW(Path);
            }
        }

        main()
        {
            pDeleteFileW = GetProcAddress(kernel32dll, "DeleteFileW");
            pDeleteFileW = SbieDll_Hook("DeleteFile",
                                        pDeleteFileW,
                                        MyDeleteFileW);
        }

Register for DLL Load/Unload Callbacks

Prototype:

       typedef void (__stdcall *P_DllCallback)(const WCHAR *ImageName, HMODULE ImageBase);

       typedef BOOLEAN *(__stdcall *P_SbieDll_RegisterDllCallback)(
               P_DllCallback pCallback);

Export Name:

       SbieDll_RegisterDllCallback

       This API is available starting with version 3.46 of Sandboxie.

Parameters:

       pCallback specifies a callback function to be invoked whenever
       any DLL is loaded or unloaded in the process.  The callback
       function cannot be unregistered.

       The ImageName (first) parameter to the callback function
       specifies the UNICODE name string for the DLL that was loaded
       or unloaded.  The name string does not include a path.

       The ImageBase (second) parameter to the callback function
       specifies the load base address for the DLL, when the callback
       function is invoked to notify of a DLL load.  When the callback
       function is invoked to notify of a DLL unload, this parameter
       is set to zero.

Return Value:

       Returns TRUE on success, FALSE if the callback cannot be registered.
       As of version 3.46, Sandboxie supports up to 8 registrations within
       a single process.

Get Sandboxie Home Folder

Prototype:

       typedef LONG *(__stdcall *P_SbieApi_GetHomePath)(
               WCHAR *NtPath,
               ULONG NtPathMaxLen,
               WCHAR *DosPath,
               ULONG DosPathMaxLen);

Export Name:

       SbieApi_GetHomePath

       This API is available starting with version 3.52 of Sandboxie.

Parameters:

       NtPath specifies a pointer to a buffer which will receive the
       full path of the Sandboxie installation folder in NT-path syntax.

       NtPathMaxLen specifies the size of the NtPath buffer.  Specify
       NULL for NtPath and zero for NtPathMaxLen to not receive the
       NT path.

       DosPath specifies a pointer to a buffer which will receive the
       full path of the Sandboxie installation folder in DOS-path syntax.

       DosPathMaxLen specifies the size of the DosPath buffer.  Specify
       NULL for DosPath and zero for DosPathMaxLen to not receive the
       NT path.

Return Value:

       Returns zero on success, a non-zero value on error.

       STATUS_BUFFER_TOO_SMALL (0xC0000023) indicates either NtPathMaxLen
       or DosPathMaxLen specifies a buffer that is too small.  Increase
       the size of the input buffer and retry the call.