Windows APIs An Introduction Copyright 1997 2020 Curt

Windows APIs An Introduction Copyright © 1997 – 2020 Curt Hill

Introduction • Many complicated software systems have an Application Program Interface (API) • This allows an application to access the features of the system • What is presented is usually a system of user-callable functions or classes with public methods • Many of the functions require a control block of a particular format – These structs, as well as constants are exposed as well Copyright © 1997 – 2020 Curt Hill

Complicated systems • Such systems include: – Operating Systems – most important – Database systems – Office applications – Web servers and browsers – The list goes on and on • Today we are considering Windows – The Win. API Copyright © 1997 – 2020 Curt Hill

Topics • • Data naming conventions An example function or two Handles Error handling: – Get. Last. Error – Format. Message – Close. Handle Copyright © 1997 – 2020 Curt Hill

Generalities • Both DOS and Windows were originally written in C – Generally we have functions and no classes – Some later libraries were object oriented • Moreover, much of the code predates 32 bit machines Copyright © 1997 – 2020 Curt Hill

Naming • Microsoft used a naming convention that included type and length for both types and variables • Many types are created with a typedef since they used so often • We will consider these as we consider our example Copyright © 1997 – 2020 Curt Hill

CRUD • This is not a expression of disappointment but an acronym: – Create – Read – Update – Delete • There is a very large number of programs that follow this stream of actions • All but Delete can be done quite easily in C/C++ with normal file I/O Copyright © 1997 – 2020 Curt Hill

File Delete • Delete. File is part of the file API of Windows • It comes in two flavors: – Delete. File. A – using an ASCII file name – Delete. File. W – using an wide (Uni. Code) file name • The signature of the ASCII one is: BOOL Delete. File. A( LPCSTR lp. File. Name ); • Let’s first consider the type LPCSTR Copyright © 1997 – 2020 Curt Hill

LPCSTR • This is short for Long Pointer C-style String • In the DOS/Windows 3 days they were running on 16 bit machines that emulated an 8 bit machine – There were segments of memory and a 16 pointer could address the entire segment – A long pointer was 32 bit pointer which was good for whole address space • The CSTR indicates a C-style null terminated string Copyright © 1997 – 2020 Curt Hill

lp. File. Name • • The variable also has some typing The lp signifies that this is a long pointer The File. Name portion is the purpose In other words the parameter is a 32 -bit pointer to a string that is the intended file name • This file name may include directory information that is either relative or absolute Copyright © 1997 – 2020 Curt Hill

Wide Version • Signature is slightly different: BOOL Delete. File. W( LPCWSTR lp. File. Name ); • The W indicates that the filename will be a wide string – As does the W in the type Copyright © 1997 – 2020 Curt Hill

Commentary • Notice that types are all in upper case • Variables are mixed case – Something like the Java convention • Two other common types: – DWORD – a 32 bit signed integer – HANDLE – see next slides Copyright © 1997 – 2020 Curt Hill

A What? • In early releases of DOS file control blocks were created by the user and passed to DOS to do file operations • The problem with this approach was that it was easy for the user to cause errors by a mis-configured block • By DOS 2 they still allowed the block approach but had also introduced the handle approach Copyright © 1997 – 2020 Curt Hill

What is a handle? • A mechanism to access something owned solely by the OS • A handle could be either: – A void * pointer into OS data – Subscript into an OS array • In general we don’t know and don’t care • Windows does not want us to know this because this protects the integrity of the OS Copyright © 1997 – 2020 Curt Hill

What is accessed by handles? • Lots of completely different things: – Files accessed by windows – Processes – Threads – Synchronization object – Windows objects • Most of these handles should be concealed from us • In some cases we create a class to conceal from the user Copyright © 1997 – 2020 Curt Hill

Delete. File. A Again • Slightly more explanation BOOL Delete. File. A( LPCSTR lp. File. Name ); • The BOOL will be a zero or one – Non-zero indicated success • There at least two obvious errors, among others: – File does not exist – File is currently used by another program • How do we find what went wrong? Copyright © 1997 – 2020 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 – 2020 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 – 2020 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 – 2020 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 – 2020 Curt Hill

Even Better Way • Several projects provided by Curt have 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 – 2020 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 – 2020 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 – 2020 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 – 2020 Curt Hill

Finally • There is always more to know • Depending on the class we will look at one of several subsets of the Windows API • Think of the fun that is coming! Copyright © 1997 – 2020 Curt Hill