Amebis/WinStd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation update

Browse Source
This commit is contained in:
Simon Rozman 2017-07-15 09:49:24 +02:00
parent 750f40fada
commit ffea8e5fbb
1 changed files with 142 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

241
README.md
View File

@ -1,17 +1,58 @@
#WinStd # WinStd
Provides additional templates and function helpers for Windows API using Standard C++ Provides additional templates and function helpers for Windows API using Standard C++
##Building ## Features
- The `.h` files can be used individually. However, we do encourage you to include the entire library project and reference it in dependant projects of your solution, as WinStd might develop some non-inline code over time. ### Lightweight Classes
- 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. ...to simplify Windows allocated memory and resources focused on their release to prevent leakage
##Usage 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:
```C++
// 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:
```C++
// 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:
```C++
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. 1. Clone the repository into your solution folder.
2. Add the `WinStd.vcxproj` to your solution. 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. 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. 4. Add a new reference to WinStd project from your project's common properties.
5. Include `.h` files from WinStd as needed: 5. Include `.h` files from WinStd as needed:
```C ```C++
#include <WinStd/Shell.h> #include <WinStd/Shell.h>
#include <string> #include <string>
#include <iostream> #include <iostream>
@ -20,11 +61,13 @@ void main()
{ {
std::wstring path; std::wstring path;
PathCanonicalize(path, _T("C:\\Windows\\Temp\\test\\..")); PathCanonicalize(path, _T("C:\\Windows\\Temp\\test\\.."));
std::cout << (LPCTSTR)path << std::endl; std::cout << path.c_str() << std::endl;
} }
``` ```
##Debugging More examples and use-cases can be found in [GÉANTLink](https://github.com/Amebis/GEANTLink) and [ZRCola](https://github.com/Amebis/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. 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: Locate the `[AutoExpand]` section and add the following lines:
``` ```
@ -34,110 +77,110 @@ Locate the `[Visualizer]` section and add the following lines:
``` ```
; WinStd ; 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{ 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]) preview ([$e.m_h])
} }
winstd::bstr{ winstd::bstr{
preview ([$e.m_h,su]) preview ([$e.m_h,su])
stringview ([$e.m_h,sub]) stringview ([$e.m_h,sub])
} }
winstd::vector_queue<*>{ winstd::vector_queue<*>{
preview ( preview (
#( #(
"[", "[",
$e.m_count, $e.m_count,
"](", "](",
#array( #array(
expr: $e.m_data._Myptr[($e.m_head + $i)%$e.m_size_max], expr: $e.m_data._Myptr[($e.m_head + $i)%$e.m_size_max],
size: $e.m_count size: $e.m_count
), ),
")" ")"
) )
) )
children ( children (
#( #(
#([size] : $e.m_count), #([size] : $e.m_count),
#([capacity] : $e.m_size_max), #([capacity] : $e.m_size_max),
#array( #array(
expr: $e.m_data._Myptr[($e.m_head + $i)%$e.m_size_max], expr: $e.m_data._Myptr[($e.m_head + $i)%$e.m_size_max],
size: $e.m_count size: $e.m_count
) )
) )
) )
} }
winstd::sanitizing_vector<*>{ winstd::sanitizing_vector<*>{
preview ( preview (
#( #(
"S[", "S[",
$e._Mylast - $e._Myfirst, $e._Mylast - $e._Myfirst,
"](", "](",
#array( #array(
expr: $e._Myfirst[$i], expr: $e._Myfirst[$i],
size: $e._Mylast - $e._Myfirst size: $e._Mylast - $e._Myfirst
), ),
")" ")"
) )
) )
children ( children (
#( #(
#([size] : $e._Mylast - $e._Myfirst), #([size] : $e._Mylast - $e._Myfirst),
#([capacity] : $e._Myend - $e._Myfirst), #([capacity] : $e._Myend - $e._Myfirst),
#array( #array(
expr: $e._Myfirst[$i], expr: $e._Myfirst[$i],
size: $e._Mylast - $e._Myfirst size: $e._Mylast - $e._Myfirst
) )
) )
) )
} }
winstd::eap_attr{ winstd::eap_attr{
preview ( preview (
#( #(
$e.eaType, $e.eaType,
" [", " [",
$e.dwLength, $e.dwLength,
"](", "](",
#array( #array(
expr: $e.pValue[$i], expr: $e.pValue[$i],
size: $e.dwLength size: $e.dwLength
), ),
")" ")"
) )
) )
children ( children (
#( #(
#([type] : $e.eaType), #([type] : $e.eaType),
#([size] : $e.dwLength), #([size] : $e.dwLength),
#array( #array(
expr: $e.pValue[$i], expr: $e.pValue[$i],
size: $e.dwLength size: $e.dwLength
) )
) )
) )
} }
winstd::event_data{ winstd::event_data{
preview ( preview (
#( #(
"[", "[",
$e.Size, $e.Size,
"](", "](",
#array( #array(
expr: [((unsigned char*)$e.Ptr)[$i],x], expr: [((unsigned char*)$e.Ptr)[$i],x],
size: $e.Size size: $e.Size
), ),
")" ")"
) )
) )
children ( children (
#( #(
#([size] : $e.Size), #([size] : $e.Size),
#array( #array(
expr: [((unsigned char*)$e.Ptr)[$i],x], expr: [((unsigned char*)$e.Ptr)[$i],x],
size: $e.Size size: $e.Size
) )
) )
) )
} }
``` ```