Core Windows Clipboard API Functions

The Windows API provides a set of functions to interact with the system clipboard, enabling applications to share data such as text, images, and file paths. Understanding these core functions is crucial for any programmatic clipboard operation:

• OpenClipboard(HWND hWnd): Acquires control of the clipboard. The hWnd parameter specifies the window that will own the clipboard, or nullptr if no specific owner window is needed. Returns TRUE on success.
• CloseClipboard(): Releases control of the clipboard, making it available for other applications.
• EmptyClipboard(): Clears any existing data from the clipboard. This should typically be called after OpenClipboard and before placing new data.
• SetClipboardData(UINT uFormat, HANDLE hMem): Places new data onto the clipboard. uFormat specifies the data format (e.g., CF_TEXT, CF_HDROP), and hMem is a handle to a global memory block containing the data. If successful, the clipboard takes ownership of hMem, and the application should not free it.
• GetClipboardData(UINT uFormat): Retrieves a handle to data from the clipboard in the specified format. The application does not own this handle and should not free it.
• IsClipboardFormatAvailable(UINT uFormat): Checks if the clipboard currently contains data in a specific format.
• RegisterClipboardFormat(LPCTSTR lpszFormat): Registers a new clipboard format string. This is used for custom formats or well-known shell formats that are identified by a string name, such as "Preferred DropEffect".

It's important to note that data placed on the clipboard must reside in global memory, typically allocated using GlobalAlloc. This ensures that the memory block can be accessed by different processes. GlobalLock provides a pointer to this memory for reading or writing, and GlobalUnlock releases the lock.

Managing Text Clipboard Content

Copying Text to the Clipboard

To place a text string on the clipboard, global memory is allocated, the string is copied into it, and then SetClipboardData is called with the appropriate format. For ANSI/MBCS strings, CF_TEXT is used; for Unicode (UTF-16) strings, CF_UNICODETEXT is preferred.

#include <windows.h>
#include <string>
#include <vector> // For std::vector<char>

void PlaceTextOnClipboard(const std::string& textInput)
{
    if (!OpenClipboard(nullptr))
    {
        // Handle error: Could not open clipboard
        return;
    }

    // Allocate global memory for the string plus a null terminator.
    // GMEM_MOVEABLE allows the system to move the block to compact memory.
    // GMEM_DDESHARE ensures it can be shared across processes.
    HGLOBAL hGlobalBuffer = GlobalAlloc(GMEM_MOVEABLE | GMEM_DDESHARE, textInput.length() + 1);
    if (!hGlobalBuffer)
    {
        CloseClipboard();
        return;
    }

    // Lock the global memory to obtain a pointer for writing.
    char* pClipboardContent = static_cast<char>(GlobalLock(hGlobalBuffer));
    if (!pClipboardContent)
    {
        GlobalFree(hGlobalBuffer); // Free memory if locking failed
        CloseClipboard();
        return;
    }

    // Copy the input string into the global memory buffer.
    // Using strcpy_s for safer string copy.
    strcpy_s(pClipboardContent, textInput.length() + 1, textInput.c_str());

    // Unlock the global memory.
    GlobalUnlock(hGlobalBuffer);

    // Clear existing clipboard content.
    EmptyClipboard();
    // Place the new data on the clipboard. The clipboard now owns hGlobalBuffer.
    SetClipboardData(CF_TEXT, hGlobalBuffer);

    CloseClipboard();
}
</char></char>

Retrieving Text from the Clipboard

Retrieving text from the clipboard involves checking if the desired format (e.g., CF_TEXT) is available, then fetching the data handle, locking it to access its pointer, and finally copying the content. The retrieved handle should not be freed by the application as it is owned by the clipboard.

#include <windows.h>
#include <string>

