Windows APIs Some odds and ends Copyright 1997

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: – Get. Last. Error – Format. Message – Close. Handle Copyright © 1997 – 2016 Curt Hill

Get. Last. Error • 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, Micro. Soft decided to save the error within the process – Then use Get. Last. Error to retrieve it when needed Copyright © 1997 – 2016 Curt Hill

The Function • The signature: DWORD WINAPI Get. Last. Error(void); • Get. Last. Error 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 Get. Last. Error • 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: Format. Message • Signature: DWORD WINAPI Format. Message( _In_ DWORD dw. Flags, _In_opt_ LPCVOID lp. Source, _In_ DWORD dw. Message. Id, _In_ DWORD dw. Language. Id, _Out_ LPTSTR lp. Buffer, _In_ DWORD n. Size, _In_opt_ va_list *Arguments ); Copyright © 1997 – 2016 Curt Hill

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

Final Thoughts • If the DWORD returned by Get. Last. Error 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 • Get. Last. Error 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: Close. Handle which takes any handle – Does not matter what type of thing Copyright © 1997 – 2016 Curt Hill

Close. Handle Again • Signature: BOOL WINAPI Close. Handle( _In_ HANDLE h. Object ); • 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

Get. Current. Thread • A function that returns a handle to the calling thread – This handle allows the thread to modify thread attributes as if it were thread creator • Signature: HANDLE WINAPI Get. Current. Thread(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