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

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

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

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

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

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

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

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

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 – 2016 Curt Hill

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

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

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