std::string RetrieveTextFromClipboard()
{
    std::string clipboardContent;

    if (!OpenClipboard(nullptr))
    {
        // Handle error: Could not open clipboard
        return clipboardContent;
    }

    if (IsClipboardFormatAvailable(CF_TEXT))
    {
        HGLOBAL hGlobalBuffer = GetClipboardData(CF_TEXT);
        if (hGlobalBuffer)
        {
            // Lock the global memory to get a read-only pointer.
            const char* pClipboardContent = static_cast<const char="">(GlobalLock(hGlobalBuffer));
            if (pClipboardContent)
            {
                clipboardContent = pClipboardContent;
                GlobalUnlock(hGlobalBuffer); // Unlock after reading
            }
        }
    }

    CloseClipboard();
    return clipboardContent;
}
</const>

Managing File Paths on the Clipboard

Clipboard operations for files involve two primary data formats: CF_HDROP, which holds the actual file paths, and a custom registered format, typically "Preferred DropEffect", which indicates weather the operation is a copy or a move (cut).

Placing File Paths on the Clipboard (Copy/Cut)

To put file paths on the clipboard, you must populate a DROPFILES structure followed by the null-terminated wide-character (UTF-16) file paths. The fWide member of DROPFILES must be set to TRUE. Additionally, the "Preferred DropEffect" format must be set to specify the intended file operation (copy or move).

#include <windows.h>
#include <string>
#include <vector>
#include <shlobj.h> // For DROPFILES

void SetFilePathsOnClipboard(const std::vector<std::wstring>& pathsToSet, bool isCutOperation)
{
    // Register the "Preferred DropEffect" clipboard format.
    UINT preferredDropEffectFormat = RegisterClipboardFormat(L"Preferred DropEffect");
    if (preferredDropEffectFormat == 0) return; // Error registering format

    // Calculate total buffer size for file paths (including double-null terminator).
    size_t totalPathsLength = 0;
    for (const auto& path : pathsToSet)
    {
        totalPathsLength += path.length() + 1; // +1 for null terminator per path
    }
    totalPathsLength += 1; // For the final double-null terminator at the end of the list.

    // Calculate total global memory size required for DROPFILES structure and paths.
    size_t dropFilesHeaderSize = sizeof(DROPFILES);
    size_t totalMemorySize = dropFilesHeaderSize + (totalPathsLength * sizeof(WCHAR));

    // Allocate global memory for the DROPFILES structure and the wide character file paths.
    // GMEM_ZEROINIT initializes memory to zero, ensuring null terminators.
    HGLOBAL hFilesGlobalMem = GlobalAlloc(GMEM_ZEROINIT | GMEM_MOVEABLE | GMEM_DDESHARE, totalMemorySize);
    if (!hFilesGlobalMem) return;

    // Lock the global memory to get a pointer.
    char* pRawClipboardData = static_cast<char>(GlobalLock(hFilesGlobalMem));
    if (!pRawClipboardData)
    {
        GlobalFree(hFilesGlobalMem);
        return;
    }

    // Initialize the DROPFILES structure.
    DROPFILES* pDropFiles = reinterpret_cast<DROPFILES*>(pRawClipboardData);
    pDropFiles->pFiles = dropFilesHeaderSize; // Offset to the first file path.
    pDropFiles->pt.x = 0; // Not used for clipboard operations.
    pDropFiles->pt.y = 0; // Not used for clipboard operations.
    pDropFiles->fNC = FALSE; // Not used.
    pDropFiles->fWide = TRUE; // Indicates paths are Unicode (WCHAR).

    // Copy file paths into the buffer after the DROPFILES structure.
    WCHAR* pPathsBuffer = reinterpret_cast<WCHAR*>(pRawClipboardData + dropFilesHeaderSize);
    size_t currentOffset = 0;
    for (const auto& path : pathsToSet)
    {
        wcscpy_s(pPathsBuffer + currentOffset, totalPathsLength - currentOffset, path.c_str());
        currentOffset += path.length() + 1;
    }
    // The final null terminator is already handled by GMEM_ZEROINIT if totalPathsLength is correct.

    GlobalUnlock(hFilesGlobalMem);

    // Allocate global memory for the "Preferred DropEffect" value.
    HGLOBAL hEffectGlobalMem = GlobalAlloc(GMEM_ZEROINIT | GMEM_MOVEABLE | GMEM_DDESHARE, sizeof(DWORD));
    if (!hEffectGlobalMem)
    {
        GlobalFree(hFilesGlobalMem);
        return;
    }

    DWORD* pDropEffectValue = static_cast<DWORD*>(GlobalLock(hEffectGlobalMem));
    if (!pDropEffectValue)
    {
        GlobalFree(hFilesGlobalMem);
        GlobalFree(hEffectGlobalMem);
        return;
    }

    *pDropEffectValue = isCutOperation ? DROPEFFECT_MOVE : DROPEFFECT_COPY;
    GlobalUnlock(hEffectGlobalMem);

    // Open, empty, and set the clipboard data.
    if (OpenClipboard(nullptr))
    {
        EmptyClipboard();
        SetClipboardData(CF_HDROP, hFilesGlobalMem);
        SetClipboardData(preferredDropEffectFormat, hEffectGlobalMem); // Set the preferred operation.
        CloseClipboard();
    }
    else
    {
        // If OpenClipboard fails, we must free our allocated global memory.
        GlobalFree(hFilesGlobalMem);
        GlobalFree(hEffectGlobalMem);
    }
}
</char>

