76

What is the difference in calling the Win32 API function that have an A character appended to the end as opposed to the W character.

I know it means ASCII and WIDE CHARACTER or Unicode, but what is the difference in the output or the input?

For example, If I call GetDefaultCommConfigA, will it fill my COMMCONFIG structure with ASCII strings instead of WCHAR strings? (Or vice-versa for GetDefaultCommConfigW)

In other words, how do I know what Encoding the string is in, ASCII or UNICODE, it must be by the version of the function I call A or W? Correct?

I have found this question, but I don't think it answers my question.

Community
  • 1
  • 1
Questionaire
  • 763
  • 1
  • 5
  • 5

1 Answers1

87

The A functions use Ansi (not ASCII) strings as input and output, and the W functions use Unicode string instead (UCS-2 on NT4 and earlier, UTF-16 on W2K and later). Refer to MSDN for more details.

Wai Ha Lee
  • 8,598
  • 83
  • 57
  • 92
Remy Lebeau
  • 555,201
  • 31
  • 458
  • 770
  • 15
    +1 - also another thing to keep in mind is that all the structures that are passed as parameters to these also come in A and W versions; so for example RegisterClassExA takes a WNDCLASSEXA which uses ANSI LPCSTRs, and while the W versions use LPCWSTRs - this prevents you from passing WCHARs to the A version, and vice versa - if you try, you'll get a compiler error about the types not matching - a fairly common beginner error is to use a cast to make the error "go away" instead of changing the code to use the right type without a cast. – BrendanMcK Sep 15 '11 at 02:43
  • 1
    How does the function without "A" or "W" postfix work? Say "GetVolumeInformation" function, does it call the GetVolumeInformationA or GetVolumeInformationW? – yu quan Mar 30 '20 at 02:49
  • 7
    @yuquan kind of. The non-A/W functions are implemented as preprocessor macros that map to the appropriate A/W functions. They do not *call* the A/W functions, but rather are *replaced* with them during the preprocessor stage, depending on whether `UNICODE` is defined or not. So, for example, if `UNICODE` is defined, a call to `GetVolumeInformation()` is replaced with a call to `GetVolumeInformationW()`, otherwise it is replaced with a call to `GetVolumeInformationA()`. – Remy Lebeau Mar 30 '20 at 04:03
  • 2
    That macro substitution "feature" is a real pain. If you have your own class function called `GetVolumeInformation` it will be silently renamed to `GetVolumeInformationA` or `GetVolumeInformationW`. Using the IDE to look up the definition will take you to the macro definition, not the function. – Mark Ransom May 28 '20 at 21:07
  • 2
    @MarkRansom Yup, and all because Microsoft won't get with the times and support C++ properly, such as by using function overloads and/or template functions rather than the preprocessor. – Remy Lebeau May 28 '20 at 21:36
  • 1
    To be fair the Win32 API still has to work from C, especially back when wide-char support was first introduced, so a C++ only solution wasn't possible. But at this point there's no excuse for not creating something better and giving you a way of opting out of the macros. – Mark Ransom May 28 '20 at 21:50
  • 1
    @MarkRansom "*the Win32 API still has to work from C*" - yes, but that doesn't mean it can't use proper wrappers for C++. It already does that for COM interfaces, so there is no reason why it can't do that for functions, too. – Remy Lebeau May 28 '20 at 21:56
  • I think we're in agreement. – Mark Ransom May 28 '20 at 21:57
  • What are ExA and ExW functions? What's the difference between these all? – Shayan Oct 19 '20 at 18:44
  • 2
    @Shayan The link in my answer, and earlier comments above, explain the `A`/`W` semantics. Those apply to `ExA`/`ExW` functions as well, which are usually just "Ex"-tended versions of earlier `A`/`W` functions. – Remy Lebeau Oct 19 '20 at 18:53