Skip to content

Commit

Permalink
Fix WIL doc summary (#786)
Browse files Browse the repository at this point in the history
- "Windows Internal Library" got named "Windows Implementation Library" for its GH release
- Fixed the links to point to the files in the WIL GH instead of the local copies.
- Left the rest of this as general guidance to how we use it.
  • Loading branch information
miniksa authored May 14, 2019
1 parent 303e227 commit 7c6278d
Showing 1 changed file with 4 additions and 4 deletions.
8 changes: 4 additions & 4 deletions doc/WIL.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
# Windows Internal Library
# Windows Implementation Library

## Overview
Windows Internal Library, or WIL, is a header-only library created to help make working with the Windows API more predictable and (hopefully) bug free.
[Windows Implementation Library](https://github.com/Microsoft/wil), or WIL, is a header-only library created to help make working with the Windows API more predictable and (hopefully) bug free.

A majority of functions are in either the `wil::` or `wistd::` namespace. `wistd::` is used for things that have an equivalent in STL's `std::` namespace but have some special functionality like being exception-free. Everything else is in `wil::` namespace.

The primary usages of WIL in our code so far are...

### Smart Pointers ###

Inside [wil\resource.h](..\dep\wil\resource.h) are smart pointer like classes for many Windows OS resources like file handles, socket handles, process handles, and so on. They're of the form `wil::unique_handle` and call the appropriate/matching OS function (like `CloseHandle()` in this case) when they go out of scope.
Inside [wil\resource.h](https://github.com/microsoft/wil/blob/master/include/wil/resource.h) are smart pointer like classes for many Windows OS resources like file handles, socket handles, process handles, and so on. They're of the form `wil::unique_handle` and call the appropriate/matching OS function (like `CloseHandle()` in this case) when they go out of scope.

Another useful item is `wil::make_unique_nothrow()` which is analogous to `std::make_unique` (except without the exception which might help you integrate with existing exception-free code in the console.) This will return a `wistd::unique_ptr` (vs. a `std::unique_ptr`) which can be used in a similar manner.

### Result Handling ###

To manage the various types of result codes that come back from Windows APIs, the file [wil\result.h](..\dep\wil\result.h) provides a wealth of macros that can help.
To manage the various types of result codes that come back from Windows APIs, the file [wil\result.h](https://github.com/microsoft/wil/blob/master/include/wil/result.h) provides a wealth of macros that can help.

As an example, the method `DuplicateHandle()` returns a `BOOL` value that is `FALSE` under failure and would like you to `GetLastError()` from the operating system to find out what the actual result code is. In this circumstance, you could use the macro `RETURN_IF_WIN32_BOOL_FALSE` to wrap the call to `DuplicateHandle()` which would automatically handle this pattern for you and return the `HRESULT` equivalent on failure.

Expand Down

0 comments on commit 7c6278d

Please sign in to comment.