NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

returnshresult

Marks a method or property as adhering to COM calling conventions rather than NGWS calling conventions.

[returnshresult(value)]

Applies To

Method and property declarations.

Parameters

value
A bool; if true, the method or property follows COM calling conventions; if false, it follows NGWS calling conventions.

Remarks

returnshresult is a single-use attribute. returnshresult is an alias for System.InterOp.ReturnsHResultAttribute.

Typically, an unmanaged COM interface method returns an HRESULT indicating success or failure, and returns its actual result through a parameter. In contrast, the return value of a NGWS method is its actual result, and errors are reported through exceptions. The returnshresult attribute maps the COM calling convention to the NGWS convention.

For example, a COM method might be declared as follows (in MIDL):

interface IExample {
   HRESULT ComputeSquareRoot([in]double x, [out,retval]double *result);
}

The real return value is the last parameter of the method, which is marked with the out and retval attributes in the MIDL interface definition.

A literal translation to C# would look like this:

interface IExample {
   HRESULT ComputeSquareRoot(double x, out double returnValue);
}

An invocation of the method might look like this:

double y;
// assume exampleObj is an object that implements IExample
HRESULT hr = exampleObj.ComputeSquareRoot(5.0, out y);
if (hr != 0) throw new COMInteropException(hr);
// do something with y

However, the same ends can be achieved much more concisely by declaring the method to have the returnshresult attribute:

interface IExample {
   [returnshresult(true)] double ComputeSquareRoot(double x);
}

Then invoking the method becomes simply

// assume exampleObj as above
double y = exampleObj.ComputeSquareRoot(5.0);

Declaring the method as returning a double more accurately reflects its purpose; the fact that it is actually a COM method returning an HRESULT is hidden. Code is automatically inserted to check the return code and raise an exception if necessary.

Non-static methods have an implicit returnshresult(true) attribute, and static methods have an implicit returnshresult(false) attribute. In the context of interoperability with unmanaged code, non-static methods correspond to COM interface methods, so the implicit returnshresult(true) attribute is appropriate because most COM methods return an HRESULT. Static methods correspond to externally implemented dllimport methods, which typically do not return an HRESULT. In both cases the default is almost always correct, but you can override it by specifying an explicit returnshresult attribute. Outside the context of interoperability, returnshresult has absolutely no effect.

See Also

C# Attributes