1. Windows APIs
Some odds and ends
Copyright © 1997 – 2016 Curt Hill

2. Introduction
This presentation considers some things that are commonly used but not considered else where
These include:
GetLastError
FormatMessage
CloseHandle
Copyright © 1997 – 2016 Curt Hill

3. GetLastError Almost every API call has an opportunity to fail
Duh!
These errors do not cause an abort
At least not immediately
Instead of putting an error code within the parameter list of every function, MicroSoft decided to save the error within the process
Then use GetLastError to retrieve it when needed
Copyright © 1997 – 2016 Curt Hill

4. The Function The signature: DWORD WINAPI GetLastError(void);
GetLastError returns an error code that is typically one of several defined constants
In the documentation for each API call you should see a list of the eligible errors
This suggests the following approach
Copyright © 1997 – 2016 Curt Hill

5. One Way Capture the error code with GetLastError
Decode it with a switch
Display a different message in each case of the switch
This is the wrong way, although it often can be made to work
The documentation does not always show the constants that correspond to errors
Copyright © 1997 – 2016 Curt Hill

6. Better Way There is another API that is helpful: FormatMessage
Signature: DWORD WINAPI FormatMessage( _In_     DWORD   dwFlags, _In_opt_ LPCVOID lpSource, _In_     DWORD   dwMessageId, _In_     DWORD   dwLanguageId, _Out_    LPTSTR  lpBuffer, _In_     DWORD   nSize, _In_opt_ va_list *Arguments );
Copyright © 1997 – 2016 Curt Hill

7. Even Better Way
The Threader demonstration has a method in it called DisplayAPIError
This takes a string
This is something about the context of the call that produced the error
It then calls FormatMessage and appends the resulting string onto the context message
Displays it all in a MessageBox
Copyright © 1997 – 2016 Curt Hill

8. Final Thoughts
If the DWORD returned by GetLastError is zero there was no error
It is better to use the constant: NO_ERROR
Only one error is saved and even that for a short time
Almost any API call will clear it
Therefore save and format the error quickly after the call
GetLastError calls always work
Return value may or may not
Copyright © 1997 – 2016 Curt Hill

9. Handles Again
Handles are one of those resources that need to be reclaimed
You may drive Windows into problems if you repeatedly use and do not give back handles
You return a handle with: CloseHandle which takes any handle
Does not matter what type of thing
Copyright © 1997 – Curt Hill

10. CloseHandle Again
Signature: BOOL WINAPI CloseHandle( _In_ HANDLE hObject );
Any type of handle may be closed
Usually the end of process recycles handles
Long running programs need to be more careful
Copyright © 1997 – 2016 Curt Hill

11. GetCurrentThread
A function that returns a handle to the calling thread
This handle allows the thread to modify thread attributes as if it were the thread creator
Signature: HANDLE WINAPI GetCurrentThread(void);
Handy so that any thread can get a handle to itself
Copyright © 1997 – 2016 Curt Hill

12. Finally There is always more to know Next we consider synchronization
Copyright © 1997 – 2016 Curt Hill