IDebugHostMemory3::CanonicalizeLocation method (dbgmodel.h)

CanonicalizeLocation is a method that transforms a given ___location to its "canonical representation", which is a chosen standard form. It can handle different types of locations, for example, virtual memory and register, that can be represented in several ways.

A classic example where this function might be helpful involve the Debugging Tools for Windows (dbgeng) that historically sign extends 32-bit addresses to 64-bits, creating difficulties in representing and distinguishing certain address regions in high address aware 32-bit processes.

Note that comparing locations or addresses gotten from components which report sign extended addresses against zero extended ones could result in unforeseen failures. You can evade such mishaps by calling CanonicalizeLocation() beforehand. Keep in mind that this method doesn't transform the type of a ___location. To transform the type, you should call LinearizeLocation().

Syntax

HRESULT CanonicalizeLocation(
  IDebugHostContext *context,
  Location          ___location,
  Location          *pCanonicalizedLocation
);

Parameters

context

The current context.

___location

The ___location you want to canonicalize.

pCanonicalizedLocation

Pointer to where the canonicalized ___location will be stored.

Return value

This method returns HRESULT which indicates success or failure.

Remarks

Although this method changes a ___location's representation to its canonical form, it doesn't alter the actual type of the ___location. Use the LinearizeLocation() method to perform such type transformation.

Requirements

See also

IDebugHostMemory3 interface