Skip to content

Commit 8505b90

Browse files
hmacgregor1hmacgregor1
authored
Merge pull request #3938 from corob-msft/docs/corob/weakref-fix
Reformat WeakRef class document.
2 parents 39f7d57 + b12dea1 commit 8505b90

1 file changed

Lines changed: 89 additions & 91 deletions

File tree

‎docs/cppcx/wrl/weakref-class.md‎

Lines changed: 89 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
---
22
description: "Learn more about: WeakRef Class"
33
title: "WeakRef Class"
4-
ms.date: "10/03/2018"
4+
ms.date: 11/22/2021
55
ms.topic: "reference"
66
f1_keywords: ["client/Microsoft::WRL::WeakRef", "client/Microsoft::WRL::WeakRef::~WeakRef", "client/Microsoft::WRL::WeakRef::As", "client/Microsoft::WRL::WeakRef::AsIID", "client/Microsoft::WRL::WeakRef::CopyTo", "client/Microsoft::WRL::WeakRef::operator&", "client/Microsoft::WRL::WeakRef::WeakRef"]
77
helpviewer_keywords: ["Microsoft::WRL::WeakRef class", "Microsoft::WRL::WeakRef::~WeakRef, destructor", "Microsoft::WRL::WeakRef::As method", "Microsoft::WRL::WeakRef::AsIID method", "Microsoft::WRL::WeakRef::CopyTo method", "Microsoft::WRL::WeakRef::operator& operator", "Microsoft::WRL::WeakRef::WeakRef, constructor"]
8-
ms.assetid: 572be703-c641-496c-8af5-ad6164670ba1
98
---
10-
# WeakRef Class
9+
# `WeakRef` class
1110

1211
Represents a *weak reference* that can be used by only the Windows Runtime, not classic COM. A weak reference represents an object that might or might not be accessible.
1312

