AllocMem Function

  • Article

The AllocMem callback function allocates memory from the process heap to a buffer. Any memory allocated with this function will automatically be freed by IIS when the session ends.

VOID * WINAPI * AllocMem(
   PHTTP_FILTER_CONTEXT pfc,
   DWORD cbSize,
   DWORD dwReserved
);

Parameters

  • pfc
    Points to the HTTP_FILTER_CONTEXT Structure that is associated with the current, active HTTP transaction.

  • cbSize
    Indicates the size of the buffer to be allocated, in bytes.

  • dwReserved
    Reserved for use by the server, and should be set to 0.

Return Values

Returns true if the function was successful; otherwise false. The GetLastError function indicates the reason for failure. The most common reason is as follows:

Return code

Description

ERROR_INVALID_PARAMETER

If pfc or the server context that pfc points to is invalid. Additionally, if the header name does not end with a colon (:).

Remarks

You can call AllocMem as many times as your code requires, but you cannot flush the AllocMem buffers. IIS maintains a list of allocated memory blocks created in the filter context and frees them after a SF_NOTIFY_END_OF_NET_SESSION notification. This means that the lifespan of AllocMem memory blocks is associated with the connection to the client, not with a particular request. If you are allocating a lot of memory with a Keep-Alive connection, then none of those blocks will be freed until the client is no longer connected.

As an alternative, if blocks of memory are only needed "per request", then you can use whatever memory allocation function that you like and clean up after the SF_NOTIFY_END_OF_REQUEST notification. However, it is easy to lose track of memory blocks that you have allocated if you don't fully understand when notifications fire. See Event Notification Order before you attempt to create memory blocks without using the AllocMem callback function.

If you use AllocMem, the tail bytes of the memory block are filled with a signature that the heap can check at de-allocation time to see if the memory blocks were modified. If they were modified, a heap corruption error is returned that looks like the following:

Heap block at <some address> modified

To debug this error, use the following procedure

  1. Enable pageheap for the Inetinfo.exe process by typing text at the command prompt and pressing ENTER:

    pageheap /enable inetinfo

  2. Stop the Inetinfo.exe process by typing the following:

    net stop iisadmin /y

  3. Restart the Inetinfo.exe process by typing the following:

    net start iisadmin

  4. Attach a debugger to the Inetinfo.exe process and rerun your filter. An Access Violation (AV) should occur right at the moment unauthorized code overwrites the memory block. Check the call stack of the thread that has the AV.

  5. When you are done debugging, turn pageheap off for the Inetinfo.exe process by typing the following:

    pageheap /disable inetinfo

    Then stop and start the Inetinfo.exe process as above. Pageheap reduces the performance of your Web server if you leave it enabled.

Requirements

Client: Requires Windows XP Professional, Windows 2000 Professional, or Windows NT Workstation 4.0.

Server: Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0.

Product: IIS

Header: Declared in httpfilt.h.