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

See Also

ImageHlp Functions
BindImageEx

Send comments about this topic to Microsoft

Build date: 9/25/2007