Search code examples
cwindowswinapiipv6loopback

Can I use Windows SDK's IN6_IS_ADDR_LOOPBACK, et. al., despite no documentation?


On Linux, netinet/in.h "shall define the following macros that test for special IPv6 addresses." This includes such macros as IN6_IS_ADDR_UNSPECIFIED, IN6_IS_ADDR_LOOPBACK, IN6_IS_ADDR_LINKLOCAL, IN6_IS_ADDR_SITELOCAL, IN6_IS_ADDR_V4MAPPED, IN6_IS_ADDR_V4COMPAT, IN6_IS_ADDR_MULTICAST, and more. All very useful.

I searched the Windows (including but not limited to Winsock and Winsock 2) documentation extensively for analogs and did not find any.

But then, by accident, I discovered that Windows SDK's ws2ipdef.h defines a set of functions (not macros) with identical names and behavior (example). I can find it in numerous Windows SDK versions from the very latest and as far back as Windows 7 (I haven't been able to find older Windows SDK versions to check), but only by directly examining the header files. As a double-check, I looked at the documentation for ws2ipdef.h specifically, and neither it nor any of its sub-pages mentions any of these functions.

Furthermore, googling for these function names in quotes plus "Windows" yields absolutely no helpful or authoritative results.

So, that leads me to two questions:

  1. Is it safe to use these functions despite their lack of documentation? If they were macros, I would precautionarily define them within #ifndef blocks, but they're actual functions, so I can't do that. I have to either use them as-is or re-implement them with different names to prevent overload errors.
  2. Why wouldn't they be documented? They're clearly helpful and meant to mirror the Linux macros of the same names.

Solution

  • Since (helpful) commenters Luke and Ron chose to post comments and not answers, I'll summarize their comments and my own experience into an answer.

    I've been unable to find a version of Windows that doesn't contain these functions that mirror netinet/in.h's macros, and they appear to work properly. Luke is right that Microsoft's documentation is severely lacking, and I've had to lean heavily on StackOverflow and other websites and blogs to figure out how to properly use GetAdaptersAddresses and associated functions and types. They're public, inline functions and they appear to be fair game, as Luke said. Ron is also right that some of these macros/functions are for deprecated address ranges, and so should be used with caution. In my specific cases, I was actually using these to filter out addresses from these deprecated ranges, making them particularly appropriate for me.

    I will say that it's unfortunate Microsoft chose to implement these as functions rather than macros, making it impracticable, if not impossible, to test for their existence (and react to their nonexistence).