@@ -19,26 +18,26 @@ class WeakRef : public ComPtr<IWeakReference>;
1918
2019
## Members
2120
22-
### Public Constructors
21+
### Public constructors
2322
2423
|Name|Description|
2524
|----------|-----------------|
26-
|[WeakRef::WeakRef Constructor](#weakref)|Initializes a new instance of the `WeakRef` class.|
27-
|[WeakRef::~WeakRef Destructor](#tilde-weakref)|Deinitializes the current instance of the `WeakRef` class.|
25+
|[`WeakRef::WeakRef` constructor](#weakref)|Initializes a new instance of the `WeakRef` class.|
26+
|[`WeakRef::~WeakRef` destructor](#tilde-weakref)|Deinitializes the current instance of the `WeakRef` class.|
2827
29-
### Public Methods
28+
### Public methods
3029
3130
|Name|Description|
3231
|----------|-----------------|
33-
|[WeakRef::As Method](#as)|Sets the specified `ComPtr` pointer parameter to represent the specified interface.|
34-
|[WeakRef::AsIID Method](#asiid)|Sets the specified `ComPtr` pointer parameter to represent the specified interface ID.|
35-
|[WeakRef::CopyTo Method](#copyto)|Assigns a pointer to an interface, if available, to the specified pointer variable.|
32+
|[`WeakRef::As`](#as)|Sets the specified `ComPtr` pointer parameter to represent the specified interface.|
33+
|[`WeakRef::AsIID`](#asiid)|Sets the specified `ComPtr` pointer parameter to represent the specified interface ID.|
34+
|[`WeakRef::CopyTo`](#copyto)|Assigns a pointer to an interface, if available, to the specified pointer variable.|
3635
37-
### Public Operators
36+
### Public operators
3837
3938
|Name|Description|
4039
|----------|-----------------|
41-
|[WeakRef::operator& Operator](#operator-ampersand-operator)|Returns a `ComPtrRef` object that represents the current `WeakRef` object.|
40+
|[`WeakRef::operator&`](#operator-ampersand-operator)|Returns a `ComPtrRef` object that represents the current `WeakRef` object.|
4241
4342
## Remarks
4443
@@ -65,7 +64,7 @@ if(wr == nullptr)
6564
}
6665
```
6766

68-
The above code does not work when using the Windows 10 SDK (or later). Instead, check the pointer that was passed in for **`nullptr`**.
67+
The above code doesn't work when using the Windows 10 SDK (or later). Instead, check the pointer that was passed in for **`nullptr`**.
6968

7069
```cpp
7170
if (strongRef == nullptr)
@@ -74,27 +73,62 @@ if (strongRef == nullptr)
7473
}
7574
```
7675

77-
## Inheritance Hierarchy
76+
## Inheritance hierarchy
7877

79-
`ComPtr`
80-
81-
`WeakRef`
78+
[`ComPtr`](comptr-class.md)\
79+
&emsp;└&nbsp;[`WeakRef`](weakref-class.md)
8280

8381
## Requirements
8482

85-
**Header:** client.h
83+
**Header:** *`client.h`*
84+
85+
**Namespace:** `Microsoft::WRL`
86+
87+
## <a name="weakref"></a> `WeakRef::WeakRef` constructor
88+
89+
Initializes a new instance of the `WeakRef` class.
90+
91+
```cpp
92+
WeakRef();
93+
WeakRef(
94+
decltype(__nullptr)
95+
);
96+
97+
WeakRef(
98+
_In_opt_ IWeakReference* ptr
99+
);
100+
101+
WeakRef(
102+
const ComPtr<IWeakReference>& ptr
103+
);
104+
105+
WeakRef(
106+
const WeakRef& ptr
107+
);
108+
109+
WeakRef(
110+
_Inout_ WeakRef&& ptr
111+
);
112+
```
113+
114+
### Parameters
115+
116+
*`ptr`*\
117+
A pointer, reference, or rvalue-reference to an existing object that initializes the current `WeakRef` object.
118+
119+
### Remarks
86120

87-
**Namespace:** Microsoft::WRL
121+
The first constructor initializes an empty `WeakRef` object. The second constructor initializes a `WeakRef` object from a pointer to the `IWeakReference` interface. The third constructor initializes a `WeakRef` object from a reference to a `ComPtr<IWeakReference>` object. The fourth and fifth constructors initialize a `WeakRef` object from another `WeakRef` object.
88122

89-
## <a name="tilde-weakref"></a> WeakRef::~WeakRef Destructor
123+
## <a name="tilde-weakref"></a> `WeakRef::~WeakRef` destructor
90124

91125
Deinitializes the current instance of the `WeakRef` class.
92126

93127
```cpp
94128
~WeakRef();
95129
```
96130

97-
## <a name="as"></a> WeakRef::As Method
131+
## <a name="as"></a> `WeakRef::As`
98132

99133
Sets the specified `ComPtr` pointer parameter to represent the specified interface.
100134

@@ -112,29 +146,29 @@ HRESULT As(
112146

113147
### Parameters
114148

115-
*U*<br/>
149+
*`U`*\
116150
An interface ID.
117151

118-
*ptr*<br/>
152+
*`ptr`*\
119153
When this operation completes, an object that represents parameter *U*.
120154

121-
### Return Value
155+
### Return value
122156

123-
- S_OK if this operation succeeds; otherwise, an HRESULT that indicates the reason the operation failed, and *ptr* is set to **`nullptr`**.
157+
- `S_OK` if this operation succeeds; otherwise, an HRESULT that indicates the reason the operation failed, and *`ptr`* is set to **`nullptr`**.
124158

125-
- S_OK if this operation succeeds, but the current `WeakRef` object has already been released. Parameter *ptr* is set to **`nullptr`**.
159+
- `S_OK` if this operation succeeds, but the current `WeakRef` object has already been released. Parameter *`ptr`* is set to **`nullptr`**.
126160

127-
- S_OK if this operation succeeds, but the current `WeakRef` object is not derived from parameter *U*. Parameter *ptr* is set to **`nullptr`**.
161+
- `S_OK` if this operation succeeds, but the current `WeakRef` object isn't derived from parameter *`U`*. Parameter *`ptr`* is set to **`nullptr`**.
128162

129163
### Remarks
130164

131-
An error is emitted if parameter *U* is `IWeakReference`, or is not derived from `IInspectable`.
165+
An error is emitted if parameter *`U`* is `IWeakReference`, or isn't derived from `IInspectable`.
132166

133-
The first template is the form that you should use in your code. The second template is an internal, helper specialization that supports C++ language features such as the [auto](../../cpp/auto-cpp.md) type deduction keyword.
167+
The first template is the form that you should use in your code. The second template is an internal, helper specialization; it supports C++ language features such as the [`auto`](../../cpp/auto-cpp.md) type deduction keyword.
134168

135-
Starting in the Windows 10 SDK, this method does not set the `WeakRef` instance to **`nullptr`** if the weak reference could not be obtained, so you should avoid error-checking code that checks the `WeakRef` for **`nullptr`**. Instead, check *ptr* for **`nullptr`**.
169+
Starting in the Windows 10 SDK, this method doesn't set the `WeakRef` instance to **`nullptr`** if the weak reference couldn't be obtained, so you should avoid error-checking code that checks the `WeakRef` for **`nullptr`**. Instead, check *ptr* for **`nullptr`**.
136170

137-
## <a name="asiid"></a> WeakRef::AsIID Method
171+
## <a name="asiid"></a> `WeakRef::AsIID`
138172

139173
Sets the specified `ComPtr` pointer parameter to represent the specified interface ID.
140174

@@ -147,29 +181,29 @@ HRESULT AsIID(
147181

148182
### Parameters
149183

150-
*riid*<br/>
184+
*`riid`*\
151185
An interface ID.
152186

153-
*ptr*<br/>
154-
When this operation completes, an object that represents parameter *riid*.
187+
*`ptr`*\
188+
When this operation completes, an object that represents parameter *`riid`*.
155189

156-
### Return Value
190+
### Return value
157191

158-
- S_OK if this operation succeeds; otherwise, an HRESULT that indicates the reason the operation failed, and *ptr* is set to **`nullptr`**.
192+
- `S_OK` if this operation succeeds; otherwise, an HRESULT that indicates the reason the operation failed, and *`ptr`* is set to **`nullptr`**.
159193

160-
- S_OK if this operation succeeds, but the current `WeakRef` object has already been released. Parameter *ptr* is set to **`nullptr`**.
194+
- `S_OK` if this operation succeeds, but the current `WeakRef` object has already been released. Parameter *`ptr`* is set to **`nullptr`**.
161195

162-
- S_OK if this operation succeeds, but the current `WeakRef` object is not derived from parameter *riid*. Parameter *ptr* is set to **`nullptr`**. (For more information, see Remarks.)
196+
- `S_OK` if this operation succeeds, but the current `WeakRef` object isn't derived from parameter *`riid`*. Parameter *`ptr`* is set to **`nullptr`**. (For more information, see Remarks.)
163197

164198
### Remarks
165199

166-
An error is emitted if parameter *riid* is not derived from `IInspectable`. This error supersedes the return value.
200+
An error is emitted if parameter *`riid`* isn't derived from `IInspectable`. This error supersedes the return value.
167201

168-
The first template is the form that you should use in your code. The second template (not shown here, but declared in the header file) is an internal, helper specialization that supports C++ language features such as the [auto](../../cpp/auto-cpp.md) type deduction keyword.
202+
The first template is the form that you should use in your code. The second template (not shown here, but declared in the header file) is an internal, helper specialization that supports C++ language features such as the [`auto`](../../cpp/auto-cpp.md) type deduction keyword.
169203

170-
Starting in the Windows 10 SDK, this method does not set the `WeakRef` instance to **`nullptr`** if the weak reference could not be obtained, so you should avoid error-checking code that checks the `WeakRef` for **`nullptr`**. Instead, check *ptr* for **`nullptr`**.
204+
Starting in the Windows 10 SDK, this method doesn't set the `WeakRef` instance to **`nullptr`** if the weak reference couldn't be obtained, so you should avoid error-checking code that checks the `WeakRef` for **`nullptr`**. Instead, check *`ptr`* for **`nullptr`**.
171205

172-
## <a name="copyto"></a> WeakRef::CopyTo Method
206+
## <a name="copyto"></a> `WeakRef::CopyTo`
173207

174208
Assigns a pointer to an interface, if available, to the specified pointer variable.
175209

@@ -191,73 +225,37 @@ HRESULT CopyTo(
191225

192226
### Parameters
193227

194-
*U*<br/>
195-
Pointer an `IInspectable` interface. An error is emitted if *U* is not derived from `IInspectable`.
228+
*`U`*\
229+
Pointer an `IInspectable` interface. An error is emitted if *`U`* isn't derived from `IInspectable`.
196230

197-
*riid*<br/>
198-
An interface ID. An error is emitted if *riid* is not derived from `IWeakReference`.
231+
*`riid`*\
232+
An interface ID. An error is emitted if *`riid`* isn't derived from `IWeakReference`.
199233

200-
*ptr*<br/>
201-
A doubly-indirect pointer to `IInspectable` or `IWeakReference`.
234+
*`ptr`*\
235+
A doubly indirect pointer to `IInspectable` or `IWeakReference`.
202236

203-
### Return Value
237+
### Return value
204238

205-
S_OK if successful; otherwise, an HRESULT that describes the failure. For more information, see **Remarks**.
239+
`S_OK` if successful; otherwise, an HRESULT that describes the failure. For more information, see **Remarks**.
206240

207241
### Remarks
208242

209-
A return value of S_OK means that this operation succeeded, but doesn't indicate whether the weak reference was resolved to a strong reference. If S_OK is returned, test that parameter *p* is a strong reference; that is, parameter *p* isn't equal to **`nullptr`**.
243+
A return value of `S_OK` means that this operation succeeded, but doesn't indicate whether the weak reference was resolved to a strong reference. If `S_OK` is returned, test that parameter *`ptr`* is a strong reference; that is, parameter *`ptr`* isn't equal to **`nullptr`**.
210244

211-
Starting in the Windows 10 SDK, this method does not set the `WeakRef` instance to **`nullptr`** if the weak reference could not be obtained, so you should avoid error checking code that checks the `WeakRef` for **`nullptr`**. Instead, check *ptr* for **`nullptr`**.
245+
Starting in the Windows 10 SDK, this method doesn't set the `WeakRef` instance to **`nullptr`** if the weak reference couldn't be obtained, so you should avoid error checking code that checks the `WeakRef` for **`nullptr`**. Instead, check *`ptr`* for **`nullptr`**.
212246

213-
## <a name="operator-ampersand-operator"></a> WeakRef::operator& Operator
247+
## <a name="operator-ampersand-operator"></a> `WeakRef::operator&`
214248

215249
Returns a `ComPtrRef` object that represents the current `WeakRef` object.
216250

217251
```cpp
218252
Details::ComPtrRef<WeakRef> operator&() throw()
219253
```
220254

221-
### Return Value
255+
### Return value
222256

223257
A `ComPtrRef` object that represents the current `WeakRef` object.
224258

225259
### Remarks
226260

227-
This is an internal helper operator that is not meant to be used in your code.
228-
229-
## <a name="weakref"></a> WeakRef::WeakRef Constructor
230-
231-
Initializes a new instance of the `WeakRef` class.
232-
233-
```cpp
234-
WeakRef();
235-
WeakRef(
236-
decltype(__nullptr)
237-
);
238-
239-
WeakRef(
240-
_In_opt_ IWeakReference* ptr
241-
);
242-
243-
WeakRef(
244-
const ComPtr<IWeakReference>& ptr
245-
);
246-
247-
WeakRef(
248-
const WeakRef& ptr
249-
);
250-
251-
WeakRef(
252-
_Inout_ WeakRef&& ptr
253-
);
254-
```
255-
256-
### Parameters
257-
258-
*ptr*<br/>
259-
A pointer, reference, or rvalue-reference to an existing object that initializes the current `WeakRef` object.
260-
261-
### Remarks
262-
263-
The first constructor initializes an empty `WeakRef` object. The second constructor initializes a `WeakRef` object from a pointer to the `IWeakReference` interface. The third constructor initializes a `WeakRef` object from a reference to a `ComPtr<IWeakReference>` object. The fourth and fifth constructors initializes a `WeakRef` object from another `WeakRef` object.
261+
`WeakRef::operator&` is an internal helper operator that's not meant to be used in your code.

0 commit comments

Comments
 (0)