WinStd/README.md

WinStd

Provides additional templates and function helpers for Windows API using Standard C++

Features

Lightweight Classes

...to simplify Windows allocated memory and resources focused on their release to prevent leakage

The classes provide unified create methods and free destructors. They are like smart-pointers for various Windows resources. Once created, you use the class instance as a snap-in replacement for pointers/handles parameters in the standard Win32 API functions.

Example

// Load and set icon.
winstd::library lib_shell32;
if (lib_shell32.load(_T("shell32.dll"), NULL, LOAD_LIBRARY_AS_DATAFILE | LOAD_LIBRARY_AS_IMAGE_RESOURCE))
    m_note_icon->SetIcon(wxLoadIconFromResource(lib_shell32, MAKEINTRESOURCE(48)));

Functions and Templates

...to extend standard Win32 API functions for variable-size outputs

Different Win32 API functions have different ways of returning variable-sized data. Getting tired of carefully studying MSDN for each particular Win32 API function how to preallocate the output memory correctly? We too...

WinStd provides a subset of Win32 API identically named functions (C++ polymorphism to the rescue), where one can use std::string, std::wstring, std::vector<> etc. as an output parameter. WinStd handles all the dirty work with memory allocation for you, so you can focus on your code.

Example

// Encode response as OEM.
std::string response;
WideCharToMultiByte(CP_OEMCP, 0, L"Copyright \u00A9 2017", response, NULL, NULL);
std::cout << response.c_str() << std::endl;

String Formatters

...for those situations where one must quckly compose a temporary string using sprintf() or FormatMessage()

Example

if (dwMaxSendPacketSize < sizeof(EapPacket))
    throw std::invalid_argument(
        winstd::string_printf(
            "Maximum packet size too small (minimum: %u, available: %u).",
            sizeof(EapPacket) + 1,
            dwMaxSendPacketSize));

Building

The WinStd.vcxproj requires Microsoft Visual Studio 2010 SP1 and ..\..\include folder with common.props, Debug.props, Release.props, Win32.props, and x64.props files to customize building process for individual applications.

Usage

1. Clone the repository into your solution folder.
2. Add the WinStd.vcxproj to your solution.
3. Add WinStd's include folder to Additional Include Directories in your project's C/C++ settings.
4. Add a new reference to WinStd project from your project's common properties.
5. Include .h files from WinStd as needed:

#include <WinStd/Shell.h>
#include <string>
#include <iostream>

void main()
{
  std::wstring path;
  PathCanonicalize(path, _T("C:\\Windows\\Temp\\test\\.."));
  std::cout << path.c_str() << std::endl;
}

More examples and use-cases can be found in GÉANTLink and ZRCola projects source code. They make heavy use of WinStd.

Debugging

For user friendlier display of variables of WinStd types in Visual Studio 2010 debugger, find the file autoexp.dat in your C:\Program Files (x86)\Microsoft Visual Studio 2010 and open it with Notepad. Locate the [AutoExpand] section and add the following lines:

winstd::variant=$BUILTIN(VARIANT)

Locate the [Visualizer] section and add the following lines:

; WinStd
winstd::com_obj<*>|winstd::handle<*>|winstd::dplhandle<*>|winstd::cert_context|winstd::cert_chain_context|winstd::cert_store|winstd::crypt_prov|winstd::crypt_hash|winstd::crypt_key|winstd::event_provider|winstd::library|winstd::heap{
        preview            ([$e.m_h])
}
winstd::bstr{
        preview            ([$e.m_h,su])
        stringview        ([$e.m_h,sub])
}
winstd::vector_queue<*>{
    preview (
        #(
            "[",
            $e.m_count,
            "](",
            #array(
                expr: $e.m_data._Myptr[($e.m_head + $i)%$e.m_size_max],
                size: $e.m_count
            ),
            ")"
        )
    )

    children (
        #(
            #([size] : $e.m_count),
            #([capacity] : $e.m_size_max),
            #array(
                expr: $e.m_data._Myptr[($e.m_head + $i)%$e.m_size_max],
                size: $e.m_count
            )
        )
    )
}
winstd::sanitizing_vector<*>{
    preview (
        #(
            "S[",
            $e._Mylast - $e._Myfirst,
            "](",
            #array(
                expr: $e._Myfirst[$i],
                size: $e._Mylast - $e._Myfirst
            ),
            ")"
        )
    )

    children (
        #(
            #([size] : $e._Mylast - $e._Myfirst),
            #([capacity] : $e._Myend - $e._Myfirst),
            #array(
                expr: $e._Myfirst[$i],
                size: $e._Mylast - $e._Myfirst
            )
        )
    )
}
winstd::eap_attr{
    preview (
        #(
            $e.eaType,
            " [",
            $e.dwLength,
            "](",
            #array(
                expr: $e.pValue[$i],
                size: $e.dwLength
            ),
            ")"
        )
    )

    children (
        #(
            #([type] : $e.eaType),
            #([size] : $e.dwLength),
            #array(
                expr: $e.pValue[$i],
                size: $e.dwLength
            )
        )
    )
}
winstd::event_data{
    preview (
        #(
            "[",
            $e.Size,
            "](",
            #array(
                expr: [((unsigned char*)$e.Ptr)[$i],x],
                size: $e.Size
            ),
            ")"
        )
    )

    children (
        #(
            #([size] : $e.Size),
            #array(
                expr: [((unsigned char*)$e.Ptr)[$i],x],
                size: $e.Size
            )
        )
    )
}