Překlady implicitních podpisů metod v rámci interoperability .NET

Aby byl systém jazykově nezávislý, systém Windows COM a mnoho rozhraní API systému Windows vrátí 4 bajtový celočíselný typ, který HRESULT udává, zda bylo volání API úspěšné či nikoliv, spolu s některými informacemi o selhání. Další hodnoty, které je třeba volajícímu předat, jsou "vráceny" prostřednictvím parametrů ukazatele, které fungují jako "out" parametry a obvykle jsou posledním parametrem v podpisu. Jazyky, jako je C# a Visual Basic, tradičně překládají kód selhání na výjimku, aby odpovídaly způsobu šíření selhání v jazyce a očekávají, že podpisy metod vzájemné spolupráce nezahrnou HRESULT. Pokud chcete přeložit podpis metody na nativní podpis, runtime přesune návratovou hodnotu metody do dalšího parametru "out" s dalším stupněm nepřímosti (jinými slovy, vytvoří ukazatel na návratový typ spravovaného podpisu) a předpokládá návratovou hodnotu HRESULT. Pokud spravovaná metoda vrátí void, žádný další parametr se nepřidá a návratová hodnota se změní na HRESULT. Podívejte se například na následující dvě metody modelu COM jazyka C#, které se překládají na stejný nativní podpis:

int Add(int a, int b);

void Add(int a, int b, out int sum);

HRESULT Add(int a, int b, /* out */ int* sum);

PreserveSig v modelu COM

Očekává se, že všechny metody COM v jazyce C# budou ve výchozím nastavení používat přeloženou signaturu. Chcete-li používat a exportovat metody bez překladu podpisu a zpracování hodnot HRESULT, přidejte PreserveSigAttribute k metodě rozhraní COM. Při aplikaci atributu na metodu nedochází ke změně podpisu a nejsou vyvolávány výjimky pro neúspěšné hodnoty HRESULT. To platí pro vestavěné COM i zdrojově generované COM. Podívejte se například na následující podpis metody jazyka C# s atributem PreserveSig a odpovídajícím nativním podpisem.

[PreserveSig]
int Add(int a, int b, out int sum);

HRESULT Add(int a, int b, int* sum);

To může být užitečné, pokud metoda může vrátit různé HRESULT hodnoty, které nejsou selhání, ale musí se zpracovat jinak. Některé metody můžou například vrátit hodnotu S_FALSE , když metoda selže, ale vrátí pouze částečné výsledky a S_OK když vrátí všechny výsledky.

PreserveSig s P/Invokes

Atribut DllImportAttribute má také pole bool PreserveSig, které funguje podobně jako PreserveSigAttribute, ale jeho výchozí hodnota je true. Chcete-li označit, že modul runtime by měl přeložit spravovaný podpis a zpracovat vrácený HRESULT podpis, nastavte PreserveSig pole na false hodnotu v objektu DllImportAttribute. Podívejte se například na následující podpisy dvou P/Invoke volání ke stejné nativní metodě: jedno, kde je PreserveSig nastaveno na false, a druhé, u které je ponechána výchozí hodnota true.

[DllImport("shlwapi.dll", EntryPoint = "SHAutoComplete", ExactSpelling = true, PreserveSig = false)]
public static extern void SHAutoComplete(IntPtr hwndEdit, SHAutoCompleteFlags dwFlags);

[DllImport("shlwapi.dll", EntryPoint = "SHAutoComplete", ExactSpelling = true)]
public static extern int SHAutoCompleteHRESULT(IntPtr hwndEdit, SHAutoCompleteFlags dwFlags);

Poznámka:

Zdrojově generované P/Invokes, které používají LibraryImportAttribute, nemají žádné PreserveSig pole. Vygenerovaný kód vždy předpokládá, že nativní a spravovaný podpis jsou identické. Další informace naleznete v tématu Automaticky generované P/Invokes.

Ruční zpracování HRESULT hodnot

Při volání PreserveSig metody, která vrací HRESULT, můžete použít metodu ThrowExceptionForHR k vyvolání odpovídající výjimky, pokud HRESULT indikuje selhání. Podobně při implementaci PreserveSig metody můžete použít metodu GetHRForException k vrácení HRESULT , která označuje odpovídající hodnotu výjimky.

Mapování HRESULT jako struktury

Při použití metody PreserveSig se očekává, že int je spravovaným typem pro HRESULT. Použití vlastní 4bajtové struktury jako návratová hodnota vám umožňuje definovat metody a vlastnosti, které mohou zjednodušit práci s HRESULT. V integrovaném marshallingu to funguje automaticky. Chcete-li použít strukturu int jako spravovanou reprezentaci HRESULT v zařazování generovaném ze zdroje, přidejte atribut MarshalAsAttribute s argumentem Error. Přítomnost tohoto atributu reinterpretuje bity objektu HRESULT jako strukturu.

Viz také

  • Last updated on