StatusRoutine Callback Function

Debug Help Library

StatusRoutine Callback Function

An application-defined callback function used with the BindImageEx function. The status routine is called during the process of the image binding.

The PIMAGEHLP_STATUS_ROUTINE type defines a pointer to this callback function. StatusRoutine is a placeholder for the application-defined function name.

BOOL StatusRoutine(
  [in]                 IMAGEHLP_STATUS_REASON Reason,
  [in]                 PSTR ImageName,
  [in]                 PSTR DllName,
  [in]                 ULONG_PTR Va,
  [in]                 ULONG_PTR Parameter
);

Parameters

Reason

The current status of the bind operation. This parameter can be one of the following values.

Value Meaning

BindOutOfMemory
0

Out of memory. The Parameter value is the number of bytes in the allocation attempt.

BindRvaToVaFailed
1

The relative virtual address is invalid for the image. The Parameter value is not used.

BindNoRoomInImage
2

No room in the image for new format import table. The Parameter value is not used.

BindImportModuleFailed
3

Module import failed. The Parameter value is not used.

BindImportProcedureFailed
4

Procedure import failed. The Parameter value is the name of the function.

BindImportModule
5

Module import is starting. The Parameter value is not used.

BindImportProcedure
6

Procedure import is starting. The Parameter value is the name of the function.

BindForwarder
7

The Parameter value is the name of the function forwarded.

BindForwarderNOT
8

The Parameter value is the name of the function not forwarded.

BindImageModified
9

Image modified. The Parameter value is not used.

BindExpandFileHeaders
10

File headers expanded. The Parameter value is the number of bytes

BindImageComplete
11

Binding is complete. For more information on the Parameter value, see the following Remarks section.

BindMismatchedSymbols
12

Checksum did not match. The Parameter value is the name of the symbol file.

BindSymbolsNotUpdated
13

Symbol file was not updated. The Parameter value is the name of the symbol file not updated.

ImageName

The name of the file to be bound. This value can be a file name, a partial path, or a full path.

DllName

The name of the DLL.

Va

The computed virtual address.

Parameter

Any additional status information. This value depends on the value of the Reason parameter. For more information, see the code fragment in the following Remarks section.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

The following code fragment describes the contents of the Parameter value when the status is BindImageComplete.

case BindImageComplete:
    if (fVerbose) {
        fprintf(stderr, "BIND: Details of binding %s\n", ImageName );
        NewImports = (PIMAGE_BOUND_IMPORT_DESCRIPTOR)Va;
        NewImport = NewImports;
        while (NewImport->OffsetModuleName) {
            fprintf( stderr, "    Import from %s [%x]",
                     (LPSTR)NewImports + NewImport->OffsetModuleName,
                     NewImport->TimeDateStamp
                   );
            if (NewImport->NumberOfModuleForwarderRefs != 0) {
                fprintf( stderr, " with %u forwarders", NewImport-> 
                         NumberOfModuleForwarderRefs );
            }
            fprintf( stderr, "\n" );
            NewForwarder = (PIMAGE_BOUND_FORWARDER_REF)(NewImport+1);
            for (i=0; i<NewImport->NumberOfModuleForwarderRefs; i++) 
            {
                fprintf( stderr, "        Forward to %s [%x]\n",
                   (LPSTR)NewImports + NewForwarder->OffsetModuleName,
                   NewForwarder->TimeDateStamp);
                NewForwarder += 1;
            }
            NewImport = (PIMAGE_BOUND_IMPORT_DESCRIPTOR)NewForwarder;
        }
    }
    break;

Requirements

Client

Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation 4.0, Windows Me, Windows 98, or Windows 95.

Server

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

Header

Declared in Imagehlp.h.

See Also

ImageHlp Functions
BindImageEx


Send comments about this topic to Microsoft

Build date: 9/25/2007

© 2007 Microsoft Corporation. All rights reserved.