Skip to content

Commit 0b1aeed

Browse files
committed
1769497, fixed duplicate headings.
1 parent ec11780 commit 0b1aeed

20 files changed

Lines changed: 60 additions & 74 deletions

‎docs/cpp/how-to-create-and-use-ccomptr-and-ccomqiptr-instances.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,21 +11,21 @@ In classic Windows programming, libraries are often implemented as COM objects (
1111

1212
When you instantiate a Component Object Model (COM) object, store the interface pointer in a COM smart pointer, which performs the reference counting by using calls to `AddRef` and `Release` in the destructor. If you are using the Active Template Library (ATL) or the Microsoft Foundation Class Library (MFC), then use the `CComPtr` smart pointer. If you are not using ATL or MFC, then use `_com_ptr_t`. Because there is no COM equivalent to `std::unique_ptr`, use these smart pointers for both single-owner and multiple-owner scenarios. Both `CComPtr` and `ComQIPtr` support move operations that have rvalue references.
1313

14-
## Example
14+
## Example using CComPtr
1515

1616
The following example shows how to use `CComPtr` to instantiate a COM object and obtain pointers to its interfaces. Notice that the `CComPtr::CoCreateInstance` member function is used to create the COM object, instead of the Win32 function that has the same name.
1717

1818
[!code-cpp[COM_smart_pointers#01](../cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_1.cpp)]
1919

2020
`CComPtr` and its relatives are part of the ATL and are defined in \<atlcomcli.h>. `_com_ptr_t` is declared in \<comip.h>. The compiler creates specializations of `_com_ptr_t` when it generates wrapper classes for type libraries.
2121

22-
## Example
22+
## Example using CComQIPt
2323

2424
ATL also provides `CComQIPtr`, which has a simpler syntax for querying a COM object to retrieve an additional interface. However, we recommend `CComPtr` because it does everything that `CComQIPtr` can do and is semantically more consistent with raw COM interface pointers. If you use a `CComPtr` to query for an interface, the new interface pointer is placed in an out parameter. If the call fails, an HRESULT is returned, which is the typical COM pattern. With `CComQIPtr`, the return value is the pointer itself, and if the call fails, the internal HRESULT return value cannot be accessed. The following two lines show how the error handling mechanisms in `CComPtr` and `CComQIPtr` differ.
2525

2626
[!code-cpp[COM_smart_pointers#02](../cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_2.cpp)]
2727

28-
## Example
28+
## Example using IDispatch
2929

3030
`CComPtr` provides a specialization for IDispatch that enables it to store pointers to COM automation components and invoke the methods on the interface by using late binding. `CComDispatchDriver` is a typedef for `CComQIPtr<IDispatch, &IIDIDispatch>`, which is implicitly convertible to `CComPtr<IDispatch>`. Therefore, when any of these three names appears in code, it is equivalent to `CComPtr<IDispatch>`. The following example shows how to obtain a pointer to the Microsoft Word object model by using a `CComPtr<IDispatch>`.
3131

‎docs/dotnet/debug-class-cpp-cli.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ When using <xref:System.Diagnostics.Debug> in a Visual C++ application, the beha
1212

1313
The behavior for <xref:System.Diagnostics.Trace> is identical to the behavior for the Debug class, but is dependent on the symbol TRACE being defined. This means that you must `#ifdef` any Trace-related code to prevent debug behavior in a release build.
1414

15-
## Example
15+
## Example that always executes the output statements
1616

1717
### Description
1818

@@ -49,7 +49,7 @@ Hello World.
4949
test
5050
```
5151

52-
## Example
52+
## Example using the #ifdef and #endif directives
5353

5454
### Description
5555

‎docs/dotnet/double-thunking-cpp.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Similarly, if you export ([dllexport, dllimport](../cpp/dllexport-dllimport.md))
1818

1919
The compiler has been updated to reduce unnecessary double thunking. For example, any function with a managed type in the signature (including return type) will implicitly be marked as `__clrcall`.
2020

21-
## Example
21+
## Example of double thunking
2222

2323
### Description
2424

@@ -76,7 +76,7 @@ after calling struct S
7676
__thiscall T::~T(void)
7777
```
7878
79-
## Example
79+
## Example of the effect of double thunking
8080
8181
### Description
8282

‎docs/dotnet/how-to-declare-override-specifiers-in-native-compilations-cpp-cli.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ ms.assetid: d0551836-9ac7-41eb-a6e9-a4b3ef60767d
1111
> [!NOTE]
1212
> The ISO C++11 Standard language has the [override](../cpp/override-specifier.md) identifier and the [final](../cpp/final-specifier.md) identifier, and both are supported in Visual Studio Use `final` instead of **`sealed`** in code that is meant to be compiled as native-only.
1313
14-
## Example
14+
## Example showing sealed is valid
1515

1616
### Description
1717

@@ -40,7 +40,7 @@ public:
4040
};
4141
```
4242
43-
## Example
43+
## Example showing override is valid
4444
4545
### Description
4646
@@ -62,7 +62,7 @@ public:
6262
};
6363
```
6464

65-
## Example
65+
## Example showing that abstract is valid
6666

6767
### Description
6868

‎docs/dotnet/how-to-extend-the-marshaling-library.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ namespace msclr {
9595
}
9696
```
9797

98-
## Example
98+
## Example extending the marshaling library
9999

100100
The following example extends the marshaling library with a conversion that does not require a context. In this example, the code converts the employee information from a native data type to a managed data type.
101101

@@ -157,7 +157,7 @@ Managed address: 123 Main Street
157157
Managed zip code: 98111
158158
```
159159

160-
## Example
160+
## Example converting the employee information
161161

162162
The following example converts the employee information from a managed data type to a native data type. This conversion requires a marshaling context.
163163

‎docs/dotnet/how-to-marshal-ansi-strings-using-cpp-interop.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ This topic demonstrates how ANSI strings can be passed using C++ Interop, but th
1515

1616
The following code examples use the [managed, unmanaged](../preprocessor/managed-unmanaged.md) #pragma directives to implement managed and unmanaged functions in the same file, but these functions interoperate in the same manner if defined in separate files. Because files containing only unmanaged functions do not need to be compiled with [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md), they can retain their performance characteristics.
1717

18-
## Example
18+
## Example passing an ANSI string
1919

2020
The example demonstrates passing an ANSI string from a managed to an unmanaged function using <xref:System.Runtime.InteropServices.Marshal.StringToHGlobalAnsi%2A>. This method allocates memory on the unmanaged heap and returns the address after performing the conversion. This means that no pinning is necessary (because memory on the GC heap is not being passed to the unmanaged function) and that the IntPtr returned from <xref:System.Runtime.InteropServices.Marshal.StringToHGlobalAnsi%2A> must be explicitly released or a memory leak results.
2121

@@ -49,7 +49,7 @@ int main() {
4949
}
5050
```
5151
52-
## Example
52+
## Example of data marshaling required to access an ANSI string
5353
5454
The following example demonstrates the data marshaling required to access an ANSI string in a managed function that is called by an unmanaged function. The managed function, on receiving the native string, can either use it directly or convert it to a managed string using the <xref:System.Runtime.InteropServices.Marshal.PtrToStringAnsi%2A> method, as shown.
5555

‎docs/dotnet/how-to-marshal-arrays-using-cpp-interop.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This topic demonstrates one facet of Visual C++ interoperability. For more infor
1111

1212
The following code examples use the [managed, unmanaged](../preprocessor/managed-unmanaged.md) #pragma directives to implement managed and unmanaged functions in the same file, but these functions interoperate in the same manner if defined in separate files. Files containing only unmanaged functions do not need to be compiled with [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md).
1313

14-
## Example
14+
## Example passing a managed array to an unmanaged function
1515

1616
The following example demonstrates how to pass a managed array to an unmanaged function. The managed function uses [pin_ptr (C++/CLI)](../extensions/pin-ptr-cpp-cli.md) to suppress garbage collection for the array before calling the unmanaged function. By providing the unmanaged function with a pinned pointer into the GC heap, the overhead of making a copy of the array can be avoided. To demonstrate that the unmanaged function is accessing GC heap memory, it modifies the contents of the array and the changes are reflected when the managed function resumes control.
1717

@@ -70,7 +70,7 @@ int main() {
7070
}
7171
```
7272
73-
## Example
73+
## Example passing an unmanaged array to a managed function
7474
7575
The following example demonstrates passing an unmanaged array to a managed function. The managed function accesses the array memory directly (as opposed to creating a managed array and copying the array content), which allows changes made by the managed function to be reflected in the unmanaged function when it regains control.
7676

‎docs/dotnet/how-to-marshal-callbacks-and-delegates-by-using-cpp-interop.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This topic demonstrates the marshalling of callbacks and delegates (the managed
1111

1212
The following code examples use the [managed, unmanaged](../preprocessor/managed-unmanaged.md) #pragma directives to implement managed and unmanaged functions in the same file, but the functions could also be defined in separate files. Files containing only unmanaged functions do not need to be compiled with the [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md).
1313

14-
## Example
14+
## Example configuring an unmanaged API to trigger a managed delegate
1515

1616
The following example demonstrates how to configure an unmanaged API to trigger a managed delegate. A managed delegate is created and one of the interop methods, <xref:System.Runtime.InteropServices.Marshal.GetFunctionPointerForDelegate%2A>, is used to retrieve the underlying entry point for the delegate. This address is then passed to the unmanaged function, which calls it with no knowledge of the fact that it is implemented as a managed function.
1717

@@ -65,7 +65,7 @@ int main() {
6565
}
6666
```
6767
68-
## Example
68+
## Example with the function pointer stored by the unmanaged API
6969
7070
The following example is similar to the previous example, but in this case the provided function pointer is stored by the unmanaged API, so it can be invoked at any time, requiring that garbage collection be suppressed for an arbitrary length of time. As a result, the following example uses a global instance of <xref:System.Runtime.InteropServices.GCHandle> to prevent the delegate from being relocated, independent of function scope. As discussed in the first example, using pin_ptr is unnecessary for these examples, but in this case wouldn't work anyway, as the scope of a pin_ptr is limited to a single function.
7171

‎docs/dotnet/how-to-marshal-com-strings-using-cpp-interop.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ This topic demonstrates how a BSTR (the basic string format favored in COM progr
1515

1616
The following code examples use the [managed, unmanaged](../preprocessor/managed-unmanaged.md) #pragma directives to implement managed and unmanaged functions in the same file, but these functions interoperate in the same manner if defined in separate files. Files containing only unmanaged functions do not need to be compiled with [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md).
1717

18-
## Example
18+
## Example passing a BSTR from a managed to an unmanaged function
1919

2020
The following example demonstrates how a BSTR (a string format used in COM programming) can be passed from a managed to an unmanaged function. The calling managed function uses <xref:System.Runtime.InteropServices.Marshal.StringToBSTR%2A> to obtain the address of a BSTR representation of the contents of a .NET System.String. This pointer is pinned using [pin_ptr (C++/CLI)](../extensions/pin-ptr-cpp-cli.md) to ensure that its physical address is not changed during a garbage collection cycle while the unmanaged function executes. The garbage collector is prohibited from moving the memory until the [pin_ptr (C++/CLI)](../extensions/pin-ptr-cpp-cli.md) goes out of scope.
2121

@@ -52,7 +52,7 @@ int main() {
5252
}
5353
```
5454
55-
## Example
55+
## Example passing a BSTR from a an unmanaged to a managed function
5656
5757
The following example demonstrates how a BSTR can be passed from an unmanaged to an unmanaged function. The receiving managed function can either use the string in as a BSTR or use <xref:System.Runtime.InteropServices.Marshal.PtrToStringBSTR%2A> to convert it to a <xref:System.String> for use with other managed functions. Because the memory representing the BSTR is allocated on the unmanaged heap, no pinning is necessary, because there is no garbage collection on the unmanaged heap.
5858

‎docs/dotnet/how-to-marshal-structures-using-cpp-interop.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This topic demonstrates one facet of Visual C++ interoperability. For more infor
1111

1212
The following code examples use the [managed, unmanaged](../preprocessor/managed-unmanaged.md) #pragma directives to implement managed and unmanaged functions in the same file, but these functions interoperate in the same manner if defined in separate files. Files containing only unmanaged functions do not need to be compiled with [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md).
1313

14-
## Example
14+
## Example passing a structure from a managed to an unmanaged function
1515

1616
The following example demonstrates passing a structure from a managed to an unmanaged function, both by value and by reference. Because the structure in this example contains only simple, intrinsic data types (see [Blittable and Non-Blittable Types](/dotnet/framework/interop/blittable-and-non-blittable-types)), no special marshaling is required. To marshal non-blittable structures, such as those that contain pointers, see [How to: Marshal Embedded Pointers Using C++ Interop](../dotnet/how-to-marshal-embedded-pointers-using-cpp-interop.md).
1717

@@ -69,7 +69,7 @@ int main() {
6969
}
7070
```
7171
72-
## Example
72+
## Example passing a structure from an unmanaged to a managed function
7373
7474
The following example demonstrates passing a structure from an unmanaged to a managed function, both by value and by reference. Because the structure in this example contains only simple, intrinsic data types (see [Blittable and Non-Blittable Types](/dotnet/framework/interop/blittable-and-non-blittable-types)), no special marshalling is required. To marshal non-blittable structures, such as those that contain pointers, see [How to: Marshal Embedded Pointers Using C++ Interop](../dotnet/how-to-marshal-embedded-pointers-using-cpp-interop.md).
7575

0 commit comments

Comments
 (0)