Rules for Using Pointers

[This is preliminary documentation and subject to change.]

Modifying your code to compile as both a Win32- and Win64-based application is straightforward. You need only follow a few simple rules about casting pointers, and use the new data types in your code. The rules for pointer manipulation are as follows.

1. Do not cast pointers to int, long, ULONG, or DWORD.

   If you must cast a pointer to test some bits, set or clear bits, or otherwise manipulate its contents, use the UINT_PTR or INT_PTR type. These types are integral types that scale to the size of a pointer for both 32-bit and 64-bit Windows (for example, ULONG for 32-bit Windows and _int64 for 64-bit Windows). For example, assume you are porting the following code:

   ImageBase = (PVOID)((ULONG)ImageBase | 1);
    

   As a part of the porting process, you would change the code as follows:

   ImageBase = (PVOID)((ULONG_PTR)ImageBase | 1);
    

   Use UINT_PTR and INT_PTR where appropriate (and if you are uncertain whether they are required, there is no harm in using them just in case). Do not cast your pointers to the types ULONG, LONG, INT, UINT, or DWORD.

   Note that HANDLE is defined as a void *, so typecasting a HANDLE value to a ULONG value to test, set, or clear the low two bits is an error in Win64 programming.

2. Use the PtrToLong or PtrToUlong function to truncate pointers.

   If you must truncate a pointer to a 32-bit value, use the PtrToLong or PtrToUlong function (defined in Basetsd.h). This function disables the pointer truncation warning for the duration of the call.

   Use these functions carefully. After you convert a pointer variable using one of these functions, never use it as a pointer again. These functions truncate the upper 32 bits of an address, which are usually needed to access the memory originally referenced by pointer. Using these functions without careful consideration will result in fragile code.

3. Be careful using OUT parameters.

   For example, suppose func is defined as follows:

   void func( OUT PULONG *PointerToUlong );
    

   Do not call func as follows:

   ULONG ul;
   PULONG lp;
   func((PULONG *)&ul);
   lp = (PULONG)ul;
    

   Instead, call func as follows:

   PULONG lp;
   func(&lp);
    

   Typecasting &ul to PULONG * prevents a compiler error, but the function will write a 64-bit pointer value into the memory at &ul. This code works on 32-bit Windows, but will cause data corruption on 64-bit Windows—and it will be subtle, hard-to-find corruption. The bottom line: Do not play tricks with the C code—straightforward and simple is better.

4. Be careful with polymorphic interfaces.

   Do not create functions that accept DWORD parameters for polymorphic data. If the data can be a pointer or an integral value, use the UINT_PTR or PVOID type.

   For example, do not create a function that accepts an array of exception parameters typed as DWORD values. The array should be an array of DWORD_PTR values. Therefore, the array elements can hold addresses or 32-bit integral values. (The general rule is that if the original type is DWORD and it needs to be pointer width, convert it to a DWORD_PTR value. That is why there are corresponding pointer-precision types for the native Win32 types.) If you have code that uses DWORD, ULONG, or other 32-bit types in a polymorphic way (that is, you really want the parameter or structure member to hold an address), use UINT_PTR in place of the current type.

5. Use the new window class functions.

   If you have window or class private data that contains pointers, your code will need to use the following new functions:

   • GetClassLongPtr
   • GetWindowLongPtr
   • SetClassLongPtr
   • SetWindowLongPtr

   These functions can be used in both Win32- and Win64-based applications, but they are required in Win64-based applications. Prepare for the transition by using these functions now.

   Additionally, you must access pointers or handles in class private data using the new functions on 64-bit platforms. To aid you in finding these cases, the following indexes are not defined in Winuser.h during a 64-bit compile:

   • GWL_WNDPROC
   • GWL_HINSTANCE
   • GWL_HWDPARENT
   • GWL_USERDATA

   Instead, Winuser.h defines the following new indexes for both Win32- and Win64-based applications:

   • GWLP_WNDPROC
   • GWLP_HINSTANCE
   • GWLP_HWNDPARENT
   • GWLP_USERDATA
   • GWLP_ID

   For example, the following code does not compile:

   SetWindowLong(hWnd, GWL_WNDPROC, (LONG)MyWndProc);
    

   It should be changed as follows:

   SetWindowLongPtr(hWnd, GWLP_WNDPROC, (LONG_PTR)MyWndProc);
    

   When setting the cbWndExtra member of the WNDCLASS structure, be sure to reserve enough space for pointers. For example, if you are currently reserving sizeof(DWORD) bytes for a pointer value, reserve sizeof(DWORD_PTR) bytes.

6. Access all window and class data using FIELD_OFFSET.

   It is common to access window data using hard-coded offsets. This technique is not portable to 64-bit Windows. To make your code portable, access your window and class data using the FIELD_OFFSET macro. Do not assume that the second pointer has an offset of 4.

7. The LPARAM, WPARAM, and LRESULT types change size with the platform.

   When compiling 64-bit code, these types expand to 64 bits, because they typically hold pointers or integral types. Do not mix these values with DWORD, ULONG, UINT, INT, int, or long values. Examine how you use these types and ensure that you do not inadvertently truncate values.