Retrieving File Paths from the Clipboard

To retrieve file paths, check for the CF_HDROP format. Once the handle is obtained, the DragQueryFileW function is used to determine the number of files and extract each path individually. The "Preferred DropEffect" can also be read to ascertain if the original operation was a copy or a move.

#include <windows.h>
#include <string>
#include <vector>
#include <shlobj.h> // For HDROP, DragQueryFileW

struct ClipboardFileDetails
{
    std::vector<std::wstring> filePaths;
    DWORD dropEffect = DROPEFFECT_NONE; // e.g., DROPEFFECT_COPY, DROPEFFECT_MOVE
};

ClipboardFileDetails RetrieveFilePathsFromClipboard()
{
    ClipboardFileDetails result;

    UINT preferredDropEffectFormat = RegisterClipboardFormat(L"Preferred DropEffect");
    if (preferredDropEffectFormat == 0) return result;

    if (!OpenClipboard(nullptr))
    {
        return result;
    }

    // Attempt to get the preferred drop effect first.
    HGLOBAL hEffectGlobalMem = GetClipboardData(preferredDropEffectFormat);
    if (hEffectGlobalMem)
    {
        const DWORD* pDropEffectValue = static_cast<const DWORD*>(GlobalLock(hEffectGlobalMem));
        if (pDropEffectValue)
        {
            result.dropEffect = *pDropEffectValue;
            GlobalUnlock(hEffectGlobalMem);
        }
    }

    // Now, get the file paths using CF_HDROP.
    HDROP hDrop = static_cast<HDROP>(GetClipboardData(CF_HDROP));
    if (hDrop)
    {
        // Get the total number of files.
        UINT numberOfFiles = DragQueryFileW(hDrop, (UINT)-1, NULL, 0);
        if (numberOfFiles > 0)
        {
            result.filePaths.reserve(numberOfFiles);
            for (UINT i = 0; i < numberOfFiles; ++i)
            {
                // Get the required buffer size for the current file path.
                UINT pathLength = DragQueryFileW(hDrop, i, NULL, 0);
                if (pathLength > 0)
                {
                    std::vector<WCHAR> pathBuffer(pathLength + 1);
                    DragQueryFileW(hDrop, i, pathBuffer.data(), pathLength + 1);
                    result.filePaths.emplace_back(pathBuffer.data());
                }
            }
        }
        // The clipboard owns hDrop, so no need to call GlobalFree(hDrop).
    }

    CloseClipboard();
    return result;
}