Why does this struct need a size value?

Question

I was reading through 'Beginning OpenGL Game Programming Second Edition' and came across this struct definition:

typedef struct tagPIXELFORMATDESCRIPTOR 
{
    WORD  nSize;    // size of the structure
    WORD  nVersion; // always set to 1
    DWORD dwFlags;  // flags for pixel buffer properties
    ...
}

"The first of the more important fields in the structure is nSize. This field should always be set equal to the size of the structure, like this: pfd.nSize = sizeof(PIXELFORMATDESCRIPTOR); This is straightforward and is a common requirement for data structures that are passed as pointers. Often, a structure needs to know its size and how much memory has been allocated for it when performing various operations. A size field allows easy and accurate access to this information." (pg. 24)

Why does the struct need the user to pass the size to it? Can code that uses this struct not just use sizeof() when needed?

Answer 1

There are at least two possible reasons for that

1. The exact definition of the struct will change with time, as the library API that uses it develops. The new fields will be added at the end, changing the definition of the struct and changing its sizeof. Yet the legacy code will still supply the "older" smaller struct to the same API functions. To make sure both the old and the new code works, run-time size information is necessary. Formally, this is what the nVersion field can be used for. That field by itself should be sufficient to tell the API what version of the API the calling code expects to be using and how many fields it allocates in the struct. But just for extra security the size information might be supplied through an independent nSize field, which is not a bad idea.

2. The struct contains optional or flexible information (regardless of the API version). The filling code will either decide what information you need or don't need based on that size or truncate the flexible-sized information based on the size you requested. This might be especially appropriate if the struct has a flexible array member at the end (along the lines of "struck hack" or such).

In this specific case (PIXELFORMATDESCRIPTOR struct from Windows API) it is the first reason that applies, since there's nothing flexible in that struct and the related API.