From 036b65682b472032f6de4ef188e356614aaefd34 Mon Sep 17 00:00:00 2001 From: Taojunshen Date: Wed, 24 Nov 2021 02:34:40 +0800 Subject: [PATCH 1/3] 11/23/2021 AM Publish (#3940) * Add gray border * LinkFix: cpp-docs-pr (2021-11) * Clarify C4146 per VCSig list (#3923) * Clarify C4146 per VCSig list * Fix link issues. * Update enable CMake Presets * fix rel links * fix github 3528 * acrolinx * change order of example * Add version info to NMAKE macro functions * Bulk fix entity `&` part 3 * threshhold test * Eliminate even more `&` entities * Minimum Viable Phix * Once more into the `&` breech * Add Visual Studio 2022 Platform Toolset Version * Add /fpcvt compiler option docs (#3886) * Add /fpcvt compiler option docs * Fix copypasta error * Update fp conversion intrinsics, too. * Replace deleted table row * Acrolinx pass * Fix TOC issues * Add useful links to intrinsics * Updates per John Morgan, plus acrolink * Update version info * Clean up rvalue reference article * Fix to `/fpcvt` per John Morgan email * Reformat WeakRef class document. * Minimizing entity form of & (#3916) * Initial pass minimizing on > entities (#3919) * Initial pass on > entities * Fix everything. * Try without `<` entities in title/desc * Clean up pass * Update docs/atl-mfc-shared/reference/cfiletime-class.md Co-authored-by: Tracey Torble Co-authored-by: Erika Co-authored-by: opbld16 Co-authored-by: Colin Robertson Co-authored-by: opbld17 Co-authored-by: Christopher McClister Co-authored-by: PRMerger16 Co-authored-by: Laura Brenner <90344170+laurabren@users.noreply.github.com> Co-authored-by: opbld15 Co-authored-by: TylerMSFT Co-authored-by: PRMerger18 Co-authored-by: PRMerger4 Co-authored-by: PRMerger6 Co-authored-by: MohammadHadi Attarieh Co-authored-by: PRMerger15 Co-authored-by: PRMerger10 Co-authored-by: Haig MacGregor <92189915+hmacgregor1@users.noreply.github.com> Co-authored-by: Tracey Torble --- docs/assembler/masm/operator-bitwise-and.md | 12 +- ...operator-greater-or-equal-masm-run-time.md | 12 +- .../operator-greater-than-masm-run-time.md | 12 +- docs/assembler/masm/operator-literal.md | 10 +- .../operator-logical-and-masm-run-time.md | 10 +- .../reference/cfiletime-class.md | 306 +++++++------- .../reference/cfiletimespan-class.md | 114 +++--- docs/atl/reference/cautoptr-class.md | 128 +++--- docs/atl/reference/ccomcurrency-class.md | 374 ++++++++--------- docs/atl/reference/ccomptrbase-class.md | 248 ++++++------ docs/atl/reference/ccomvariant-class.md | 361 +++++++++-------- docs/atl/reference/cheapptrbase-class.md | 128 +++--- docs/atl/reference/cpatht-class.md | 8 +- docs/atl/reference/csid-class.md | 382 +++++++++--------- ...e-target-framework-and-platform-toolset.md | 1 + docs/build/reference/c-visual-cpp.md | 20 +- docs/build/reference/code-visual-cpp.md | 27 +- docs/build/reference/example-visual-cpp.md | 18 +- docs/build/reference/exception-visual-cpp.md | 28 +- docs/build/reference/fpcvt.md | 2 +- docs/build/reference/include-visual-cpp.md | 38 +- docs/cpp/address-of-operator-amp.md | 23 +- docs/cpp/bitwise-and-operator-amp.md | 14 +- docs/cpp/logical-and-operator-amp-amp.md | 10 +- docs/cpp/lvalue-reference-declarator-amp.md | 21 +- .../rvalue-reference-declarator-amp-amp.md | 65 ++- docs/cppcx/wrl/weakref-class.md | 180 ++++----- docs/data/oledb/cdataconnection-class.md | 82 ++-- .../concurrency-namespace-operators.md | 4 +- 29 files changed, 1322 insertions(+), 1316 deletions(-) diff --git a/docs/assembler/masm/operator-bitwise-and.md b/docs/assembler/masm/operator-bitwise-and.md index 7b72004c778..1f902919245 100644 --- a/docs/assembler/masm/operator-bitwise-and.md +++ b/docs/assembler/masm/operator-bitwise-and.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator &" +description: "Learn more about: Microsoft Assembler (MASM) operator &" title: "operator &" ms.date: "12/17/2019" f1_keywords: ["&", "operator &"] helpviewer_keywords: ["& operator, syntax", "AND operator", "& operator"] ms.assetid: f3c51a54-48ba-4b99-afed-5c45177bf694 --- -# operator `&` +# operator `&` (MASM) -Bitwise **AND**. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. +Bitwise **AND**. Used only within [`.IF`](dot-if.md), [`.WHILE`](dot-while.md), or [`.REPEAT`](dot-repeat.md) blocks and evaluated at run time, not at assembly time. ## Syntax -> *expression1* **&** *expression2* +> *expression1* **`&`** *expression2* ## See also -[Operators Reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[Operators reference](operators-reference.md)\ +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/operator-greater-or-equal-masm-run-time.md b/docs/assembler/masm/operator-greater-or-equal-masm-run-time.md index 1c6a7f8f64e..15190e74d60 100644 --- a/docs/assembler/masm/operator-greater-or-equal-masm-run-time.md +++ b/docs/assembler/masm/operator-greater-or-equal-masm-run-time.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator >= (MASM Run Time)" -title: "operator >= (MASM Run Time)" +description: "Learn more about: Microsoft Assembler operator >= (MASM runtime)" +title: "MASM perator >= (runtime)" ms.date: "12/17/2019" f1_keywords: ["operator >="] helpviewer_keywords: [">= operator, comparing specific objects", "operator >="] ms.assetid: c7366d99-f7b8-4eb8-b5df-6dc74491b114 --- -# operator >= (MASM Run Time) +# operator `>=` (MASM runtime) -Is greater than or equal to. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. +Greater than or equal to operator. Used only within [`.IF`](dot-if.md), [`.WHILE`](dot-while.md), or [`.REPEAT`](dot-repeat.md) blocks and evaluated at runtime, not at assembly time. ## Syntax -> *expression1* **>=** *expression2* +> *expression1* **`>=`** *expression2* ## See also [Operators reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/operator-greater-than-masm-run-time.md b/docs/assembler/masm/operator-greater-than-masm-run-time.md index b1eab87a53a..01d8c629e52 100644 --- a/docs/assembler/masm/operator-greater-than-masm-run-time.md +++ b/docs/assembler/masm/operator-greater-than-masm-run-time.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator > (MASM Run Time)" -title: "operator > (MASM Run Time)" +description: "Learn more about: Microsoft Assembler (MASM) operator > (MASM runtime)" +title: "MASM operator > (runtime)" ms.date: "12/17/2019" f1_keywords: ["operator >"] helpviewer_keywords: ["> operator, comparing specific objects", "operator >"] ms.assetid: f2244900-8ddf-4e8c-9ab0-68b9118a6f75 --- -# operator > (MASM Run Time) +# operator `>` (MASM runtime) -Is greater than. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. +Greater than operator. Used only within [`.IF`](dot-if.md), [`.WHILE`](dot-while.md), or [`.REPEAT`](dot-repeat.md) blocks and evaluated at run time, not at assembly time. ## Syntax -> *expression1* **>** *expression2* +> *expression1* **`>`** *expression2* ## See also [Operators reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/operator-literal.md b/docs/assembler/masm/operator-literal.md index 80c0b5b63ab..2eec9296734 100644 --- a/docs/assembler/masm/operator-literal.md +++ b/docs/assembler/masm/operator-literal.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator <>" -title: "operator <>" +description: "Learn more about: Microsoft Assembler (MASM) operator <>" +title: "MASM operator <>" ms.date: "12/17/2019" f1_keywords: ["<>", "operator <>"] helpviewer_keywords: ["operator <>", "<> operator"] ms.assetid: bc5acf43-df3e-499b-a3ed-1672cfa0d1ed --- -# operator <> +# MASM operator `<>` Treats *text* as a single literal element. ## Syntax -> __\<__*text*__>__ +> __`<`__*text*__`>`__ ## See also [Operators reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/operator-logical-and-masm-run-time.md b/docs/assembler/masm/operator-logical-and-masm-run-time.md index 9e196ac1917..856cde6ca77 100644 --- a/docs/assembler/masm/operator-logical-and-masm-run-time.md +++ b/docs/assembler/masm/operator-logical-and-masm-run-time.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator && (MASM Run Time)" +description: "Learn more about: Microsoft Assembler (MASM) operator && (MASM runtime)" title: "operator && (MASM Run Time)" ms.date: "12/17/2019" f1_keywords: ["operator &&"] helpviewer_keywords: ["operator &&", "&& operator"] ms.assetid: 0a633a40-114c-48f5-88ff-09bc8d9b281a --- -# operator `&&` (MASM Run Time) +# operator `&&` (MASM runtime) -Logical **AND**. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. +Logical **AND**. Used only within [`.IF`](dot-if.md), [`.WHILE`](dot-while.md), or [`.REPEAT`](dot-repeat.md) blocks and evaluated at runtime, not at assembly time. ## Syntax -> *expression1* **&&** *expression2* +> *expression1* **`&&`** *expression2* ## See also [Operators reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/atl-mfc-shared/reference/cfiletime-class.md b/docs/atl-mfc-shared/reference/cfiletime-class.md index da4732a8528..35d7d8dc48e 100644 --- a/docs/atl-mfc-shared/reference/cfiletime-class.md +++ b/docs/atl-mfc-shared/reference/cfiletime-class.md @@ -1,100 +1,100 @@ --- -description: "Learn more about: CFileTime Class" -title: "CFileTime Class" +description: "Learn more about: CFileTime class" +title: "CFileTime class" ms.date: "10/18/2018" f1_keywords: ["CFileTime", "ATLTIME/ATL::CFileTime", "ATLTIME/ATL::CFileTime::CFileTime", "ATLTIME/ATL::CFileTime::GetCurrentTime", "ATLTIME/ATL::CFileTime::GetTime", "ATLTIME/ATL::CFileTime::LocalToUTC", "ATLTIME/ATL::CFileTime::SetTime", "ATLTIME/ATL::CFileTime::UTCToLocal", "ATLTIME/ATL::CFileTime::Day", "ATLTIME/ATL::CFileTime::Hour", "ATLTIME/ATL::CFileTime::Millisecond", "ATLTIME/ATL::CFileTime::Minute", "ATLTIME/ATL::CFileTime::Second", "ATLTIME/ATL::CFileTime::Week"] helpviewer_keywords: ["CFileTime class", "shared classes, CFileTime"] ms.assetid: 1a358a65-1383-4124-b0d4-59b026e6860f --- -# CFileTime Class +# `CFileTime` class This class provides methods for managing the date and time values associated with a file. ## Syntax -``` +```cpp class CFileTime : public FILETIME ``` ## Members -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[CFileTime::CFileTime](#cfiletime)|The constructor.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[CFileTime::GetCurrentTime](#getcurrenttime)|Call this static function to retrieve a `CFileTime` object that represents the current system date and time.| -|[CFileTime::GetTime](#gettime)|Call this method to retrieve the time from the `CFileTime` object.| -|[CFileTime::LocalToUTC](#localtoutc)|Call this method to convert a local file time to a file time based on the Coordinated Universal Time (UTC).| -|[CFileTime::SetTime](#settime)|Call this method to set the date and time stored by the `CFileTime` object.| -|[CFileTime::UTCToLocal](#utctolocal)|Call this method to convert time based on the Coordinated Universal Time (UTC) to local file time.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[CFileTime::operator -](#operator_-)|This operator is used to perform subtraction on a `CFileTime` or `CFileTimeSpan` object.| -|[CFileTime::operator !=](#operator_neq)|This operator compares two `CFileTime` objects for inequality.| -|[CFileTime::operator +](#operator_add)|This operator is used to perform addition on a `CFileTimeSpan` object.| -|[CFileTime::operator +=](#operator_add_eq)|This operator is used to perform addition on a `CFileTimeSpan` object and assign the result to the current object.| -|[CFileTime::operator <](#operator_lt)|This operator compares two `CFileTime` objects to determine the lesser.| -|[CFileTime::operator <=](#operator_lt_eq)|This operator compares two `CFileTime` objects to determine equality or the lesser.| -|[CFileTime::operator =](#operator_eq)|The assignment operator.| -|[CFileTime::operator -=](#operator_-_eq)|This operator is used to perform subtraction on a `CFileTimeSpan` object and assign the result to the current object.| -|[CFileTime::operator ==](#operator_eq_eq)|This operator compares two `CFileTime` objects for equality.| -|[CFileTime::operator >](#operator_gt)|This operator compares two `CFileTime` objects to determine the larger.| -|[CFileTime::operator >=](#operator_gt_eq)|This operator compares two `CFileTime` objects to determine equality or the larger.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[CFileTime::Day](#day)|A static data member storing the number of 100-nanosecond intervals that make up one day.| -|[CFileTime::Hour](#hour)|A static data member storing the number of 100-nanosecond intervals that make up one hour.| -|[CFileTime::Millisecond](#millisecond)|A static data member storing the number of 100-nanosecond intervals that make up one millisecond.| -|[CFileTime::Minute](#minute)|A static data member storing the number of 100-nanosecond intervals that make up one minute.| -|[CFileTime::Second](#second)|A static data member storing the number of 100-nanosecond intervals that make up one second.| -|[CFileTime::Week](#week)|A static data member storing the number of 100-nanosecond intervals that make up one week.| +### Public constructors + +| Name | Description | +|--|--| +| [`CFileTime::CFileTime`](#cfiletime) | The constructor. | + +### Public methods + +| Name | Description | +|--|--| +| [`CFileTime::GetCurrentTime`](#getcurrenttime) | Call this static function to retrieve a `CFileTime` object that represents the current system date and time. | +| [`CFileTime::GetTime`](#gettime) | Call this method to retrieve the time from the `CFileTime` object. | +| [`CFileTime::LocalToUTC`](#localtoutc) | Call this method to convert a local file time to a file time based on the Coordinated Universal Time (UTC). | +| [`CFileTime::SetTime`](#settime) | Call this method to set the date and time stored by the `CFileTime` object. | +| [`CFileTime::UTCToLocal`](#utctolocal) | Call this method to convert time based on the Coordinated Universal Time (UTC) to local file time. | + +### Public operators + +| Name | Description | +|--|--| +| [`CFileTime::operator -`](#operator_-) | This operator is used to perform subtraction on a `CFileTime` or `CFileTimeSpan` object. | +| [`CFileTime::operator !=`](#operator_neq) | This operator compares two `CFileTime` objects for inequality. | +| [`CFileTime::operator +`](#operator_add) | This operator is used to perform addition on a `CFileTimeSpan` object. | +| [`CFileTime::operator +=`](#operator_add_eq) | This operator is used to perform addition on a `CFileTimeSpan` object and assign the result to the current object. | +| [`CFileTime::operator <`](#operator_lt) | This operator compares two `CFileTime` objects to determine the lesser. | +| [`CFileTime::operator <=`](#operator_lt_eq) | This operator compares two `CFileTime` objects to determine equality or the lesser. | +| [`CFileTime::operator =`](#operator_eq) | The assignment operator. | +| [`CFileTime::operator -=`](#operator_-_eq) | This operator is used to perform subtraction on a `CFileTimeSpan` object and assign the result to the current object. | +| [`CFileTime::operator ==`](#operator_eq_eq) | This operator compares two `CFileTime` objects for equality. | +| [`CFileTime::operator >`](#operator_gt) | This operator compares two `CFileTime` objects to determine the larger. | +| [`CFileTime::operator >=`](#operator_gt_eq) | This operator compares two `CFileTime` objects to determine equality or the larger. | + +### Public constants + +| Name | Description | +|--|--| +| [`CFileTime::Day`](#day) | A static data member storing the number of 100-nanosecond intervals that make up one day. | +| [`CFileTime::Hour`](#hour) | A static data member storing the number of 100-nanosecond intervals that make up one hour. | +| [`CFileTime::Millisecond`](#millisecond) | A static data member storing the number of 100-nanosecond intervals that make up one millisecond. | +| [`CFileTime::Minute`](#minute) | A static data member storing the number of 100-nanosecond intervals that make up one minute. | +| [`CFileTime::Second`](#second) | A static data member storing the number of 100-nanosecond intervals that make up one second. | +| [`CFileTime::Week`](#week) | A static data member storing the number of 100-nanosecond intervals that make up one week. | ## Remarks -This class provides methods for managing the date and time values associated with the creation, access and modification of files. The methods and data of this class are frequently used in conjunction with `CFileTimeSpan` objects, which deal with relative time values. +This class provides methods for managing the date and time values associated with the creation, access, and modification of files. The methods and data of this class are frequently used together with `CFileTimeSpan` objects, which deal with relative time values. -The date and time value is stored as a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601. This is the Coordinated Universal Time (UTC) format. +The date and time value is stored as a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601. This format is the Coordinated Universal Time (UTC) format. The following static const member variables are provided to simplify calculations: -|Member variable|Number of 100-nanosecond intervals| -|---------------------|-----------------------------------------| -|Millisecond|10,000| -|Second|Millisecond \* 1,000| -|Minute|Second \* 60| -|Hour|Minute \* 60| -|Day|Hour \* 24| -|Week|Day \* 7| - -**Note** Not all file systems can record creation and last access time and not all file systems record them in the same manner. For example, on the Windows NT FAT file system, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (the access date). On NTFS, access time has a resolution of 1 hour. Furthermore, FAT records times on disk in local time, but NTFS records times on disk in UTC. For more information, see [File Times](/windows/win32/SysInfo/file-times). +| Member variable | Number of 100-nanosecond intervals | +|--|--| +| Millisecond | 10,000 | +| Second | Millisecond \* 1,000 | +| Minute | Second \* 60 | +| Hour | Minute \* 60 | +| Day | Hour \* 24 | +| Week | Day \* 7 | -## Inheritance Hierarchy +> [!Note] +> Not all file systems can record creation and last access time and not all file systems record them in the same manner. For example, on the Windows NT FAT file system, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (the access date). On NTFS, access time has a resolution of 1 hour. Furthermore, FAT records times on disk in local time, but NTFS records times on disk in UTC. For more information, see [File times](/windows/win32/SysInfo/file-times). -`FILETIME` +## Inheritance hierarchy -`CFileTime` +[`FILETIME`](/windows/win32/api/minwinbase/ns-minwinbase-filetime)\ + └ [`CFileTime`](cfiletime-class.md) ## Requirements **Header:** atltime.h -## CFileTime::CFileTime +## `CFileTime::CFileTime` The constructor. -``` +```cpp CFileTime() throw(); CFileTime(const FILETIME& ft) throw(); CFileTime(ULONGLONG nTime) throw(); @@ -102,37 +102,37 @@ CFileTime(ULONGLONG nTime) throw(); ### Parameters -*ft*
-A [FILETIME](/windows/win32/api/minwinbase/ns-minwinbase-filetime) structure. +*`ft`*\ +A [`FILETIME`](/windows/win32/api/minwinbase/ns-minwinbase-filetime) structure. -*nTime*
+*`nTime`*\ The date and time expressed as a 64-bit value. ### Remarks The `CFileTime` object can be created using an existing date and time from a `FILETIME` structure, or expressed as a 64-bit value (in local or Coordinated Universal Time (UTC) time formats). The default constructor sets the time to 0. -## CFileTime::Day +## `CFileTime::Day` A static data member storing the number of 100-nanosecond intervals that make up one day. -``` +```cpp static const ULONGLONG Day = Hour* 24; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). -## CFileTime::GetCurrentTime +## `CFileTime::GetCurrentTime` Call this static function to retrieve a `CFileTime` object that represents the current system date and time. -``` +```cpp static CFileTime GetCurrentTime() throw(); ``` -### Return Value +### Return value Returns the current system date and time in Coordinated Universal Time (UTC) format. @@ -140,51 +140,51 @@ Returns the current system date and time in Coordinated Universal Time (UTC) for [!code-cpp[NVC_MFCFiles#41](../../atl-mfc-shared/reference/codesnippet/cpp/cfiletime-class_1.cpp)] -## CFileTime::GetTime +## `CFileTime::GetTime` Call this method to retrieve the time from the `CFileTime` object. -``` +```cpp ULONGLONG GetTime() const throw(); ``` -### Return Value +### Return value Returns the date and time as a 64-bit number, which may be in either local or Coordinated Universal Time (UTC) format. -## CFileTime::Hour +## `CFileTime::Hour` A static data member storing the number of 100-nanosecond intervals that make up one hour. -``` +```cpp static const ULONGLONG Hour = Minute* 60; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). -## CFileTime::LocalToUTC +## `CFileTime::LocalToUTC` Call this method to convert a local file time to a file time based on the Coordinated Universal Time (UTC). -``` +```cpp CFileTime LocalToUTC() const throw(); ``` -### Return Value +### Return value Returns a `CFileTime` object containing the time in UTC format. ### Example -See the example for [CFileTime::UTCToLocal](#utctolocal). +See the example for [`CFileTime::UTCToLocal`](#utctolocal). -## CFileTime::Millisecond +## `CFileTime::Millisecond` A static data member storing the number of 100-nanosecond intervals that make up one millisecond. -``` +```cpp static const ULONGLONG Millisecond = 10000; ``` @@ -192,226 +192,226 @@ static const ULONGLONG Millisecond = 10000; [!code-cpp[NVC_MFCFiles#44](../../atl-mfc-shared/reference/codesnippet/cpp/cfiletime-class_2.cpp)] -## CFileTime::Minute +## `CFileTime::Minute` A static data member storing the number of 100-nanosecond intervals that make up one minute. -``` +```cpp static const ULONGLONG Minute = Second* 60; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). -## CFileTime::operator - +## `CFileTime::operator -` This operator is used to perform subtraction on a `CFileTime` or `CFileTimeSpan` object. -``` +```cpp CFileTime operator-(CFileTimeSpan span) const throw(); CFileTimeSpan operator-(CFileTime ft) const throw(); ``` ### Parameters -*span*
+*`span`*\ A `CFileTimeSpan` object. -*ft*
+*`ft`*\ A `CFileTime` object. -### Return Value +### Return value Returns a `CFileTime` object or a `CFileTimeSpan` object representing the result of the time difference between the two objects. -## CFileTime::operator != +## `CFileTime::operator !=` This operator compares two `CFileTime` objects for inequality. -``` +```cpp bool operator!=(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the item being compared is not equal to the `CFileTime` object, otherwise FALSE. +Returns `TRUE` if the item being compared isn't equal to the `CFileTime` object, otherwise `FALSE`. -## CFileTime::operator + +## `CFileTime::operator +` This operator is used to perform addition on a `CFileTimeSpan` object. -``` +```cpp CFileTime operator+(CFileTimeSpan span) const throw(); ``` ### Parameters -*span*
+*`span`*\ A `CFileTimeSpan` object. -### Return Value +### Return value Returns a `CFileTime` object representing the result of the original time plus a relative time. -## CFileTime::operator += +## `CFileTime::operator +=` This operator is used to perform addition on a `CFileTimeSpan` object and assign the result to the current object. -``` +```cpp CFileTime& operator+=(CFileTimeSpan span) throw(); ``` ### Parameters -*span*
+*`span`*\ A `CFileTimeSpan` object. -### Return Value +### Return value Returns the updated `CFileTime` object, representing the result of the original time plus a relative time. -## CFileTime::operator < +## `CFileTime::operator <` This operator compares two `CFileTime` objects to determine the lesser. -``` +```cpp bool operator<(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the first object is less (earlier in time) than the second, FALSE otherwise. +Returns `TRUE` if the first object is less (earlier in time) than the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_MFCFiles#43](../../atl-mfc-shared/reference/codesnippet/cpp/cfiletime-class_3.cpp)] -## CFileTime::operator <= +## `CFileTime::operator <>=` This operator compares two `CFileTime` objects to determine equality or the lesser. -``` +```cpp bool operator<=(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the first object is less than (earlier in time) or equal to the second, otherwise FALSE. +Returns `TRUE` if the first object is less than (earlier in time) or equal to the second, otherwise `FALSE`. -## CFileTime::operator = +## `CFileTime::operator =` The assignment operator. -``` +```cpp CFileTime& operator=(const FILETIME& ft) throw(); ``` ### Parameters -*ft*
+*`ft`*\ A `CFileTime` object containing the new time and date. -### Return Value +### Return value Returns the updated `CFileTime` object. -## CFileTime::operator -= +## `CFileTime::operator -=` This operator is used to perform subtraction on a `CFileTimeSpan` object and assign the result to the current object. -``` +```cpp CFileTime& operator-=(CFileTimeSpan span) throw(); ``` ### Parameters -*span*
+*`span`*\ A `CFileTimeSpan` object containing the relative time to subtract. -### Return Value +### Return value Returns the updated `CFileTime` object. -## CFileTime::operator == +## `CFileTime::operator ==` This operator compares two `CFileTime` objects for equality. -``` +```cpp bool operator==(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to compare. -### Return Value +### Return value -Returns TRUE if the objects are equal, otherwise FALSE. +Returns `TRUE` if the objects are equal, otherwise `FALSE`. -## CFileTime::operator > +## `CFileTime::operator >` This operator compares two `CFileTime` objects to determine the larger. -``` +```cpp bool operator>(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the first object is greater than (later in time) than the second, otherwise FALSE. +Returns `TRUE` if the first object is greater than (later in time) than the second, otherwise `FALSE`. -## CFileTime::operator >= +## `CFileTime::operator >=` This operator compares two `CFileTime` objects to determine equality or the larger. -``` +```cpp bool operator>=(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the first object is greater than (later in time) or equal to the second, otherwise FALSE. +Returns `TRUE` if the first object is greater than (later in time) or equal to the second, otherwise `FALSE`. -## CFileTime::Second +## `CFileTime::Second` A static data member storing the number of 100-nanosecond intervals that make up one day. -``` +```cpp static const ULONGLONG Second = Millisecond* 1000; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). -## CFileTime::SetTime +## `CFileTime::SetTime` Call this method to set the date and time stored by the `CFileTime` object. @@ -421,18 +421,18 @@ void SetTime(ULONGLONG nTime) throw(); ### Parameters -*nTime*
+*`nTime`*\ The 64-bit value representing the date and time, in either local or Coordinated Universal Time (UTC) format. -## CFileTime::UTCToLocal +## `CFileTime::UTCToLocal` Call this method to convert time based on the Coordinated Universal Time (UTC) to local file time. -``` +```cpp CFileTime UTCToLocal() const throw(); ``` -### Return Value +### Return value Returns a `CFileTime` object containing the time in local file time format. @@ -440,21 +440,21 @@ Returns a `CFileTime` object containing the time in local file time format. [!code-cpp[NVC_MFCFiles#42](../../atl-mfc-shared/reference/codesnippet/cpp/cfiletime-class_4.cpp)] -## CFileTime::Week +## `CFileTime::Week` A static data member storing the number of 100-nanosecond intervals that make up one week. -``` +```cpp static const ULONGLONG Week = Day* 7; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). ## See also -[FILETIME](/windows/win32/api/minwinbase/ns-minwinbase-filetime)
-[CFileTimeSpan Class](../../atl-mfc-shared/reference/cfiletimespan-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[ATL/MFC Shared Classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) +[`FILETIME`](/windows/win32/api/minwinbase/ns-minwinbase-filetime)\ +[`CFileTimeSpan` class](../../atl-mfc-shared/reference/cfiletimespan-class.md)\ +[Hierarchy chart](../../mfc/hierarchy-chart.md)\ +[ATL/MFC shared classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) diff --git a/docs/atl-mfc-shared/reference/cfiletimespan-class.md b/docs/atl-mfc-shared/reference/cfiletimespan-class.md index 144bb6a723d..62a26f382ec 100644 --- a/docs/atl-mfc-shared/reference/cfiletimespan-class.md +++ b/docs/atl-mfc-shared/reference/cfiletimespan-class.md @@ -6,7 +6,7 @@ f1_keywords: ["CFileTimeSpan", "ATLTIME/ATL::CFileTimeSpan", "ATLTIME/ATL::CFile helpviewer_keywords: ["shared classes, CFileTimeSpan", "CFileTimeSpan class"] ms.assetid: 5856fb39-9c82-4027-8ccf-8760890491ec --- -# CFileTimeSpan class +# `CFileTimeSpan` class This class provides methods for managing relative date and time values associated with a file. @@ -22,44 +22,44 @@ class CFileTimeSpan |Name|Description| |----------|-----------------| -|[CFileTimeSpan::CFileTimeSpan](#cfiletimespan)|The constructor.| +|[`CFileTimeSpan::CFileTimeSpan`](#cfiletimespan)|The constructor.| ### Public methods |Name|Description| |----------|-----------------| -|[CFileTimeSpan::GetTimeSpan](#gettimespan)|Call this method to retrieve the time span from the `CFileTimeSpan` object.| -|[CFileTimeSpan::SetTimeSpan](#settimespan)|Call this method to set the time span of the `CFileTimeSpan` object.| +|[`CFileTimeSpan::GetTimeSpan`](#gettimespan)|Call this method to retrieve the time span from the `CFileTimeSpan` object.| +|[`CFileTimeSpan::SetTimeSpan`](#settimespan)|Call this method to set the time span of the `CFileTimeSpan` object.| ### Public operators |Name|Description| |----------|-----------------| -|[CFileTimeSpan::operator -](#operator_-)|Performs subtraction on a `CFileTimeSpan` object.| -|[CFileTimeSpan::operator !=](#operator_neq)|Compares two `CFileTimeSpan` objects for inequality.| -|[CFileTimeSpan::operator +](#operator_add)|Performs addition on a `CFileTimeSpan` object.| -|[CFileTimeSpan::operator +=](#operator_add_eq)|Performs addition on a `CFileTimeSpan` object and assign the result to the current object.| -|[CFileTimeSpan::operator <](#operator_lt)|Compares two `CFileTimeSpan` objects to determine the lesser.| -|[CFileTimeSpan::operator <=](#operator_lt_eq)|Compares two `CFileTimeSpan` objects to determine equality or the lesser.| -|[CFileTimeSpan::operator =](#operator_eq)|The assignment operator.| -|[CFileTimeSpan::operator -=](#operator_-_eq)|Performs subtraction on a `CFileTimeSpan` object and assign the result to the current object.| -|[CFileTimeSpan::operator ==](#operator_eq_eq)|Compares two `CFileTimeSpan` objects for equality.| -|[CFileTimeSpan::operator >](#operator_gt)|Compares two `CFileTimeSpan` objects to determine the larger.| -|[CFileTimeSpan::operator >=](#operator_gt_eq)|Compares two `CFileTimeSpan` objects to determine equality or the larger.| +|[`CFileTimeSpan::operator -`](#operator_-)|Performs subtraction on a `CFileTimeSpan` object.| +|[`CFileTimeSpan::operator !=`](#operator_neq)|Compares two `CFileTimeSpan` objects for inequality.| +|[`CFileTimeSpan::operator +`](#operator_add)|Performs addition on a `CFileTimeSpan` object.| +|[`CFileTimeSpan::operator +=`](#operator_add_eq)|Performs addition on a `CFileTimeSpan` object and assign the result to the current object.| +|[`CFileTimeSpan::operator <`](#operator_lt)|Compares two `CFileTimeSpan` objects to determine the lesser.| +|[`CFileTimeSpan::operator <=`](#operator_lt_eq)|Compares two `CFileTimeSpan` objects to determine equality or the lesser.| +|[`CFileTimeSpan::operator =`](#operator_eq)|The assignment operator.| +|[`CFileTimeSpan::operator -=`](#operator_-_eq)|Performs subtraction on a `CFileTimeSpan` object and assign the result to the current object.| +|[`CFileTimeSpan::operator ==`](#operator_eq_eq)|Compares two `CFileTimeSpan` objects for equality.| +|[`CFileTimeSpan::operator >`](#operator_gt)|Compares two `CFileTimeSpan` objects to determine the larger.| +|[`CFileTimeSpan::operator >=`](#operator_gt_eq)|Compares two `CFileTimeSpan` objects to determine equality or the larger.| ## Remarks -The `CFileTimeSpan` class provides methods to handle relative periods of time in the units the file system uses. These units are often used in file operations, such as when a file was created, last accessed, or last modified. The methods of this class are frequently used in conjunction with [CFileTime class](../../atl-mfc-shared/reference/cfiletime-class.md) objects. +The `CFileTimeSpan` class provides methods to handle relative periods of time in the units the file system uses. These units are often used in file operations, such as when a file was created, last accessed, or last modified. The methods of this class are frequently used together with [`CFileTime` class](../../atl-mfc-shared/reference/cfiletime-class.md) objects. ## Example -See the example for [CFileTime::Millisecond](../../atl-mfc-shared/reference/cfiletime-class.md#millisecond). +See the example for [`CFileTime::Millisecond`](../../atl-mfc-shared/reference/cfiletime-class.md#millisecond). ## Requirements **Header:** atltime.h -## CFileTimeSpan::CFileTimeSpan +## `CFileTimeSpan::CFileTimeSpan` The constructor. @@ -71,17 +71,17 @@ CFileTimeSpan(LONGLONG nSpan) throw(); ### Parameters -*span*\ +*`span`*\ An existing `CFileTimeSpan` object. -*nSpan*\ -A period of time in FILETIME units. +*`nSpan`*\ +A period of time in `FILETIME` units. ### Remarks -The `CFileTimeSpan` object can be created using an existing `CFileTimeSpan` object, or expressed as a 64-bit value in 100-nanosecond FILETIME units. For more information, see [CFileTime](cfiletime-class.md). The default constructor sets the time span to 0. +The `CFileTimeSpan` object can be created using an existing `CFileTimeSpan` object, or expressed as a 64-bit value in 100-nanosecond `FILETIME` units. For more information, see [`CFileTime`](cfiletime-class.md). The default constructor sets the time span to 0. -## CFileTimeSpan::GetTimeSpan +## `CFileTimeSpan::GetTimeSpan` Call this method to retrieve the time span from the `CFileTimeSpan` object. @@ -91,9 +91,9 @@ LONGLONG GetTimeSpan() const throw(); ### Return value -Returns the time span in 100-nanosecond FILETIME units. For more information, see [CFileTime](cfiletime-class.md). +Returns the time span in 100-nanosecond `FILETIME` units. For more information, see [`CFileTime`](cfiletime-class.md). -## CFileTimeSpan::operator - +## `CFileTimeSpan::operator -` Performs subtraction on a `CFileTimeSpan` object. @@ -103,14 +103,14 @@ CFileTimeSpan operator-(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns a `CFileTimeSpan` object representing the result of the difference between two time spans. -## CFileTimeSpan::operator != +## `CFileTimeSpan::operator !=` Compares two `CFileTimeSpan` objects for inequality. @@ -120,14 +120,14 @@ bool operator!=(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the item being compared isn't equal to the `CFileTimeSpan` object; otherwise FALSE. +Returns `TRUE` if the item being compared isn't equal to the `CFileTimeSpan` object; otherwise `FALSE`. -## CFileTimeSpan::operator + +## `CFileTimeSpan::operator +` Performs addition on a `CFileTimeSpan` object. @@ -137,14 +137,14 @@ CFileTimeSpan operator+(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns a `CFileTimeSpan` object containing the sum of the two time spans. -## CFileTimeSpan::operator += +## `CFileTimeSpan::operator +=` Performs addition on a `CFileTimeSpan` object and assigns the result to the current object. @@ -154,14 +154,14 @@ CFileTimeSpan& operator+=(CFileTimeSpan span) throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns the updated `CFileTimeSpan` object containing the sum of the two time spans. -## CFileTimeSpan::operator < +## `CFileTimeSpan::operator <` Compares two `CFileTimeSpan` objects to determine the lesser. @@ -171,14 +171,14 @@ bool operator<(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the first object is less (that is, represents a shorter time period) than the second, otherwise FALSE. +Returns `TRUE` if the first object is less (that is, represents a shorter time period) than the second, otherwise `FALSE`. -## CFileTimeSpan::operator <= +## `CFileTimeSpan::operator <=` Compares two `CFileTimeSpan` objects to determine equality or the lesser. @@ -188,14 +188,14 @@ bool operator<=(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the first object is less than (that is, represents a shorter time period) or equal to the second, otherwise FALSE. +Returns `TRUE` if the first object is less than (that is, represents a shorter time period) or equal to the second, otherwise `FALSE`. -## CFileTimeSpan::operator = +## `CFileTimeSpan::operator =` The assignment operator. @@ -205,14 +205,14 @@ CFileTimeSpan& operator=(const CFileTimeSpan& span) throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns the updated `CFileTimeSpan` object. -## CFileTimeSpan::operator -= +## `CFileTimeSpan::operator -=` Performs subtraction on a `CFileTimeSpan` object and assigns the result to the current object. @@ -222,14 +222,14 @@ CFileTimeSpan& operator-=(CFileTimeSpan span) throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns the updated `CFileTimeSpan` object. -## CFileTimeSpan::operator == +## `CFileTimeSpan::operator ==` Compares two `CFileTimeSpan` objects for equality. @@ -239,14 +239,14 @@ bool operator==(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the objects are equal, otherwise FALSE. +Returns `TRUE` if the objects are equal, otherwise `FALSE`. -## CFileTimeSpan::operator > +## `CFileTimeSpan::operator >` Compares two `CFileTimeSpan` objects to determine the larger. @@ -256,14 +256,14 @@ bool operator>(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the first object is greater than (that is, represents a longer time period) than the second, otherwise FALSE. +Returns `TRUE` if the first object is greater than (that is, represents a longer time period) than the second, otherwise `FALSE`. -## CFileTimeSpan::operator >= +## `CFileTimeSpan::operator >=` Compares two `CFileTimeSpan` objects to determine equality or the larger. @@ -273,14 +273,14 @@ bool operator>=(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the first object is greater than (that is, represents a longer time period) or equal to the second, otherwise FALSE. +Returns `TRUE` if the first object is greater than (that is, represents a longer time period) or equal to the second, otherwise `FALSE`. -## CFileTimeSpan::SetTimeSpan +## `CFileTimeSpan::SetTimeSpan` Call this method to set the time span of the `CFileTimeSpan` object. @@ -290,12 +290,12 @@ void SetTimeSpan(LONGLONG nSpan) throw(); ### Parameters -*nSpan*\ -The new value for the time span in 100-nanosecond FILETIME units. For more information, see [CFileTime](cfiletime-class.md). +*`nSpan`*\ +The new value for the time span in 100-nanosecond `FILETIME` units. For more information, see [`CFileTime`](cfiletime-class.md). ## See also -[FILETIME](/windows/win32/api/minwinbase/ns-minwinbase-filetime)\ -[CFileTime class](cfiletime-class.md)\ +[`FILETIME`](/windows/win32/api/minwinbase/ns-minwinbase-filetime)\ +[`CFileTime` class](cfiletime-class.md)\ [Hierarchy chart](../../mfc/hierarchy-chart.md)\ [ATL/MFC shared classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) diff --git a/docs/atl/reference/cautoptr-class.md b/docs/atl/reference/cautoptr-class.md index 68abb80ad8d..ec51839b4b2 100644 --- a/docs/atl/reference/cautoptr-class.md +++ b/docs/atl/reference/cautoptr-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: CAutoPtr Class" -title: "CAutoPtr Class" +description: "Learn more about: CAutoPtr class" +title: "CAutoPtr class" ms.date: "11/04/2016" f1_keywords: ["CAutoPtr", "ATLBASE/ATL::CAutoPtr", "ATLBASE/ATL::CAutoPtr::CAutoPtr", "ATLBASE/ATL::CAutoPtr::Attach", "ATLBASE/ATL::CAutoPtr::Detach", "ATLBASE/ATL::CAutoPtr::Free", "ATLBASE/ATL::CAutoPtr::m_p"] helpviewer_keywords: ["CAutoPtr class"] ms.assetid: 08988d53-4fb0-4711-bdfc-8ac29c63f410 --- -# CAutoPtr Class +# `CAutoPtr` class This class represents a smart pointer object. @@ -22,51 +22,51 @@ class CAutoPtr ### Parameters -*T*
+*`T`*\ The pointer type. ## Members -### Public Constructors +### Public constructors -|Name|Description| -|----------|-----------------| -|[CAutoPtr::CAutoPtr](#cautoptr)|The constructor.| -|[CAutoPtr::~CAutoPtr](#dtor)|The destructor.| +| Name | Description | +|--|--| +| [`CAutoPtr::CAutoPtr`](#cautoptr) | The constructor. | +| [`CAutoPtr::~CAutoPtr`](#dtor) | The destructor. | -### Public Methods +### Public methods -|Name|Description| -|----------|-----------------| -|[CAutoPtr::Attach](#attach)|Call this method to take ownership of an existing pointer.| -|[CAutoPtr::Detach](#detach)|Call this method to release ownership of a pointer.| -|[CAutoPtr::Free](#free)|Call this method to delete an object pointed to by a `CAutoPtr`.| +| Name | Description | +|--|--| +| [`CAutoPtr::Attach`](#attach) | Call this method to take ownership of an existing pointer. | +| [`CAutoPtr::Detach`](#detach) | Call this method to release ownership of a pointer. | +| [`CAutoPtr::Free`](#free) | Call this method to delete an object pointed to by a `CAutoPtr`. | -### Public Operators +### Public operators -|Name|Description| -|----------|-----------------| -|[CAutoPtr::operator T*](#operator_t_star)|The cast operator.| -|[CAutoPtr::operator =](#operator_eq)|The assignment operator.| -|[CAutoPtr::operator ->](#operator_ptr)|The pointer-to-member operator.| +| Name | Description | +|--|--| +| [`CAutoPtr::operator T*`](#operator_t_star) | The cast operator. | +| [`CAutoPtr::operator =`](#operator_eq) | The assignment operator. | +| [`CAutoPtr::operator ->`](#operator_ptr) | The pointer-to-member operator. | -### Public Data Members +### Public data members -|Name|Description| -|----------|-----------------| -|[CAutoPtr::m_p](#m_p)|The pointer data member variable.| +| Name | Description | +|--|--| +| [`CAutoPtr::m_p`](#m_p) | The pointer data member variable. | ## Remarks -This class provides methods for creating and managing a smart pointer, which will help protect against memory leaks by automatically freeing resources when it falls out of scope. +This class provides methods for creating and managing a smart pointer. Smart pointers help protect against memory leaks by automatically freeing resources when it falls out of scope. -Further, `CAutoPtr`'s copy constructor and assignment operator transfer ownership of the pointer, copying the source pointer to the destination pointer and setting the source pointer to NULL. It is therefore impossible to have two `CAutoPtr` objects each storing the same pointer, and this reduces the possibility of deleting the same pointer twice. +Further, `CAutoPtr`'s copy constructor and assignment operator transfer ownership of the pointer, copying the source pointer to the destination pointer and setting the source pointer to NULL. That's why it's impossible to have two `CAutoPtr` objects each storing the same pointer, and it reduces the possibility of deleting the same pointer twice. `CAutoPtr` also simplifies the creation of collections of pointers. Instead of deriving a collection class and overriding the destructor, it's simpler to make a collection of `CAutoPtr` objects. When the collection is deleted, the `CAutoPtr` objects will go out of scope and automatically delete themselves. -[CHeapPtr](../../atl/reference/cheapptr-class.md) and variants work in the same way as `CAutoPtr`, except that they allocate and free memory using different heap functions instead of the C++ **`new`** and **`delete`** operators. [CAutoVectorPtr](../../atl/reference/cautovectorptr-class.md) is similar to `CAutoPtr`, the only difference being that it uses **vector new[]** and **vector delete[]** to allocate and free memory. +[`CHeapPtr`](../../atl/reference/cheapptr-class.md) and variants work in the same way as `CAutoPtr`, except that they allocate and free memory using different heap functions instead of the C++ **`new`** and **`delete`** operators. [`CAutoVectorPtr`](../../atl/reference/cautovectorptr-class.md) is similar to `CAutoPtr`, the only difference being that it uses **vector new[]** and **vector delete[]** to allocate and free memory. -See also [CAutoPtrArray](../../atl/reference/cautoptrarray-class.md) and [CAutoPtrList](../../atl/reference/cautoptrlist-class.md) when arrays or lists of smart pointers are required. +See also [`CAutoPtrArray`](../../atl/reference/cautoptrarray-class.md) and [`CAutoPtrList`](../../atl/reference/cautoptrlist-class.md) when arrays or lists of smart pointers are required. ## Requirements @@ -76,7 +76,7 @@ See also [CAutoPtrArray](../../atl/reference/cautoptrarray-class.md) and [CAutoP [!code-cpp[NVC_ATL_Utilities#74](../../atl/codesnippet/cpp/cautoptr-class_1.cpp)] -## CAutoPtr::Attach +## `CAutoPtr::Attach` Call this method to take ownership of an existing pointer. @@ -86,20 +86,20 @@ void Attach(T* p) throw(); ### Parameters -*p*
+*`p`*\ The `CAutoPtr` object will take ownership of this pointer. ### Remarks -When a `CAutoPtr` object takes ownership of a pointer, it will automatically delete the pointer and any allocated data when it goes out of scope. If [CAutoPtr::Detach](#detach) is called, the programmer is again given responsibility for freeing any allocated resources. +When a `CAutoPtr` object takes ownership of a pointer, it will automatically delete the pointer and any allocated data when it goes out of scope. If [`CAutoPtr::Detach`](#detach) is called, the programmer is again given responsibility for freeing any allocated resources. -In debug builds, an assertion failure will occur if the [CAutoPtr::m_p](#m_p) data member currently points to an existing value; that is, it is not equal to NULL. +In debug builds, an assertion failure will occur if the [`CAutoPtr::m_p`](#m_p) data member currently points to an existing value; that is, it's not equal to NULL. ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` Overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::CAutoPtr +## `CAutoPtr::CAutoPtr` The constructor. @@ -116,10 +116,10 @@ CAutoPtr(CAutoPtr& p) throw(); ### Parameters -*p*
+*`p`*\ An existing pointer. -*TSrc*
+*`TSrc`*\ The type being managed by another `CAutoPtr`, used to initialize the current object. ### Remarks @@ -128,9 +128,9 @@ The `CAutoPtr` object can be created using an existing pointer, in which case it ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::~CAutoPtr +## `CAutoPtr::~CAutoPtr` The destructor. @@ -140,9 +140,9 @@ The destructor. ### Remarks -Frees any allocated resources. Calls [CAutoPtr::Free](#free). +Frees any allocated resources. Calls [`CAutoPtr::Free`](#free). -## CAutoPtr::Detach +## `CAutoPtr::Detach` Call this method to release ownership of a pointer. @@ -150,19 +150,19 @@ Call this method to release ownership of a pointer. T* Detach() throw(); ``` -### Return Value +### Return value Returns a copy of the pointer. ### Remarks -Releases ownership of a pointer, sets the [CAutoPtr::m_p](#m_p) data member variable to NULL, and returns a copy of the pointer. After calling `Detach`, it is up to the programmer to free any allocated resources over which the `CAutoPtr` object may have previously assumed reponsibility. +Releases ownership of a pointer, sets the [`CAutoPtr::m_p`](#m_p) data member variable to NULL, and returns a copy of the pointer. After calling `Detach`, it's up to the programmer to free any allocated resources over which the `CAutoPtr` object may have previously assumed responsibility. ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::Free +## `CAutoPtr::Free` Call this method to delete an object pointed to by a `CAutoPtr`. @@ -172,9 +172,9 @@ void Free() throw(); ### Remarks -The object pointed to by the `CAutoPtr` is freed, and the [CAutoPtr::m_p](#m_p) data member variable is set to NULL. +The object pointed to by the `CAutoPtr` is freed, and the [`CAutoPtr::m_p`](#m_p) data member variable is set to NULL. -## CAutoPtr::m_p +## `CAutoPtr::m_p` The pointer data member variable. @@ -186,7 +186,7 @@ T* m_p; This member variable holds the pointer information. -## CAutoPtr::operator = +## `CAutoPtr::operator =` The assignment operator. @@ -200,25 +200,25 @@ CAutoPtr& operator= (CAutoPtr& p); ### Parameters -*p*
+*`p`*\ A pointer. -*TSrc*
+*`TSrc`*\ A class type. -### Return Value +### Return value -Returns a reference to a **CAutoPtr\< T >**. +Returns a reference to a `CAutoPtr< T >`. ### Remarks -The assignment operator detaches the `CAutoPtr` object from any current pointer and attaches the new pointer, *p*, in its place. +The assignment operator detaches the `CAutoPtr` object from any current pointer and attaches the new pointer, *`p`*, in its place. ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::operator -> +## `CAutoPtr::operator ->` The pointer-to-member operator. @@ -226,9 +226,9 @@ The pointer-to-member operator. T* operator->() const throw(); ``` -### Return Value +### Return value -Returns the value of the [CAutoPtr::m_p](#m_p) data member variable. +Returns the value of the [`CAutoPtr::m_p`](#m_p) data member variable. ### Remarks @@ -236,9 +236,9 @@ Use this operator to call a method in a class pointed to by the `CAutoPtr` objec ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` Overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::operator T* +## `CAutoPtr::operator T*` The cast operator. @@ -246,16 +246,16 @@ The cast operator. operator T* () const throw(); ``` -### Return Value +### Return value Returns a pointer to the object data type defined in the class template. ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` overview](../../atl/reference/cautoptr-class.md). ## See also -[CHeapPtr Class](../../atl/reference/cheapptr-class.md)
-[CAutoVectorPtr Class](../../atl/reference/cautovectorptr-class.md)
-[Class Overview](../../atl/atl-class-overview.md) +[`CHeapPtr` class](../../atl/reference/cheapptr-class.md)\ +[`CAutoVectorPtr` class](../../atl/reference/cautovectorptr-class.md)\ +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/ccomcurrency-class.md b/docs/atl/reference/ccomcurrency-class.md index 55f0b3fc6ee..b51cb2e04a2 100644 --- a/docs/atl/reference/ccomcurrency-class.md +++ b/docs/atl/reference/ccomcurrency-class.md @@ -6,88 +6,88 @@ f1_keywords: ["CComCurrency", "ATLCUR/ATL::CComCurrency", "ATLCUR/ATL::CComCurre helpviewer_keywords: ["CComCurrency class"] ms.assetid: a1c3d10a-bba6-40cc-8bcf-aed9023c8a9e --- -# CComCurrency Class +# `CComCurrency` Class -`CComCurrency` has methods and operators for creating and managing a CURRENCY object. +`CComCurrency` has methods and operators for creating and managing a `CURRENCY` object. ## Syntax -``` -class CComCurrency +```cpp +class CComCurrency; ``` ## Members -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[CComCurrency::CComCurrency](#ccomcurrency)|The constructor for a `CComCurrency` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[CComCurrency::GetCurrencyPtr](#getcurrencyptr)|Returns the address of an `m_currency` data member.| -|[CComCurrency::GetFraction](#getfraction)|Call this method to return the fractional component of a `CComCurrency` object.| -|[CComCurrency::GetInteger](#getinteger)|Call this method to return the integer component of a `CComCurrency` object.| -|[CComCurrency::Round](#round)|Call this method to round a `CComCurrency` object to the nearest integer value.| -|[CComCurrency::SetFraction](#setfraction)|Call this method to set the fractional component of a `CComCurrency` object.| -|[CComCurrency::SetInteger](#setinteger)|Call this method to set the integer component of a `CComCurrency` object.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[CComCurrency::operator -](#operator_-)|This operator is used to perform subtraction on a `CComCurrency` object.| -|[CComCurrency::operator !=](#operator_neq)|Compares two `CComCurrency` objects for inequality.| -|[CComCurrency::operator *](#operator_star)|This operator is used to perform multiplication on a `CComCurrency` object.| -|[CComCurrency::operator *=](#operator_star_eq)|This operator is used to perform multiplication on a `CComCurrency` object and assign it the result.| -|[CComCurrency::operator /](#operator_div)|This operator is used to perform division on a `CComCurrency` object.| -|[CComCurrency::operator /=](#operator_div_eq)|This operator is used to perform division on a `CComCurrency` object and assign it the result.| -|[CComCurrency::operator +](#operator_add)|This operator is used to perform addition on a `CComCurrency` object.| -|[CComCurrency::operator +=](#operator_add_eq)|This operator is used to perform addition on a `CComCurrency` object and assign the result to the current object.| -|[CComCurrency::operator <](#operator_lt)|This operator compares two `CComCurrency` objects to determine the lesser.| -|[CComCurrency::operator <=](#operator_lt_eq)|This operator compares two `CComCurrency` objects to determine equality or the lesser.| -|[CComCurrency::operator =](#operator_eq)|This operator assigns the `CComCurrency` object to a new value.| -|[CComCurrency::operator -=](#operator_-_eq)|This operator is used to perform subtraction on a `CComCurrency` object and assign it the result.| -|[CComCurrency::operator ==](#operator_eq_eq)|This operator compares two `CComCurrency` objects for equality.| -|[CComCurrency::operator >](#operator_gt)|This operator compares two `CComCurrency` objects to determine the larger.| -|[CComCurrency::operator >=](#operator_gt_eq)|This operator compares two `CComCurrency` objects to determine equality or the larger.| -|[CComCurrency::operator CURRENCY](#operator_currency)|Casts a CURRENCY object.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[CComCurrency::m_currency](#m_currency)|The CURRENCY variable created by your class instance.| +### Public constructors + +| Name | Description | +|--|--| +| [`CComCurrency::CComCurrency`](#ccomcurrency) | The constructor for a `CComCurrency` object. | + +### Public methods + +| Name | Description | +|--|--| +| [`CComCurrency::GetCurrencyPtr`](#getcurrencyptr) | Returns the address of an `m_currency` data member. | +| [`CComCurrency::GetFraction`](#getfraction) | Call this method to return the fractional component of a `CComCurrency` object. | +| [`CComCurrency::GetInteger`](#getinteger) | Call this method to return the integer component of a `CComCurrency` object. | +| [`CComCurrency::Round`](#round) | Call this method to round a `CComCurrency` object to the nearest integer value. | +| [`CComCurrency::SetFraction`](#setfraction) | Call this method to set the fractional component of a `CComCurrency` object. | +| [`CComCurrency::SetInteger`](#setinteger) | Call this method to set the integer component of a `CComCurrency` object. | + +### Public operators + +| Name | Description | +|--|--| +| [`CComCurrency::operator -`](#operator_-) | This operator is used to perform subtraction on a `CComCurrency` object. | +| [`CComCurrency::operator !=`](#operator_neq) | Compares two `CComCurrency` objects for inequality. | +| [`CComCurrency::operator *`](#operator_star) | This operator is used to perform multiplication on a `CComCurrency` object. | +| [`CComCurrency::operator *=`](#operator_star_eq) | This operator is used to perform multiplication on a `CComCurrency` object and assign it the result. | +| [`CComCurrency::operator /`](#operator_div) | This operator is used to perform division on a `CComCurrency` object. | +| [`CComCurrency::operator /=`](#operator_div_eq) | This operator is used to perform division on a `CComCurrency` object and assign it the result. | +| [`CComCurrency::operator +`](#operator_add) | This operator is used to perform addition on a `CComCurrency` object. | +| [`CComCurrency::operator +=`](#operator_add_eq) | This operator is used to perform addition on a `CComCurrency` object and assign the result to the current object. | +| [`CComCurrency::operator <`](#operator_lt) | This operator compares two `CComCurrency` objects to determine the lesser. | +| [`CComCurrency::operator <=`](#operator_lt_eq) | This operator compares two `CComCurrency` objects to determine equality or the lesser. | +| [`CComCurrency::operator =`](#operator_eq) | This operator assigns the `CComCurrency` object to a new value. | +| [`CComCurrency::operator -=`](#operator_-_eq) | This operator is used to perform subtraction on a `CComCurrency` object and assign it the result. | +| [`CComCurrency::operator ==`](#operator_eq_eq) | This operator compares two `CComCurrency` objects for equality. | +| [`CComCurrency::operator >`](#operator_gt) | This operator compares two `CComCurrency` objects to determine the larger. | +| [`CComCurrency::operator >=`](#operator_gt_eq) | This operator compares two `CComCurrency` objects to determine equality or the larger. | +| [`CComCurrency::operator CURRENCY`](#operator_currency) | Casts a `CURRENCY` object. | + +### Public data members + +| Name | Description | +|--|--| +| [`CComCurrency::m_currency`](#m_currency) | The `CURRENCY` variable created by your class instance. | ## Remarks -`CComCurrency` is a wrapper for the CURRENCY data type. CURRENCY is implemented as an 8-byte two's-complement integer value scaled by 10,000. This gives a fixed-point number with 15 digits to the left of the decimal point and 4 digits to the right. The CURRENCY data type is extremely useful for calculations involving money, or for any fixed-point calculations where accuracy is important. +`CComCurrency` is a wrapper for the `CURRENCY` data type. `CURRENCY` is implemented as an 8-byte two's-complement integer value scaled by 10,000. This scaling gives a fixed-point number with 15 digits left of the decimal point and 4 digits to the right. The `CURRENCY` data type is useful for calculations involving money, or for any fixed-point calculations where accuracy is important. The `CComCurrency` wrapper implements arithmetic, assignment, and comparison operations for this fixed-point type. The supported applications have been selected to control the rounding errors that can occur during fixed-point calculations. -The `CComCurrency` object provides access to the numbers on either side of the decimal point in the form of two components: an integer component which stores the value to the left of the decimal point, and a fractional component which stores the value to the right of the decimal point. The fractional component is stored internally as an integer value between -9999 (CY_MIN_FRACTION) and +9999 (CY_MAX_FRACTION). The method [CComCurrency::GetFraction](#getfraction) returns a value scaled by a factor of 10000 (CY_SCALE). +The `CComCurrency` object provides access to the numbers on either side of the decimal point in the form of two components: an integer component, which stores the value to the left of the decimal point, and a fractional component, which stores the value to the right of the decimal point. The fractional component is stored internally as an integer value between -9999 (`CY_MIN_FRACTION`) and +9999 (`CY_MAX_FRACTION`). The method [`CComCurrency::GetFraction`](#getfraction) returns a value scaled by a factor of 10000 (`CY_SCALE`). -When specifying the integer and fractional components of a `CComCurrency` object, remember that the fractional component is a number in the range 0 to 9999. This is important when dealing with a currency such as the US dollar that expresses amounts using only two significant digits after the decimal point. Even though the last two digits are not displayed, they must be taken into account. +When specifying the integer and fractional components of a `CComCurrency` object, remember that the fractional component is a number in the range 0 to 9999. This consideration is important when dealing with a currency such as the US dollar. Dollar amounts are commonly expressed using only two significant digits after the decimal point. Even though the last two digits aren't displayed, they must be taken into account. -|Value|Possible CComCurrency assignments| -|-----------|---------------------------------------| -|$10.50|CComCurrency(10,5000) *or* CComCurrency(10.50)| -|$10.05|CComCurrency(10,500) *or* CComCurrency(10.05)| +| Value | Possible CComCurrency assignments | +|--|--| +| $10.50 | `CComCurrency(10,5000)` or `CComCurrency(10.50)` | +| $10.05 | `CComCurrency(10,500)` or `CComCurrency(10.05)` | -The values CY_MIN_FRACTION, CY_MAX_FRACTION, and CY_SCALE are defined in atlcur.h. +The values `CY_MIN_FRACTION`, `CY_MAX_FRACTION`, and `CY_SCALE` are defined in atlcur.h. ## Requirements **Header:** atlcur.h -## CComCurrency::CComCurrency +## `CComCurrency::CComCurrency` The constructor. -``` +```cpp CComCurrency() throw(); CComCurrency(const CComCurrency& curSrc) throw(); CComCurrency(CURRENCY cySrc) throw(); @@ -109,79 +109,79 @@ explicit CComCurrency(LPCSTR szSrc); ### Parameters -*curSrc*
+*`curSrc`*\ An existing `CComCurrency` object. -*cySrc*
-A variable of type CURRENCY. +*`cySrc`*\ +A variable of type `CURRENCY`. -*bSrc*, *dSrc*, *fSrc*, *lSrc*, *sSrc*, *ulSrc, usSrc*
+*`bSrc`*, *`dSrc`*, *`fSrc`*, *`lSrc`*, *`sSrc`*, *`ulSrc`*, *`usSrc`*\ The initial value given to the member variable `m_currency`. -*cSrc*
+*`cSrc`*\ A character containing the initial value given to the member variable `m_currency`. -*nInteger*, *nFraction*
-The integer and fractional components of the initial monetary value. See the [CComCurrency](../../atl/reference/ccomcurrency-class.md) overview for more information. +*`nInteger`*, *`nFraction`*\ +The initial monetary value's integer and fractional components. For more information, see the [`CComCurrency`](../../atl/reference/ccomcurrency-class.md) overview. -*pDispSrc*
+*`pDispSrc`*\ An `IDispatch` pointer. -*varSrc*
-A variable of type VARIANT. The locale of the current thread is used to perform the conversion. +*`varSrc`*\ +A variable of type `VARIANT`. The locale of the current thread is used to perform the conversion. -*szSrc*
+*`szSrc`*\ A Unicode or ANSI string containing the initial value. The locale of the current thread is used to perform the conversion. ### Remarks -The constructor sets the initial value of [CComCurrency::m_currency](#m_currency), and accepts a wide range of data types, including integers, strings, floating-point numbers, CURRENCY variables, and other `CComCurrency` objects. If no value is provided, `m_currency` is set to 0. +The constructor sets the initial value of [`CComCurrency::m_currency`](#m_currency), and accepts a wide range of data types, including integers, strings, floating-point numbers, `CURRENCY` variables, and other `CComCurrency` objects. If no value is provided, `m_currency` is set to 0. -In the event of an error, such as an overflow, the constructors lacking an empty exception specification (**throw()**) call `AtlThrow` with an HRESULT describing the error. +If there's an error, such as an overflow, the constructors lacking an empty exception specification (**`throw()`**) call `AtlThrow` with an `HRESULT` describing the error. -When using floating-point or double values to assign a value, note that `CComCurrency(10.50)` is equivalent to `CComCurrency(10,5000)` and not `CComCurrency(10,50)`. +When using floating-point or double values to assign a value, remember that `CComCurrency(10.50)` is equivalent to `CComCurrency(10,5000)`, and not `CComCurrency(10,50)`. -## CComCurrency::GetCurrencyPtr +## `CComCurrency::GetCurrencyPtr` Returns the address of an `m_currency` data member. -``` +```cpp CURRENCY* GetCurrencyPtr() throw(); ``` -### Return Value +### Return value Returns the address of an `m_currency` data member -## CComCurrency::GetFraction +## `CComCurrency::GetFraction` Call this method to return the fractional component of the `CComCurrency` object. -``` +```cpp SHORT GetFraction() const; ``` -### Return Value +### Return value Returns the fractional component of the `m_currency` data member. ### Remarks -The fractional component is a 4-digit integer value between -9999 (CY_MIN_FRACTION) and +9999 (CY_MAX_FRACTION). `GetFraction` returns this value scaled by 10000 (CY_SCALE). The values of CY_MIN_FRACTION, CY_MAX_FRACTION, and CY_SCALE are defined in atlcur.h. +The fractional component is a 4-digit integer value between -9999 (`CY_MIN_FRACTION`) and +9999 (`CY_MAX_FRACTION`). `GetFraction` returns this value scaled by 10000 (`CY_SCALE`). The values of `CY_MIN_FRACTION`, `CY_MAX_FRACTION`, and `CY_SCALE` are defined in atlcur.h. ### Example [!code-cpp[NVC_ATL_Utilities#50](../../atl/codesnippet/cpp/ccomcurrency-class_1.cpp)] -## CComCurrency::GetInteger +## `CComCurrency::GetInteger` Call this method to get the integer component of a `CComCurrency` object. -``` +```cpp LONGLONG GetInteger() const; ``` -### Return Value +### Return value Returns the integer component of the `m_currency` data member. @@ -189,11 +189,11 @@ Returns the integer component of the `m_currency` data member. [!code-cpp[NVC_ATL_Utilities#51](../../atl/codesnippet/cpp/ccomcurrency-class_2.cpp)] -## CComCurrency::m_currency +## `CComCurrency::m_currency` -The CURRENCY data member. +The `CURRENCY` data member. -``` +```cpp CURRENCY m_currency; ``` @@ -201,113 +201,113 @@ CURRENCY m_currency; This member holds the currency accessed and manipulated by the methods of this class. -## CComCurrency::operator - +## `CComCurrency::operator -` This operator is used to perform subtraction on a `CComCurrency` object. -``` +```cpp CComCurrency operator-() const; CComCurrency operator-(const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns a `CComCurrency` object representing the result of the subtraction. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns a `CComCurrency` object representing the result of the subtraction. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#55](../../atl/codesnippet/cpp/ccomcurrency-class_3.cpp)] -## CComCurrency::operator != +## `CComCurrency::operator !=` This operator compares two objects for inequality. -``` +```cpp bool operator!= (const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ The `CComCurrency` object to be compared. -### Return Value +### Return value -Returns TRUE if the item being compared is not equal to the `CComCurrency` object; otherwise, FALSE. +Returns `TRUE` if the item being compared isn't equal to the `CComCurrency` object; otherwise, `FALSE`. ### Example [!code-cpp[NVC_ATL_Utilities#56](../../atl/codesnippet/cpp/ccomcurrency-class_4.cpp)] -## CComCurrency::operator * +## `CComCurrency::operator *` This operator is used to perform multiplication on a `CComCurrency` object. -``` +```cpp CComCurrency operator*(long nOperand) const; CComCurrency operator*(const CComCurrency& cur) const; ``` ### Parameters -*nOperand*
+*`nOperand`*\ The multiplier. -*cur*
+*`cur`*\ The `CComCurrency` object used as the multiplier. -### Return Value +### Return value -Returns a `CComCurrency` object representing the result of the multiplication. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns a `CComCurrency` object representing the result of the multiplication. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#57](../../atl/codesnippet/cpp/ccomcurrency-class_5.cpp)] -## CComCurrency::operator \*= +## `CComCurrency::operator *=` This operator is used to perform multiplication on a `CComCurrency` object and assign it the result. -``` +```cpp const CComCurrency& operator*= (long nOperand); const CComCurrency& operator*= (const CComCurrency& cur); ``` ### Parameters -*nOperand*
+*`nOperand`*\ The multiplier. -*cur*
+*`cur`*\ The `CComCurrency` object used as the multiplier. -### Return Value +### Return value -Returns the updated `CComCurrency` object. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns the updated `CComCurrency` object. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#58](../../atl/codesnippet/cpp/ccomcurrency-class_6.cpp)] -## CComCurrency::operator / +## `CComCurrency::operator /` This operator is used to perform division on a `CComCurrency` object. -``` +```cpp CComCurrency operator/(long nOperand) const; ``` ### Parameters -*nOperand*
+*`nOperand`*\ The divisor. -### Return Value +### Return value Returns a `CComCurrency` object representing the result of the division. If the divisor is 0, an assert failure will occur. @@ -315,20 +315,20 @@ Returns a `CComCurrency` object representing the result of the division. If the [!code-cpp[NVC_ATL_Utilities#59](../../atl/codesnippet/cpp/ccomcurrency-class_7.cpp)] -## CComCurrency::operator /= +## `CComCurrency::operator /=` This operator is used to perform division on a `CComCurrency` object and assign it the result. -``` +```cpp const CComCurrency& operator/= (long nOperand); ``` ### Parameters -*nOperand*
+*`nOperand`*\ The divisor. -### Return Value +### Return value Returns the updated `CComCurrency` object. If the divisor is 0, an assert failure will occur. @@ -336,95 +336,95 @@ Returns the updated `CComCurrency` object. If the divisor is 0, an assert failur [!code-cpp[NVC_ATL_Utilities#60](../../atl/codesnippet/cpp/ccomcurrency-class_8.cpp)] -## CComCurrency::operator + +## `CComCurrency::operator +` This operator is used to perform addition on a `CComCurrency` object. -``` +```cpp CComCurrency operator+(const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ The `CComCurrency` object to be added to the original object. -### Return Value +### Return value -Returns a `CComCurrency` object representing the result of the addition. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns a `CComCurrency` object representing the result of the addition. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#61](../../atl/codesnippet/cpp/ccomcurrency-class_9.cpp)] -## CComCurrency::operator += +## `CComCurrency::operator +=` This operator is used to perform addition on a `CComCurrency` object and assign the result to the current object. -``` +```cpp const CComCurrency& operator+= (const CComCurrency& cur); ``` ### Parameters -*cur*
+*`cur`*\ The `CComCurrency` object. -### Return Value +### Return value -Returns the updated `CComCurrency` object. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns the updated `CComCurrency` object. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#62](../../atl/codesnippet/cpp/ccomcurrency-class_10.cpp)] -## CComCurrency::operator < +## `CComCurrency::operator <` This operator compares two `CComCurrency` objects to determine the lesser. -``` +```cpp bool operator<(const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns TRUE if the first object is less than the second, FALSE otherwise. +Returns `TRUE` if the first object is less than the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#63](../../atl/codesnippet/cpp/ccomcurrency-class_11.cpp)] -## CComCurrency::operator <= +## `CComCurrency::operator <=` This operator compares two `CComCurrency` objects to determine equality or the lesser. -``` +```cpp bool operator<= (const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns TRUE if the first object is less than or equal to the second, FALSE otherwise. +Returns `TRUE` if the first object is less than or equal to the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#64](../../atl/codesnippet/cpp/ccomcurrency-class_12.cpp)] -## CComCurrency::operator = +## `CComCurrency::operator =` This operator assigns the `CComCurrency` object to a new value. -``` +```cpp const CComCurrency& operator= (const CComCurrency& curSrc) throw(); const CComCurrency& operator= (CURRENCY cySrc) throw(); const CComCurrency& operator= (FLOAT fSrc); @@ -440,184 +440,184 @@ const CComCurrency& operator= (DECIMAL dSrc); ### Parameters -*curSrc*
+*`curSrc`*\ A `CComCurrency` object. -*cySrc*
-A variable of type CURRENCY. +*`cySrc`*\ +A variable of type `CURRENCY`. -*sSrc*, *fSrc*, *lSrc*, *bSrc*, *usSrc*, *dSrc*, *cSrc*, *ulSrc*, *dSrc*
+*`sSrc`*, *`fSrc`*, *`lSrc`*, *`bSrc`*, *`usSrc`*, *`dSrc`*, *`cSrc`*, *`ulSrc`*, *`dSrc`*\ The numeric value to assign to the `CComCurrency` object. -### Return Value +### Return value -Returns the updated `CComCurrency` object. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns the updated `CComCurrency` object. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#65](../../atl/codesnippet/cpp/ccomcurrency-class_13.cpp)] -## CComCurrency::operator -= +## `CComCurrency::operator -=` This operator is used to perform subtraction on a `CComCurrency` object and assign it the result. -``` +```cpp const CComCurrency& operator-= (const CComCurrency& cur); ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns the updated `CComCurrency` object. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns the updated `CComCurrency` object. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#66](../../atl/codesnippet/cpp/ccomcurrency-class_14.cpp)] -## CComCurrency::operator == +## `CComCurrency::operator ==` This operator compares two `CComCurrency` objects for equality. -``` +```cpp bool operator== (const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ The `CComCurrency` object to compare. -### Return Value +### Return value -Returns TRUE if the objects are equal (that is, the `m_currency` data members, both integer and fractional, in both objects have the same value), FALSE otherwise. +Returns `TRUE` if the objects are equal (that is, the `m_currency` data members, both integer and fractional, in both objects have the same value), `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#67](../../atl/codesnippet/cpp/ccomcurrency-class_15.cpp)] -## CComCurrency::operator > +## `CComCurrency::operator >` This operator compares two `CComCurrency` objects to determine the larger. -``` +```cpp bool operator>(const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns TRUE if the first object is greater than the second, FALSE otherwise. +Returns `TRUE` if the first object is greater than the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#68](../../atl/codesnippet/cpp/ccomcurrency-class_16.cpp)] -## CComCurrency::operator >= +## `CComCurrency::operator >=` This operator compares two `CComCurrency` objects to determine equality or the larger. -``` +```cpp bool operator>= (const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns TRUE if the first object is greater than or equal to the second, FALSE otherwise. +Returns `TRUE` if the first object is greater than or equal to the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#69](../../atl/codesnippet/cpp/ccomcurrency-class_17.cpp)] -## CComCurrency::operator CURRENCY +## `CComCurrency::operator CURRENCY` -These operators are used to cast a `CComCurrency` object to a CURRENCY data type. +These operators are used to cast a `CComCurrency` object to a `CURRENCY` data type. -``` +```cpp operator CURRENCY&() throw(); operator const CURRENCY&() const throw(); ``` -### Return Value +### Return value -Returns a reference to a CURRENCY object. +Returns a reference to a `CURRENCY` object. ### Example [!code-cpp[NVC_ATL_Utilities#70](../../atl/codesnippet/cpp/ccomcurrency-class_18.cpp)] -## CComCurrency::Round +## `CComCurrency::Round` Call this method to round the currency to a specified number of decimal places. -``` +```cpp HRESULT Roundint nDecimals); ``` ### Parameters -*nDecimals*
+*`nDecimals`*\ The number of digits to which `m_currency` will be rounded, in the range 0 to 4. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Example [!code-cpp[NVC_ATL_Utilities#52](../../atl/codesnippet/cpp/ccomcurrency-class_19.cpp)] -## CComCurrency::SetFraction +## `CComCurrency::SetFraction` Call this method to set the fractional component of a `CComCurrency` object. -``` +```cpp HRESULT SetFraction(SHORT nFraction); ``` ### Parameters -*nFraction*
-The value to be assigned to the fractional component of the `m_currency` data member. The sign of the fractional component must the same as the integer component, and the value must be in range -9999 (CY_MIN_FRACTION) to +9999 (CY_MAX_FRACTION). +*`nFraction`*\ +The value to assign to the fractional component of the `m_currency` data member. The sign of the fractional component must be the same as the integer component, and the value must be in the range -9999 (`CY_MIN_FRACTION`) to +9999 (`CY_MAX_FRACTION`). -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Example [!code-cpp[NVC_ATL_Utilities#53](../../atl/codesnippet/cpp/ccomcurrency-class_20.cpp)] -## CComCurrency::SetInteger +## `CComCurrency::SetInteger` Call this method to set the integer component of a `CComCurrency` object. -``` +```cpp HRESULT SetInteger(LONGLONG nInteger); ``` ### Parameters -*nInteger*
+*`nInteger`*\ The value to be assigned to the integer component of the `m_currency` data member. The sign of the integer component must match the sign of the existing fractional component. -*nInteger* must be in the range CY_MIN_INTEGER to CY_MAX_INTEGER inclusive. These values are defined in atlcur.h. +*`nInteger`* must be in the range `CY_MIN_INTEGER` to `CY_MAX_INTEGER`, inclusive. These values are defined in atlcur.h. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Example @@ -625,6 +625,6 @@ Returns S_OK on success, or an error HRESULT on failure. ## See also -[COleCurrency Class](../../mfc/reference/colecurrency-class.md)
-[CURRENCY](/windows/win32/api/wtypes/ns-wtypes-cy-r1)
-[Class Overview](../../atl/atl-class-overview.md) +[`COleCurrency` class](../../mfc/reference/colecurrency-class.md)\ +[`CURRENCY`](/windows/win32/api/wtypes/ns-wtypes-cy-r1)\ +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/ccomptrbase-class.md b/docs/atl/reference/ccomptrbase-class.md index 020318db19d..c2363d848e2 100644 --- a/docs/atl/reference/ccomptrbase-class.md +++ b/docs/atl/reference/ccomptrbase-class.md @@ -6,75 +6,75 @@ f1_keywords: ["CComPtrBase", "ATLCOMCLI/ATL::CComPtrBase", "ATLCOMCLI/ATL::CComP helpviewer_keywords: ["CComPtrBase class"] ms.assetid: 6dbe9543-dee8-4a97-b02f-dd3a25f4a1a0 --- -# CComPtrBase Class +# `CComPtrBase` Class This class provides a basis for smart pointer classes using COM-based memory routines. ## Syntax -``` +```cpp template class CComPtrBase ``` -#### Parameters +### Parameters -*T*
+*`T`*\ The object type to be referenced by the smart pointer. ## Members -### Public Constructors +### Public constructors -|Name|Description| -|----------|-----------------| -|[CComPtrBase::~CComPtrBase](#dtor)|The destructor.| +| Name | Description | +|--|--| +| [`CComPtrBase::~CComPtrBase`](#dtor) | The destructor. | -### Public Methods +### Public methods -|Name|Description| -|----------|-----------------| -|[CComPtrBase::Advise](#advise)|Call this method to create a connection between the `CComPtrBase`'s connection point and a client's sink.| -|[CComPtrBase::Attach](#attach)|Call this method to take ownership of an existing pointer.| -|[CComPtrBase::CoCreateInstance](#cocreateinstance)|Call this method to create an object of the class associated with a specified Class ID or Program ID.| -|[CComPtrBase::CopyTo](#copyto)|Call this method to copy the `CComPtrBase` pointer to another pointer variable.| -|[CComPtrBase::Detach](#detach)|Call this method to release ownership of a pointer.| -|[CComPtrBase::IsEqualObject](#isequalobject)|Call this method to check if the specified `IUnknown` points to the same object associated with the `CComPtrBase` object.| -|[CComPtrBase::QueryInterface](#queryinterface)|Call this method to return a pointer to a specified interface.| -|[CComPtrBase::Release](#release)|Call this method to release the interface.| -|[CComPtrBase::SetSite](#setsite)|Call this method to set the site of the `CComPtrBase` object to the `IUnknown` of the parent object.| +| Name | Description | +|--|--| +| [`CComPtrBase::Advise`](#advise) | Call this method to create a connection between the `CComPtrBase`'s connection point and a client's sink. | +| [`CComPtrBase::Attach`](#attach) | Call this method to take ownership of an existing pointer. | +| [`CComPtrBase::CoCreateInstance`](#cocreateinstance) | Call this method to create an object of the class associated with a specified Class ID or Program ID. | +| [`CComPtrBase::CopyTo`](#copyto) | Call this method to copy the `CComPtrBase` pointer to another pointer variable. | +| [`CComPtrBase::Detach`](#detach) | Call this method to release ownership of a pointer. | +| [`CComPtrBase::IsEqualObject`](#isequalobject) | Call this method to check if the specified `IUnknown` points to the same object associated with the `CComPtrBase` object. | +| [`CComPtrBase::QueryInterface`](#queryinterface) | Call this method to return a pointer to a specified interface. | +| [`CComPtrBase::Release`](#release) | Call this method to release the interface. | +| [`CComPtrBase::SetSite`](#setsite) | Call this method to set the site of the `CComPtrBase` object to the `IUnknown` of the parent object. | -### Public Operators +### Public operators -|Name|Description| -|----------|-----------------| -|[CComPtrBase::operator T*](#operator_t_star)|The cast operator.| -|[CComPtrBase::operator !](#operator_not)|The NOT operator.| -|[CComPtrBase::operator &](#operator_amp)|The & operator.| -|[CComPtrBase::operator *](#operator_star)|The \* operator.| -|[CComPtrBase::operator <](#ccomptrbase__operator lt)|The less-than operator.| -|[CComPtrBase::operator ==](#operator_eq_eq)|The equality operator.| -|[CComPtrBase::operator ->](#operator_ptr)|The pointer-to-members operator.| +| Name | Description | +|--|--| +| [`CComPtrBase::operator T*`](#operator_t_star) | The cast operator. | +| [`CComPtrBase::operator !`](#operator_not) | The NOT operator. | +| [`CComPtrBase::operator &`](#operator_amp) | The address-of `&` operator. | +| [`CComPtrBase::operator *`](#operator_star) | The pointer-to `*` operator. | +| [`CComPtrBase::operator <`](#operator_lt) | The less-than operator. | +| [`CComPtrBase::operator ==`](#operator_eq_eq) | The equality operator. | +| [`CComPtrBase::operator ->`](#operator_ptr) | The pointer-to-members operator. | -### Public Data Members +### Public data members -|Name|Description| -|----------|-----------------| -|[CComPtrBase::p](#p)|The pointer data member variable.| +| Name | Description | +|--|--| +| [`CComPtrBase::p`](#p) | The pointer data member variable. | ## Remarks -This class provides the basis for other smart pointers which use COM memory management routines, such as [CComQIPtr](../../atl/reference/ccomqiptr-class.md) and [CComPtr](../../atl/reference/ccomptr-class.md). The derived classes add their own constructors and operators, but rely on the methods provided by `CComPtrBase`. +This class provides the basis for other smart pointers that use COM memory management routines, such as [`CComQIPtr`](../../atl/reference/ccomqiptr-class.md) and [`CComPtr`](../../atl/reference/ccomptr-class.md). The derived classes add their own constructors and operators, but rely on the methods provided by `CComPtrBase`. ## Requirements **Header:** atlcomcli.h -## CComPtrBase::Advise +## `CComPtrBase::Advise` Call this method to create a connection between the `CComPtrBase`'s connection point and a client's sink. -``` +```cpp HRESULT Advise( IUnknown* pUnk, const IID& iid, @@ -83,24 +83,24 @@ HRESULT Advise( ### Parameters -*pUnk*
+*`pUnk`*\ A pointer to the client's `IUnknown`. -*iid*
-The GUID of the connection point. Typically, this is the same as the outgoing interface managed by the connection point. +*`iid`*\ +The GUID of the connection point. Typically, this GUID is the same as the outgoing interface managed by the connection point. -*pdw*
+*`pdw`*\ A pointer to the cookie that uniquely identifies the connection. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -See [AtlAdvise](connection-point-global-functions.md#atladvise) for more information. +For more information, see [`AtlAdvise`](connection-point-global-functions.md#atladvise). -## CComPtrBase::Attach +## `CComPtrBase::Attach` Call this method to take ownership of an existing pointer. @@ -110,18 +110,18 @@ void Attach(T* p2) throw(); ### Parameters -*p2*
+*`p2`*\ The `CComPtrBase` object will take ownership of this pointer. ### Remarks -`Attach` calls [CComPtrBase::Release](#release) on the existing [CComPtrBase::p](#p) member variable and then assigns *p2* to `CComPtrBase::p`. When a `CComPtrBase` object takes ownership of a pointer, it will automatically call `Release` on the pointer which will delete the pointer and any allocated data if the reference count on the object goes to 0. +`Attach` calls [`CComPtrBase::Release`](#release) on the existing [`CComPtrBase::p`](#p) member variable and then assigns *`p2`* to `CComPtrBase::p`. When a `CComPtrBase` object takes ownership of a pointer, it will automatically call `Release` on the pointer, which deletes the pointer and any allocated data if the reference count on the object goes to 0. -## CComPtrBase::~CComPtrBase +## `CComPtrBase::~CComPtrBase` The destructor. -``` +```cpp ~CComPtrBase() throw(); ``` @@ -129,11 +129,11 @@ The destructor. Releases the interface pointed to by `CComPtrBase`. -## CComPtrBase::CoCreateInstance +## `CComPtrBase::CoCreateInstance` Call this method to create an object of the class associated with a specified Class ID or Program ID. -``` +```cpp HRESULT CoCreateInstance( LPCOLESTR szProgID, LPUNKNOWN pUnkOuter = NULL, @@ -147,177 +147,177 @@ HRESULT CoCreateInstance( ### Parameters -*szProgID*
+*`szProgID`*\ Pointer to a ProgID, used to recover the CLSID. -*pUnkOuter*
-If NULL, indicates that the object is not being created as part of an aggregate. If non- NULL, is a pointer to the aggregate object's `IUnknown` interface (the controlling `IUnknown`). +*`pUnkOuter`*\ +If NULL, indicates that the object isn't being created as part of an aggregate. If non- NULL, is a pointer to the aggregate object's `IUnknown` interface (the controlling `IUnknown`). -*dwClsContext*
+*`dwClsContext`*\ Context in which the code that manages the newly created object will run. -*rclsid*
+*`rclsid`*\ CLSID associated with the data and code that will be used to create the object. -### Return Value +### Return value -Returns S_OK on success, or REGDB_E_CLASSNOTREG, CLASS_E_NOAGGREGATION, CO_E_CLASSSTRING or E_NOINTERFACE on failure. See [CoCreateClassInstance](/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance) and [CLSIDFromProgID](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromprogid) for a description of these errors. +Returns `S_OK` on success, or `REGDB_E_CLASSNOTREG`, `CLASS_E_NOAGGREGATION`, `CO_E_CLASSSTRING`, or `E_NOINTERFACE` on failure. See [`CoCreateClassInstance`](/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance) and [`CLSIDFromProgID`](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromprogid) for a description of these errors. ### Remarks -If the first form of the method is called, [CLSIDFromProgID](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromprogid) is used to recover the CLSID. Both forms then call [CoCreateClassInstance](/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance). +If the first form of the method is called, [`CLSIDFromProgID`](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromprogid) is used to recover the CLSID. Both forms then call [`CoCreateClassInstance`](/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance). -In debug builds, an assertion error will occur if [CComPtrBase::p](#p) is not equal to NULL. +In debug builds, an assertion error will occur if [`CComPtrBase::p`](#p) isn't equal to NULL. -## CComPtrBase::CopyTo +## `CComPtrBase::CopyTo` Call this method to copy the `CComPtrBase` pointer to another pointer variable. -``` +```cpp HRESULT CopyTo(T** ppT) throw(); ``` ### Parameters -*ppT*
-Address of the variable which will receive the `CComPtrBase` pointer. +*`ppT`*\ +Address of the variable to receive the `CComPtrBase` pointer. -### Return Value +### Return value -Returns S_OK on success, E_POINTER on failure. +Returns `S_OK` on success, `E_POINTER` on failure. ### Remarks -Copies the `CComPtrBase` pointer to *ppT*. The reference count on the [CComPtrBase::p](#p) member variable is incremented. +Copies the `CComPtrBase` pointer to *`ppT`*. The reference count on the [`CComPtrBase::p`](#p) member variable is incremented. -An error HRESULT will be returned if *ppT* is equal to NULL. In debug builds, an assertion error will occur if *ppT* is equal to NULL. +An error `HRESULT` will be returned if *`ppT`* is equal to NULL. In debug builds, an assertion error will occur if *`ppT`* is equal to NULL. -## CComPtrBase::Detach +## `CComPtrBase::Detach` Call this method to release ownership of a pointer. -``` +```cpp T* Detach() throw(); ``` -### Return Value +### Return value Returns a copy of the pointer. ### Remarks -Releases ownership of a pointer, sets the [CComPtrBase::p](#p) data member variable to NULL, and returns a copy of the pointer. +Releases ownership of a pointer, sets the [`CComPtrBase::p`](#p) data member variable to NULL, and returns a copy of the pointer. -## CComPtrBase::IsEqualObject +## `CComPtrBase::IsEqualObject` Call this method to check if the specified `IUnknown` points to the same object associated with the `CComPtrBase` object. -``` +```cpp bool IsEqualObject(IUnknown* pOther) throw(); ``` ### Parameters -*pOther*
+*`pOther`*\ The `IUnknown *` to compare. -### Return Value +### Return value Returns true if the objects are identical, false otherwise. -## CComPtrBase::operator ! +## `CComPtrBase::operator !` The NOT operator. -``` +```cpp bool operator!() const throw(); ``` -### Return Value +### Return value Returns true if the `CComHeapPtr` pointer is equal to NULL, false otherwise. -## CComPtrBase::operator & +## `CComPtrBase::operator &` -The & operator. +The address-of `&` operator. -``` +```cpp T** operator&() throw(); ``` -### Return Value +### Return value Returns the address of the object pointed to by the `CComPtrBase` object. -## CComPtrBase::operator \* +## `CComPtrBase::operator *` -The \* operator. +The pointer-to `*` operator. -``` +```cpp T& operator*() const throw(); ``` -### Return Value +### Return value -Returns the value of [CComPtrBase::p](#p); that is, a pointer to the object referenced by the `CComPtrBase` object. +Returns the value of [`CComPtrBase::p`](#p); that is, a pointer to the object referenced by the `CComPtrBase` object. -If debug builds, an assertion error will occur if [CComPtrBase::p](#p) is not equal to NULL. +If debug builds, an assertion error will occur if [`CComPtrBase::p`](#p) isn't equal to NULL. -## CComPtrBase::operator == +## `CComPtrBase::operator ==` The equality operator. -``` +```cpp bool operator== (T* pT) const throw(); ``` ### Parameters -*pT*
+*`pT`*\ A pointer to an object. -### Return Value +### Return value -Returns true if `CComPtrBase` and *pT* point to the same object, false otherwise. +Returns true if `CComPtrBase` and *`pT`* point to the same object, false otherwise. -## CComPtrBase::operator -> +## `CComPtrBase::operator ->` The pointer-to-member operator. -``` +```cpp _NoAddRefReleaseOnCComPtr* operator->() const throw(); ``` -### Return Value +### Return value -Returns the value of the [CComPtrBase::p](#p) data member variable. +Returns the value of the [`CComPtrBase::p`](#p) data member variable. ### Remarks Use this operator to call a method in a class pointed to by the `CComPtrBase` object. In debug builds, an assertion failure will occur if the `CComPtrBase` data member points to NULL. -## CComPtrBase::operator < +## `CComPtrBase::operator <` The less-than operator. -``` +```cpp bool operator<(T* pT) const throw(); ``` ### Parameters -*pT*
+*`pT`*\ A pointer to an object. -### Return Value +### Return value -Returns true if the pointer managed by current object is less than the pointer to which it is being compared. +Returns true if the pointer managed by current object is less than the pointer to which it's being compared. -## CComPtrBase::operator T\* +## `CComPtrBase::operator T*` The cast operator. -``` +```cpp operator T*() const throw(); ``` @@ -325,11 +325,11 @@ operator T*() const throw(); Returns a pointer to the object data type defined in the class template. -## CComPtrBase::p +## `CComPtrBase::p` The pointer data member variable. -``` +```cpp T* p; ``` @@ -337,34 +337,34 @@ T* p; This member variable holds the pointer information. -## CComPtrBase::QueryInterface +## `CComPtrBase::QueryInterface` Call this method to return a pointer to a specified interface. -``` +```cpp template HRESULT QueryInterface(Q ** pp) const throw(); ``` ### Parameters -*Q*
+*`Q`*\ The object type whose interface pointer is required. -*pp*
+*`pp`*\ Address of output variable that receives the requested interface pointer. -### Return Value +### Return value -Returns S_OK on success, or E_NOINTERFACE on failure. +Returns `S_OK` on success, or `E_NOINTERFACE` on failure. ### Remarks -This method calls [IUnknown::QueryInterface](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)). +This method calls [`IUnknown::QueryInterface`](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)). -In debug builds, an assertion error will occur if *pp* is not equal to NULL. +In debug builds, an assertion error will occur if *`pp`* isn't equal to NULL. -## CComPtrBase::Release +## `CComPtrBase::Release` Call this method to release the interface. @@ -374,29 +374,29 @@ void Release() throw(); ### Remarks -The interface is released, and [CComPtrBase::p](#p) is set to NULL. +The interface is released, and [`CComPtrBase::p`](#p) is set to NULL. -## CComPtrBase::SetSite +## `CComPtrBase::SetSite` Call this method to set the site of the `CComPtrBase` object to the `IUnknown` of the parent object. -``` +```cpp HRESULT SetSite(IUnknown* punkParent) throw(); ``` ### Parameters -*punkParent*
+*`punkParent`*\ A pointer to the `IUnknown` interface of the parent. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -This method calls [AtlSetChildSite](composite-control-global-functions.md#atlsetchildsite). +This method calls [`AtlSetChildSite`](composite-control-global-functions.md#atlsetchildsite). ## See also -[Class Overview](../../atl/atl-class-overview.md) +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/ccomvariant-class.md b/docs/atl/reference/ccomvariant-class.md index 31418519793..cb97f860f4d 100644 --- a/docs/atl/reference/ccomvariant-class.md +++ b/docs/atl/reference/ccomvariant-class.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: CComVariant Class" -title: "CComVariant Class" +description: "Learn more about: CComVariant class" +title: "CComVariant class" ms.date: "11/04/2016" f1_keywords: ["CComVariant", "ATLCOMCLI/ATL::CComVariant", "ATLCOMCLI/ATL::CComVariant::CComVariant", "ATLCOMCLI/ATL::CComVariant::Attach", "ATLCOMCLI/ATL::CComVariant::ChangeType", "ATLCOMCLI/ATL::CComVariant::Clear", "ATLCOMCLI/ATL::CComVariant::Copy", "ATLCOMCLI/ATL::CComVariant::CopyTo", "ATLCOMCLI/ATL::CComVariant::Detach", "ATLCOMCLI/ATL::CComVariant::GetSize", "ATLCOMCLI/ATL::CComVariant::ReadFromStream", "ATLCOMCLI/ATL::CComVariant::SetByRef", "ATLCOMCLI/ATL::CComVariant::WriteToStream"] helpviewer_keywords: ["VARIANT macro", "CComVariant class", "VARIANT macro, ATL"] ms.assetid: 4d31149c-d005-44b5-a509-10f84afa2b61 --- -# CComVariant Class +# `CComVariant` class -This class wraps the VARIANT type, providing a member indicating the type of data stored. +This class wraps the `VARIANT` type, providing a member indicating the type of data stored. ## Syntax @@ -18,80 +18,79 @@ class CComVariant : public tagVARIANT ## Members -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[CComVariant::CComVariant](#ccomvariant)|The constructor.| -|[CComVariant::~CComVariant](#dtor)|The destructor.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[CComVariant::Attach](#attach)|Attaches a VARIANT to the `CComVariant` object.| -|[CComVariant::ChangeType](#changetype)|Converts the `CComVariant` object to a new type.| -|[CComVariant::Clear](#clear)|Clears the `CComVariant` object.| -|[CComVariant::Copy](#copy)|Copies a VARIANT to the `CComVariant` object.| -|[CComVariant::CopyTo](#copyto)|Copies the contents of the `CComVariant` object.| -|[CComVariant::Detach](#detach)|Detaches the underlying VARIANT from the `CComVariant` object.| -|[CComVariant::GetSize](#getsize)|Returns the size in number of bytes of the contents of the `CComVariant` object.| -|[CComVariant::ReadFromStream](#readfromstream)|Loads a VARIANT from a stream.| -|[CComVariant::SetByRef](#setbyref)|Initializes the `CComVariant` object and sets the `vt` member to VT_BYREF.| -|[CComVariant::WriteToStream](#writetostream)|Saves the underlying VARIANT to a stream.| - -### Public Operators - -|Operator|Description| -|-|-| -|[CComVariant::operator <](#operator_lt)|Indicates whether the `CComVariant` object is less than the specified VARIANT.| -|[CComVariant::operator >](#operator_gt)|Indicates whether the `CComVariant` object is greater than the specified VARIANT.| -|[operator !=](#operator_neq)|Indicates whether the `CComVariant` object does not equal the specified VARIANT.| -|[operator =](#operator_eq)|Assigns a value to the `CComVariant` object.| -|[operator ==](#operator_eq_eq)|Indicates whether the `CComVariant` object equals the specified VARIANT.| +### Public constructors + +| Name | Description | +|--|--| +| [`CComVariant::CComVariant`](#ccomvariant) | The constructor. | +| [`CComVariant::~CComVariant`](#dtor) | The destructor. | + +### Public methods + +| Name | Description | +|--|--| +| [`CComVariant::Attach`](#attach) | Attaches a `VARIANT` to the `CComVariant` object. | +| [`CComVariant::ChangeType`](#changetype) | Converts the `CComVariant` object to a new type. | +| [`CComVariant::Clear`](#clear) | Clears the `CComVariant` object. | +| [`CComVariant::Copy`](#copy) | Copies a `VARIANT` to the `CComVariant` object. | +| [`CComVariant::CopyTo`](#copyto) | Copies the contents of the `CComVariant` object. | +| [`CComVariant::Detach`](#detach) | Detaches the underlying `VARIANT` from the `CComVariant` object. | +| [`CComVariant::GetSize`](#getsize) | Returns the size in number of bytes of the contents of the `CComVariant` object. | +| [`CComVariant::ReadFromStream`](#readfromstream) | Loads a `VARIANT` from a stream. | +| [`CComVariant::SetByRef`](#setbyref) | Initializes the `CComVariant` object and sets the `vt` member to `VT_BYREF`. | +| [`CComVariant::WriteToStream`](#writetostream) | Saves the underlying `VARIANT` to a stream. | + +### Public operators + +| Operator | Description | +|--|--| +| [`CComVariant::operator <`](#operator_lt) | Indicates whether the `CComVariant` object is less than the specified `VARIANT`. | +| [`CComVariant::operator >`](#operator_gt) | Indicates whether the `CComVariant` object is greater than the specified `VARIANT`. | +| [`CComVariant::operator !=`](#operator_neq) | Indicates whether the `CComVariant` object doesn't equal the specified `VARIANT`. | +| [`CComVariant::operator =`](#operator_eq) | Assigns a value to the `CComVariant` object. | +| [`CComVariant::operator ==`](#operator_eq_eq) | Indicates whether the `CComVariant` object equals the specified `VARIANT`. | ## Remarks -`CComVariant` wraps the VARIANT and VARIANTARG type, which consists of a union and a member indicating the type of the data stored in the union. VARIANTs are typically used in Automation. +`CComVariant` wraps the `VARIANT` and `VARIANTARG` type, which consists of a union and a member indicating the type of the data stored in the union. VARIANTs are typically used in Automation. -`CComVariant` derives from the VARIANT type so it can be used wherever a VARIANT can be used. You can, for example, use the V_VT macro to extract the type of a `CComVariant` or you can access the `vt` member directly just as you can with a VARIANT. +`CComVariant` derives from the `VARIANT` type so it can be used wherever a `VARIANT` can be used. You can, for example, use the `V_VT` macro to extract the type of a `CComVariant` or you can access the `vt` member directly just as you can with a `VARIANT`. -## Inheritance Hierarchy +## Inheritance hierarchy -`tagVARIANT` - -`CComVariant` +[`tagVARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant)\ + └ [`CComVariant`](ccomvariant-class.md) ## Requirements **Header:** atlcomcli.h -## CComVariant::Attach +## `CComVariant::Attach` -Safely clears the current contents of the `CComVariant` object, copies the contents of *pSrc* into this object, then sets the variant type of *pSrc* to VT_EMPTY. +Safely clears the current contents of the `CComVariant` object, copies the contents of *`pSrc`* into this object, then sets the variant type of *`pSrc`* to `VT_EMPTY`. -``` +```cpp HRESULT Attach(VARIANT* pSrc); ``` ### Parameters -*pSrc*
-[in] Points to the [VARIANT](/windows/win32/api/oaidl/ns-oaidl-variant) to be attached to the object. +*`pSrc`*\ +[in] Points to the [`VARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant) to be attached to the object. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -Ownership of the data held by *pSrc* is transferred to the `CComVariant` object. +Ownership of the data held by *`pSrc`* is transferred to the `CComVariant` object. -## CComVariant::CComVariant +## `CComVariant::CComVariant` Each constructor handles the safe initialization of the `CComVariant` object by calling the `VariantInit` Win32 function or by setting the object's value and type according to the parameters passed. -``` +```cpp CComVariant() throw(); CComVariant(const CComVariant& varSrc); CComVariant(const VARIANT& varSrc); @@ -119,181 +118,181 @@ CComVariant(const CComBSTR& bstrSrc); ### Parameters -*varSrc*
-[in] The `CComVariant` or VARIANT used to initialize the `CComVariant` object. The contents of the source variant are copied to the destination without conversion. +*`varSrc`*\ +[in] The `CComVariant` or `VARIANT` used to initialize the `CComVariant` object. The contents of the source variant are copied to the destination without conversion. -*lpszSrc*
-[in] The character string used to initialize the `CComVariant` object. You can pass a zero-terminated wide (Unicode) character string to the LPCOLESTR version of the constructor or an ANSI string to the LPCSTR version. In either case the string is converted to a Unicode BSTR allocated using `SysAllocString`. The type of the `CComVariant` object will be VT_BSTR. +*`lpszSrc`*\ +[in] The character string used to initialize the `CComVariant` object. You can pass a zero-terminated wide (Unicode) character string to the `LPCOLESTR` version of the constructor or an ANSI string to the `LPCSTR` version. In either case, the string is converted to a Unicode `BSTR` allocated using `SysAllocString`. The type of the `CComVariant` object is `VT_BSTR`. -*bSrc*
-[in] The **`bool`** used to initialize the `CComVariant` object. The **`bool`** argument is converted to a VARIANT_BOOL before being stored. The type of the `CComVariant` object will be VT_BOOL. +*`bSrc`*\ +[in] The **`bool`** used to initialize the `CComVariant` object. The **`bool`** argument is converted to a `VARIANT_BOOL` before being stored. The type of the `CComVariant` object is `VT_BOOL`. -*nSrc*
-[in] The **`int`**, **BYTE**, **`short`**, **`long`**, LONGLONG, ULONGLONG, **`unsigned short`**, **`unsigned long`**, or **`unsigned int`** used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_I4, VT_UI1, VT_I2, VT_I4, VT_I8, VT_UI8, VT_UI2, VT_UI4, or VT_UI4, respectively. +*`nSrc`*\ +[in] The **`int`**, `BYTE`, **`short`**, **`long`**, `LONGLONG`, `ULONGLONG`, **`unsigned short`**, **`unsigned long`**, or **`unsigned int`** used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_I4`, `VT_UI1`, `VT_I2`, `VT_I4`, `VT_I8`, `VT_UI8`, `VT_UI2`, `VT_UI4`, or `VT_UI4`, respectively. -*vtSrc*
-[in] The type of the variant. When the first parameter is **`int`**, valid types are VT_I4 and VT_INT. When the first parameter is **`long`**, valid types are VT_I4 and VT_ERROR. When the first parameter is **`double`**, valid types are VT_R8 and VT_DATE. When the first parameter is **`unsigned int`**, valid types are VT_UI4 and VT_UINT. +*`vtSrc`*\ +[in] The type of the variant. When the first parameter is **`int`**, valid types are `VT_I4` and `VT_INT`. When the first parameter is **`long`**, valid types are `VT_I4` and `VT_ERROR`. When the first parameter is **`double`**, valid types are `VT_R8` and `VT_DATE`. When the first parameter is **`unsigned int`**, valid types are `VT_UI4` and `VT_UINT`. -*fltSrc*
-[in] The **`float`** used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_R4. +*`fltSrc`*\ +[in] The **`float`** used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_R4`. -*dblSrc*
-[in] The **`double`** used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_R8. +*`dblSrc`*\ +[in] The **`double`** used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_R8`. -*cySrc*
-[in] The `CY` used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_CY. +*`cySrc`*\ +[in] The `CY` used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_CY`. -*pSrc*
-[in] The `IDispatch` or `IUnknown` pointer used to initialize the `CComVariant` object. `AddRef` will be called on the interface pointer. The type of the `CComVariant` object will be VT_DISPATCH or VT_UNKNOWN, respectively. +*`pSrc`*\ +[in] The `IDispatch` or `IUnknown` pointer used to initialize the `CComVariant` object. `AddRef` is called on the interface pointer. The type of the `CComVariant` object is `VT_DISPATCH` or `VT_UNKNOWN`, respectively. -Or, the SAFERRAY pointer used to initialize the `CComVariant` object. A copy of the SAFEARRAY is stored in the `CComVariant` object. The type of the `CComVariant` object will be a combination of the original type of the SAFEARRAY and VT_ARRAY. +Or, the `SAFERRAY` pointer used to initialize the `CComVariant` object. A copy of the `SAFEARRAY` is stored in the `CComVariant` object. The type of the `CComVariant` object is a combination of the original type of the `SAFEARRAY` and `VT_ARRAY`. -*cSrc*
-[in] The **`char`** used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_I1. +*`cSrc`*\ +[in] The **`char`** used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_I1`. -*bstrSrc*
-[in] The BSTR used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_BSTR. +*`bstrSrc`*\ +[in] The `BSTR` used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_BSTR`. ### Remarks -The destructor manages cleanup by calling [CComVariant::Clear](#clear). +The destructor manages cleanup by calling [`CComVariant::Clear`](#clear). -## CComVariant::~CComVariant +## `CComVariant::~CComVariant` The destructor. -``` +```cpp ~CComVariant() throw(); ``` ### Remarks -This method manages cleanup by calling [CComVariant::Clear](#clear). +This method manages cleanup by calling [`CComVariant::Clear`](#clear). -## CComVariant::ChangeType +## `CComVariant::ChangeType` Converts the `CComVariant` object to a new type. -``` +```cpp HRESULT ChangeType(VARTYPE vtNew, const VARIANT* pSrc = NULL); ``` ### Parameters -*vtNew*
+*`vtNew`*\ [in] The new type for the `CComVariant` object. -*pSrc*
-[in] A pointer to the VARIANT whose value will be converted to the new type. The default value is NULL, meaning the `CComVariant` object will be converted in place. +*`pSrc`*\ +[in] A pointer to the `VARIANT` whose value is converted to the new type. The default value is NULL, meaning the `CComVariant` object is converted in place. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -If you pass a value for *pSrc*, `ChangeType` will use this VARIANT as the source for the conversion. Otherwise, the `CComVariant` object will be the source. +If you pass a value for *`pSrc`*, `ChangeType` will use this `VARIANT` as the source for the conversion. Otherwise, the `CComVariant` object is the source. -## CComVariant::Clear +## `CComVariant::Clear` Clears the `CComVariant` object by calling the `VariantClear` Win32 function. -``` +```cpp HRESULT Clear(); ``` -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks The destructor automatically calls `Clear`. -## CComVariant::Copy +## `CComVariant::Copy` -Frees the `CComVariant` object and then assigns it a copy of the specified VARIANT. +Frees the `CComVariant` object and then assigns it a copy of the specified `VARIANT`. -``` +```cpp HRESULT Copy(const VARIANT* pSrc); ``` ### Parameters -*pSrc*
-[in] A pointer to the [VARIANT](/windows/win32/api/oaidl/ns-oaidl-variant) to be copied. +*`pSrc`*\ +[in] A pointer to the [`VARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant) to be copied. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. -## CComVariant::CopyTo +## `CComVariant::CopyTo` Copies the contents of the `CComVariant` object. -``` +```cpp HRESULT CopyTo(BSTR* pstrDest); ``` ### Parameters -*pstrDest*
-Points to a BSTR that will receive a copy of the contents of the `CComVariant` object. +*`pstrDest`*\ +Points to a `BSTR` that will receive a copy of the contents of the `CComVariant` object. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -The `CComVariant` object must be of type VT_BSTR. +The `CComVariant` object must be of type `VT_BSTR`. -## CComVariant::Detach +## `CComVariant::Detach` -Detaches the underlying VARIANT from the `CComVariant` object and sets the object's type to VT_EMPTY. +Detaches the underlying `VARIANT` from the `CComVariant` object and sets the object's type to `VT_EMPTY`. -``` +```cpp HRESULT Detach(VARIANT* pDest); ``` ### Parameters -*pDest*
-[out] Returns the underlying VARIANT value of the object. +*`pDest`*\ +[out] Returns the underlying `VARIANT` value of the object. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -Note that the contents of the VARIANT referenced by *pDest* will automatically be cleared before being assigned the value and type of the calling `CComVariant` object. +The contents of the `VARIANT` referenced by *`pDest`* are automatically cleared before being assigned the value and type of the calling `CComVariant` object. -## CComVariant::GetSize +## `CComVariant::GetSize` -For simple-fixed size VARIANTs, this method returns the **`sizeof`** value for the underlying data type plus **sizeof(VARTYPE)**. +For simple-fixed size VARIANTs, this method returns the **`sizeof`** value for the underlying data type plus `sizeof(VARTYPE)`. -``` +```cpp ULONG GetSize() const; ``` -### Return Value +### Return value The size in bytes of the current contents of the `CComVariant` object. ### Remarks -If the VARIANT contains an interface pointer, `GetSize` queries for `IPersistStream` or `IPersistStreamInit`. If successful, the return value is the low-order 32 bits of the value returned by `GetSizeMax` plus `sizeof(CLSID)` and `sizeof(VARTYPE)`. If the interface pointer is NULL, `GetSize` returns `sizeof(CLSID)` plus `sizeof(VARTYPE)`. If the total size is larger than ULONG_MAX, `GetSize` returns `sizeof(VARTYPE)` which indicates an error. +If the `VARIANT` contains an interface pointer, `GetSize` queries for `IPersistStream` or `IPersistStreamInit`. If successful, the return value is the low-order 32 bits of the value returned by `GetSizeMax` plus `sizeof(CLSID)` and `sizeof(VARTYPE)`. If the interface pointer is NULL, `GetSize` returns `sizeof(CLSID)` plus `sizeof(VARTYPE)`. If the total size is larger than `ULONG_MAX`, `GetSize` returns `sizeof(VARTYPE)`, which indicates an error. -In all other cases, a temporary VARIANT of type VT_BSTR is coerced from the current VARIANT. The length of this BSTR is calculated as the size of the length of the string plus the length of the string itself plus the size of the null character plus **sizeof(VARTYPE)**. If the VARIANT cannot be coerced to a VARIANT of type VT_BSTR, `GetSize` returns **sizeof(VARTYPE)**. +In all other cases, a temporary `VARIANT` of type `VT_BSTR` is coerced from the current `VARIANT`. The length of this `BSTR` is calculated as the size of the length of the string plus the length of the string itself plus the size of the null character plus `sizeof(VARTYPE)`. If the `VARIANT` cannot be coerced to a `VARIANT` of type `VT_BSTR`, `GetSize` returns `sizeof(VARTYPE)`. -The size returned by this method matches the number of bytes used by [CComVariant::WriteToStream](#writetostream) under successful conditions. +The size returned by this method matches the number of bytes used by [`CComVariant::WriteToStream`](#writetostream) under successful conditions. -## CComVariant::operator = +## `CComVariant::operator =` Assigns a value and corresponding type to the `CComVariant` object. -``` +```cpp CComVariant& operator=(const CComVariant& varSrc); CComVariant& operator=(const VARIANT& varSrc); CComVariant& operator=(const CComBSTR& bstrSrc); @@ -320,151 +319,151 @@ CComVariant& operator=(char cSrc) throw(); ### Parameters -*varSrc*
-[in] The `CComVariant` or [VARIANT](/windows/win32/api/oaidl/ns-oaidl-variant) to be assigned to the `CComVariant` object. The contents of the source variant are copied to the destination without conversion. +*`varSrc`*\ +[in] The `CComVariant` or [`VARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant) to be assigned to the `CComVariant` object. The contents of the source variant are copied to the destination without conversion. -*bstrSrc*
-[in] The BSTR to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_BSTR. +*`bstrSrc`*\ +[in] The `BSTR` to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_BSTR`. -*lpszSrc*
-[in] The character string to be assigned to the `CComVariant` object. You can pass a zero-terminated wide (Unicode) character string to the LPCOLESTR version of the operator or an ANSI string to the LPCSTR version. In either case, the string is converted to a Unicode BSTR allocated using `SysAllocString`. The type of the `CComVariant` object will be VT_BSTR. +*`lpszSrc`*\ +[in] The character string to be assigned to the `CComVariant` object. You can pass a zero-terminated wide (Unicode) character string to the `LPCOLESTR` version of the operator or an ANSI string to the `LPCSTR` version. In either case, the string is converted to a Unicode `BSTR` allocated using `SysAllocString`. The type of the `CComVariant` object is `VT_BSTR`. -*bSrc*
-[in] The **`bool`** to be assigned to the `CComVariant` object. The **`bool`** argument is converted to a VARIANT_BOOL before being stored. The type of the `CComVariant` object will be VT_BOOL. +*`bSrc`*\ +[in] The **`bool`** to be assigned to the `CComVariant` object. The **`bool`** argument is converted to a `VARIANT_BOOL` before being stored. The type of the `CComVariant` object is `VT_BOOL`. -*nSrc*
-[in] The **`int`**, BYTE, **`short`**, **`long`**, LONGLONG, ULONGLONG, **`unsigned short`**, **`unsigned long`**, or **`unsigned int`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_I4, VT_UI1, VT_I2, VT_I4, VT_I8, VT_UI8, VT_UI2, VT_UI4, or VT_UI4, respectively. +*`nSrc`*\ +[in] The **`int`**, `BYTE`, **`short`**, **`long`**, `LONGLONG`, `ULONGLONG`, **`unsigned short`**, **`unsigned long`**, or **`unsigned int`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_I4`, `VT_UI1`, `VT_I2`, `VT_I4`, `VT_I8`, `VT_UI8`, `VT_UI2`, `VT_UI4`, or `VT_UI4`, respectively. -*fltSrc*
-[in] The **`float`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_R4. +*`fltSrc`*\ +[in] The **`float`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_R4`. -*dblSrc*
-[in] The **`double`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_R8. +*`dblSrc`*\ +[in] The **`double`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_R8`. -*cySrc*
-[in] The `CY` to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_CY. +*`cySrc`*\ +[in] The `CY` to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_CY`. -*pSrc*
-[in] The `IDispatch` or `IUnknown` pointer to be assigned to the `CComVariant` object. `AddRef` will be called on the interface pointer. The type of the `CComVariant` object will be VT_DISPATCH or VT_UNKNOWN, respectively. +*`pSrc`*\ +[in] The `IDispatch` or `IUnknown` pointer to be assigned to the `CComVariant` object. `AddRef` is called on the interface pointer. The type of the `CComVariant` object is `VT_DISPATCH` or `VT_UNKNOWN`, respectively. -Or, a SAFEARRAY pointer to be assigned to the `CComVariant` object. A copy of the SAFEARRAY is stored in the `CComVariant` object. The type of the `CComVariant` object will be a combination of the original type of the SAFEARRAY and VT_ARRAY. +Or, a `SAFEARRAY` pointer to be assigned to the `CComVariant` object. A copy of the `SAFEARRAY` is stored in the `CComVariant` object. The type of the `CComVariant` object is a combination of the original type of the `SAFEARRAY` and `VT_ARRAY`. -*cSrc*
-[in] The char to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_I1. +*`cSrc`*\ +[in] The char to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_I1`. -## CComVariant::operator == +## `CComVariant::operator ==` -Indicates whether the `CComVariant` object equals the specified VARIANT. +Indicates whether the `CComVariant` object equals the specified `VARIANT`. -``` +```cpp bool operator==(const VARIANT& varSrc) const throw(); ``` ### Remarks -Returns TRUE if the value and type of *varSrc* are equal to the value and type, respectively, of the `CComVariant` object. Otherwise, FALSE. The operator uses the user's default locale to perform the comparison. +Returns `TRUE` if the value and type of *`varSrc`* are equal to the value and type, respectively, of the `CComVariant` object. Otherwise, `FALSE`. The operator uses the user's default locale to perform the comparison. The operator compares only the value of the variant types. It compares strings, integers, and floating points, but not arrays or records. -## CComVariant::operator != +## `CComVariant::operator !=` -Indicates whether the `CComVariant` object does not equal the specified VARIANT. +Indicates whether the `CComVariant` object doesn't equal the specified `VARIANT`. -``` +```cpp bool operator!=(const VARIANT& varSrc) const throw(); ``` ### Remarks -Returns TRUE if either the value or type of *varSrc* is not equal to the value or type, respectively, of the `CComVariant` object. Otherwise, FALSE. The operator uses the user's default locale to perform the comparison. +Returns `TRUE` if either the value or type of *`varSrc`* isn't equal to the value or type, respectively, of the `CComVariant` object. Otherwise, `FALSE`. The operator uses the user's default locale to perform the comparison. The operator compares only the value of the variant types. It compares strings, integers, and floating points, but not arrays or records. -## CComVariant::operator < +## `CComVariant::operator <` -Indicates whether the `CComVariant` object is less than the specified VARIANT. +Indicates whether the `CComVariant` object is less than the specified `VARIANT`. -``` +```cpp bool operator<(const VARIANT& varSrc) const throw(); ``` ### Remarks -Returns TRUE if the value of the `CComVariant` object is less than the value of *varSrc*. Otherwise, FALSE. The operator uses the user's default locale to perform the comparison. +Returns `TRUE` if the value of the `CComVariant` object is less than the value of *`varSrc`*. Otherwise, `FALSE`. The operator uses the user's default locale to perform the comparison. -## CComVariant::operator > +## `CComVariant::operator >` -Indicates whether the `CComVariant` object is greater than the specified VARIANT. +Indicates whether the `CComVariant` object is greater than the specified `VARIANT`. -``` +```cpp bool operator>(const VARIANT& varSrc) const throw(); ``` ### Remarks -Returns TRUE if the value of the `CComVariant` object is greater than the value of *varSrc*. Otherwise, FALSE. The operator uses the user's default locale to perform the comparison. +Returns `TRUE` if the value of the `CComVariant` object is greater than the value of *`varSrc`*. Otherwise, `FALSE`. The operator uses the user's default locale to perform the comparison. -## CComVariant::ReadFromStream +## `CComVariant::ReadFromStream` -Sets the underlying VARIANT to the VARIANT contained in the specified stream. +Sets the underlying `VARIANT` to the `VARIANT` contained in the specified stream. -``` +```cpp HRESULT ReadFromStream(IStream* pStream); ``` ### Parameters -*pStream*
-[in] A pointer to the [IStream](/windows/win32/api/objidl/nn-objidl-istream) interface on the stream containing the data. +*`pStream`*\ +[in] A pointer to the [`IStream`](/windows/win32/api/objidl/nn-objidl-istream) interface on the stream containing the data. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -`ReadToStream` requires a previous call to [WriteToStream](#writetostream). +`ReadToStream` requires a previous call to [`WriteToStream`](#writetostream). -## CComVariant::SetByRef +## `CComVariant::SetByRef` -Initializes the `CComVariant` object and sets the `vt` member to VT_BYREF. +Initializes the `CComVariant` object and sets the `vt` member to `VT_BYREF`. -``` +```cpp template < typename T > void SetByRef(T* pT) throw(); ``` ### Parameters -*T*
-The type of VARIANT, for example, BSTR, **`int`**, or **`char`**. +*`T`*\ +The type of `VARIANT`, for example, `BSTR`, **`int`**, or **`char`**. -*pT*
+*`pT`*\ The pointer used to initialize the `CComVariant` object. ### Remarks -`SetByRef` is a function template that initializes the `CComVariant` object to the pointer *pT* and sets the `vt` member to VT_BYREF. For example: +`SetByRef` is a function template that initializes the `CComVariant` object to the pointer *`pT`* and sets the `vt` member to `VT_BYREF`. For example: [!code-cpp[NVC_ATL_Utilities#76](../../atl/codesnippet/cpp/ccomvariant-class_1.cpp)] -## CComVariant::WriteToStream +## `CComVariant::WriteToStream` -Saves the underlying VARIANT to a stream. +Saves the underlying `VARIANT` to a stream. -``` +```cpp HRESULT WriteToStream(IStream* pStream); ``` ### Parameters -*pStream*
-[in] A pointer to the [IStream](/windows/win32/api/objidl/nn-objidl-istream) interface on a stream. +*`pStream`*\ +[in] A pointer to the [`IStream`](/windows/win32/api/objidl/nn-objidl-istream) interface on a stream. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ## See also -[Class Overview](../../atl/atl-class-overview.md) +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/cheapptrbase-class.md b/docs/atl/reference/cheapptrbase-class.md index 41114bb8281..8ba15f0fb65 100644 --- a/docs/atl/reference/cheapptrbase-class.md +++ b/docs/atl/reference/cheapptrbase-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: CHeapPtrBase Class" -title: "CHeapPtrBase Class" +description: "Learn more about: CHeapPtrBase class" +title: "CHeapPtrBase class" ms.date: "11/04/2016" f1_keywords: ["CHeapPtrBase", "ATLCORE/ATL::CHeapPtrBase", "ATLCORE/ATL::CHeapPtrBase::AllocateBytes", "ATLCORE/ATL::CHeapPtrBase::Attach", "ATLCORE/ATL::CHeapPtrBase::Detach", "ATLCORE/ATL::CHeapPtrBase::Free", "ATLCORE/ATL::CHeapPtrBase::ReallocateBytes", "ATLCORE/ATL::CHeapPtrBase::m_pData"] helpviewer_keywords: ["CHeapPtrBase class"] ms.assetid: 501ac1b2-fb34-4c72-b7e6-a4f1fc8fda21 --- -# CHeapPtrBase Class +# `CHeapPtrBase` class This class forms the basis for several smart heap pointer classes. @@ -15,81 +15,81 @@ This class forms the basis for several smart heap pointer classes. ## Syntax -``` +```cpp template class CHeapPtrBase ``` #### Parameters -*T*
+*`T`*\ The object type to be stored on the heap. -*Allocator*
+*`Allocator`*\ The memory allocation class to use. By default CRT routines are used to allocate and free memory. ## Members -### Public Constructors +### Public constructors -|Name|Description| -|----------|-----------------| -|[CHeapPtrBase::~CHeapPtrBase](#dtor)|The destructor.| +| Name | Description | +|--|--| +| [`CHeapPtrBase::~CHeapPtrBase`](#dtor) | The destructor. | -### Public Methods +### Public methods -|Name|Description| -|----------|-----------------| -|[CHeapPtrBase::AllocateBytes](#allocatebytes)|Call this method to allocate memory.| -|[CHeapPtrBase::Attach](#attach)|Call this method to take ownership of an existing pointer.| -|[CHeapPtrBase::Detach](#detach)|Call this method to release ownership of a pointer.| -|[CHeapPtrBase::Free](#free)|Call this method to delete an object pointed to by a `CHeapPtrBase`.| -|[CHeapPtrBase::ReallocateBytes](#reallocatebytes)|Call this method to reallocate memory.| +| Name | Description | +|--|--| +| [`CHeapPtrBase::AllocateBytes`](#allocatebytes) | Call this method to allocate memory. | +| [`CHeapPtrBase::Attach`](#attach) | Call this method to take ownership of an existing pointer. | +| [`CHeapPtrBase::Detach`](#detach) | Call this method to release ownership of a pointer. | +| [`CHeapPtrBase::Free`](#free) | Call this method to delete an object pointed to by a `CHeapPtrBase`. | +| [`CHeapPtrBase::ReallocateBytes`](#reallocatebytes) | Call this method to reallocate memory. | -### Public Operators +### Public operators -|Name|Description| -|----------|-----------------| -|[CHeapPtrBase::operator T*](#operator_t_star)|The cast operator.| -|[CHeapPtrBase::operator &](#operator_amp)|The & operator.| -|[CHeapPtrBase::operator ->](#operator_ptr)|The pointer-to-member operator.| +| Name | Description | +|--|--| +| [`CHeapPtrBase::operator T*`](#operator_t_star) | The cast operator. | +| [`CHeapPtrBase::operator &`](#operator_amp) | The & operator. | +| [`CHeapPtrBase::operator ->`](#operator_ptr) | The pointer-to-member operator. | -### Public Data Members +### Public data members -|Name|Description| -|----------|-----------------| -|[CHeapPtrBase::m_pData](#m_pdata)|The pointer data member variable.| +| Name | Description | +|--|--| +| [`CHeapPtrBase::m_pData`](#m_pdata) | The pointer data member variable. | ## Remarks -This class forms the basis for several smart heap pointer classes. The derived classes, for example, [CHeapPtr](../../atl/reference/cheapptr-class.md) and [CComHeapPtr](../../atl/reference/ccomheapptr-class.md), add their own constructors and operators. See these classes for implementation examples. +This class forms the basis for several smart heap pointer classes. The derived classes, for example, [`CHeapPtr`](../../atl/reference/cheapptr-class.md) and [`CComHeapPtr`](../../atl/reference/ccomheapptr-class.md), add their own constructors and operators. See these classes for implementation examples. ## Requirements **Header:** atlcore.h -## CHeapPtrBase::AllocateBytes +## `CHeapPtrBase::AllocateBytes` Call this method to allocate memory. -``` +```cpp bool AllocateBytes(size_t nBytes) throw(); ``` ### Parameters -*nBytes*
+*`nBytes`*\ The number of bytes of memory to allocate. -### Return Value +### Return value Returns true if the memory is successfully allocated, false otherwise. ### Remarks -In debug builds, an assertion failure will occur if the [CHeapPtrBase::m_pData](#m_pdata) member variable currently points to an existing value; that is, it is not equal to NULL. +In debug builds, an assertion failure will occur if the [`CHeapPtrBase::m_pData`](#m_pdata) member variable currently points to an existing value; that is, it's not equal to NULL. -## CHeapPtrBase::Attach +## `CHeapPtrBase::Attach` Call this method to take ownership of an existing pointer. @@ -99,20 +99,20 @@ void Attach(T* pData) throw(); ### Parameters -*pData*
+*`pData`*\ The `CHeapPtrBase` object will take ownership of this pointer. ### Remarks When a `CHeapPtrBase` object takes ownership of a pointer, it will automatically delete the pointer and any allocated data when it goes out of scope. -In debug builds, an assertion failure will occur if the [CHeapPtrBase::m_pData](#m_pdata) member variable currently points to an existing value; that is, it is not equal to NULL. +In debug builds, an assertion failure will occur if the [`CHeapPtrBase::m_pData`](#m_pdata) member variable currently points to an existing value; that is, it's not equal to NULL. -## CHeapPtrBase::~CHeapPtrBase +## `CHeapPtrBase::~CHeapPtrBase` The destructor. -``` +```cpp ~CHeapPtrBase() throw(); ``` @@ -120,23 +120,23 @@ The destructor. Frees all allocated resources. -## CHeapPtrBase::Detach +## `CHeapPtrBase::Detach` Call this method to release ownership of a pointer. -``` +```cpp T* Detach() throw(); ``` -### Return Value +### Return value Returns a copy of the pointer. ### Remarks -Releases ownership of a pointer, sets the [CHeapPtrBase::m_pData](#m_pdata) member variable to NULL, and returns a copy of the pointer. +Releases ownership of a pointer, sets the [`CHeapPtrBase::m_pData`](#m_pdata) member variable to NULL, and returns a copy of the pointer. -## CHeapPtrBase::Free +## `CHeapPtrBase::Free` Call this method to delete an object pointed to by a `CHeapPtrBase`. @@ -146,13 +146,13 @@ void Free() throw(); ### Remarks -The object pointed to by the `CHeapPtrBase` is freed, and the [CHeapPtrBase::m_pData](#m_pdata) member variable is set to NULL. +The object pointed to by the `CHeapPtrBase` is freed, and the [`CHeapPtrBase::m_pData`](#m_pdata) member variable is set to NULL. -## CHeapPtrBase::m_pData +## `CHeapPtrBase::m_pData` The pointer data member variable. -``` +```cpp T* m_pData; ``` @@ -160,65 +160,65 @@ T* m_pData; This member variable holds the pointer information. -## CHeapPtrBase::operator & +## `CHeapPtrBase::operator &` The & operator. -``` +```cpp T** operator&() throw(); ``` -### Return Value +### Return value Returns the address of the object pointed to by the `CHeapPtrBase` object. -## CHeapPtrBase::operator -> +## `CHeapPtrBase::operator ->` The pointer-to-member operator. -``` +```cpp T* operator->() const throw(); ``` -### Return Value +### Return value -Returns the value of the [CHeapPtrBase::m_pData](#m_pdata) member variable. +Returns the value of the [`CHeapPtrBase::m_pData`](#m_pdata) member variable. ### Remarks Use this operator to call a method in a class pointed to by the `CHeapPtrBase` object. In debug builds, an assertion failure will occur if the `CHeapPtrBase` points to NULL. -## CHeapPtrBase::operator T* +## `CHeapPtrBase::operator T*` The cast operator. -``` +```cpp operator T*() const throw(); ``` ### Remarks -Returns [CHeapPtrBase::m_pData](#m_pdata). +Returns [`CHeapPtrBase::m_pData`](#m_pdata). -## CHeapPtrBase::ReallocateBytes +## `CHeapPtrBase::ReallocateBytes` Call this method to reallocate memory. -``` +```cpp bool ReallocateBytes(size_t nBytes) throw(); ``` ### Parameters -*nBytes*
+*`nBytes`*\ The new amount of memory to allocate, in bytes. -### Return Value +### Return value Returns true if the memory is successfully allocated, false otherwise. ## See also -[CHeapPtr Class](../../atl/reference/cheapptr-class.md)
-[CComHeapPtr Class](../../atl/reference/ccomheapptr-class.md)
-[Class Overview](../../atl/atl-class-overview.md) +[`CHeapPtr` class](../../atl/reference/cheapptr-class.md)\ +[`CComHeapPtr` class](../../atl/reference/ccomheapptr-class.md)\ +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/cpatht-class.md b/docs/atl/reference/cpatht-class.md index 7710ee37f62..32b31a3db12 100644 --- a/docs/atl/reference/cpatht-class.md +++ b/docs/atl/reference/cpatht-class.md @@ -60,14 +60,14 @@ The ATL/MFC string class to use for the path (see [CStringT](../../atl-mfc-share |[CPathT::GetDriveNumber](#getdrivenumber)|Call this method to search the path for a drive letter within the range of 'A' to 'Z' and return the corresponding drive number.| |[CPathT::GetExtension](#getextension)|Call this method to get the file extension from the path.| |[CPathT::IsDirectory](#isdirectory)|Call this method to check whether the path is a valid directory.| -|[CPathT::IsFileSpec](#isfilespec)|Call this method to search a path for any path-delimiting characters (for example, ':' or '\\' ). If there are no path-delimiting characters present, the path is considered to be a File Spec path.| +|[CPathT::IsFileSpec](#isfilespec)|Call this method to search a path for any path-delimiting characters (for example, `:` or `\`). If there are no path-delimiting characters present, the path is considered to be a File Spec path.| |[CPathT::IsPrefix](#isprefix)|Call this method to determine whether a path contains a valid prefix of the type passed by *pszPrefix*.| |[CPathT::IsRelative](#isrelative)|Call this method to determine if the path is relative.| |[CPathT::IsRoot](#isroot)|Call this method to determine if the path is a directory root.| |[CPathT::IsSameRoot](#issameroot)|Call this method to determine whether another path has a common root component with the current path.| |[CPathT::IsUNC](#isunc)|Call this method to determine whether the path is a valid UNC (universal naming convention) path for a server and share.| |[CPathT::IsUNCServer](#isuncserver)|Call this method to determine whether the path is a valid UNC (universal naming convention) path for a server only.| -|[CPathT::IsUNCServerShare](#isuncservershare)|Call this method to determine whether the path is a valid UNC (universal naming convention) share path, \\\ *server*\ *share*.| +|[CPathT::IsUNCServerShare](#isuncservershare)|Call this method to determine whether the path is a valid UNC (universal naming convention) share path, *`\\server\share`*.| |[CPathT::MakePretty](#makepretty)|Call this method to convert a path to all lowercase characters to give the path a consistent appearance.| |[CPathT::MatchSpec](#matchspec)|Call this method to search the path for a string containing a wildcard match type.| |[CPathT::QuoteSpaces](#quotespaces)|Call this method to enclose the path in quotation marks if it contains any spaces.| @@ -177,7 +177,7 @@ void BuildRoot(int iDrive); ### Parameters *iDrive*
-The drive number (0 is A:, 1 is B:, and so on). +The drive number (0 is *`A:`*, 1 is *`B:`*, and so on). ### Remarks @@ -396,7 +396,7 @@ For more information, see [PathIsDirectory](/windows/win32/api/shlwapi/nf-shlwap ## CPathT::IsFileSpec -Call this method to search a path for any path-delimiting characters (for example, ':' or '\\' ). If there are no path-delimiting characters present, the path is considered to be a File Spec path. +Call this method to search a path for any path-delimiting characters (for example, `:` or `\`). If there are no path-delimiting characters present, the path is considered to be a File Spec path. ``` BOOL IsFileSpec() const; diff --git a/docs/atl/reference/csid-class.md b/docs/atl/reference/csid-class.md index 3306d493950..49be86aa613 100644 --- a/docs/atl/reference/csid-class.md +++ b/docs/atl/reference/csid-class.md @@ -1,79 +1,79 @@ --- -description: "Learn more about: CSid Class" -title: "CSid Class" +description: "Learn more about: CSid class" +title: "CSid class" ms.date: "03/27/2019" f1_keywords: ["CSid", "ATLSECURITY/ATL::CSid", "ATLSECURITY/ATL::CSid::CSidArray", "ATLSECURITY/ATL::CSid::CSid", "ATLSECURITY/ATL::CSid::AccountName", "ATLSECURITY/ATL::CSid::Domain", "ATLSECURITY/ATL::CSid::EqualPrefix", "ATLSECURITY/ATL::CSid::GetLength", "ATLSECURITY/ATL::CSid::GetPSID", "ATLSECURITY/ATL::CSid::GetPSID_IDENTIFIER_AUTHORITY", "ATLSECURITY/ATL::CSid::GetSubAuthority", "ATLSECURITY/ATL::CSid::GetSubAuthorityCount", "ATLSECURITY/ATL::CSid::IsValid", "ATLSECURITY/ATL::CSid::LoadAccount", "ATLSECURITY/ATL::CSid::Sid", "ATLSECURITY/ATL::CSid::SidNameUse"] helpviewer_keywords: ["CSid class"] ms.assetid: be58b7ca-5958-49c3-a833-ca341aaaf753 --- -# CSid Class +# `CSid` class This class is a wrapper for a `SID` (security identifier) structure. > [!IMPORTANT] -> This class and its members cannot be used in applications that execute in the Windows Runtime. +> This class and its members can't be used in applications that execute in the Windows Runtime. ## Syntax -``` -class CSid +```cpp +class CSid; ``` ## Members -### Public Typedefs +### Public typedefs -|Name|Description| -|----------|-----------------| -|[CSid::CSidArray](#csidarray)|An array of `CSid` objects.| +| Name | Description | +|--|--| +| [`CSid::CSidArray`](#csidarray) | An array of `CSid` objects. | -### Public Constructors +### Public constructors -|Name|Description| -|----------|-----------------| -|[CSid::CSid](#csid)|The constructor.| -|[CSid::~CSid](#dtor)|The destructor.| +| Name | Description | +|--|--| +| [`CSid::CSid`](#csid) | The constructor. | +| [`CSid::~CSid`](#dtor) | The destructor. | -### Public Methods +### Public methods -|Name|Description| -|----------|-----------------| -|[CSid::AccountName](#accountname)|Returns the name of the account associated with the `CSid` object.| -|[CSid::Domain](#domain)|Returns the name of the domain associated with the `CSid` object.| -|[CSid::EqualPrefix](#equalprefix)|Tests `SID` (security identifier) prefixes for equality.| -|[CSid::GetLength](#getlength)|Returns the length of the `CSid` object.| -|[CSid::GetPSID](#getpsid)|Returns a pointer to a `SID` structure.| -|[CSid::GetPSID_IDENTIFIER_AUTHORITY](#getpsid_identifier_authority)|Returns a pointer to the `SID_IDENTIFIER_AUTHORITY` structure.| -|[CSid::GetSubAuthority](#getsubauthority)|Returns a specified subauthority in a `SID` structure.| -|[CSid::GetSubAuthorityCount](#getsubauthoritycount)|Returns the subauthority count.| -|[CSid::IsValid](#isvalid)|Tests the `CSid` object for validity.| -|[CSid::LoadAccount](#loadaccount)|Updates the `CSid` object given the account name and domain, or an existing `SID` structure.| -|[CSid::Sid](#sid)|Returns the ID string.| -|[CSid::SidNameUse](#sidnameuse)|Returns a description of the state of the `CSid` object.| +| Name | Description | +|--|--| +| [`CSid::AccountName`](#accountname) | Returns the name of the account associated with the `CSid` object. | +| [`CSid::Domain`](#domain) | Returns the name of the domain associated with the `CSid` object. | +| [`CSid::EqualPrefix`](#equalprefix) | Tests `SID` (security identifier) prefixes for equality. | +| [`CSid::GetLength`](#getlength) | Returns the length of the `CSid` object. | +| [`CSid::GetPSID`](#getpsid) | Returns a pointer to a `SID` structure. | +| [`CSid::GetPSID_IDENTIFIER_AUTHORITY`](#getpsid_identifier_authority) | Returns a pointer to the `SID_IDENTIFIER_AUTHORITY` structure. | +| [`CSid::GetSubAuthority`](#getsubauthority) | Returns a specified subauthority in a `SID` structure. | +| [`CSid::GetSubAuthorityCount`](#getsubauthoritycount) | Returns the subauthority count. | +| [`CSid::IsValid`](#isvalid) | Tests the `CSid` object for validity. | +| [`CSid::LoadAccount`](#loadaccount) | Updates the `CSid` object given the account name and domain, or an existing `SID` structure. | +| [`CSid::Sid`](#sid) | Returns the ID string. | +| [`CSid::SidNameUse`](#sidnameuse) | Returns a description of the state of the `CSid` object. | ### Operators -|Name|Description| -|-|-| -|[operator =](#operator_eq)|Assignment operator.| -|[operator const SID *](#operator_const_sid__star)|Casts a `CSid` object to a pointer to a `SID` structure.| +| Name | Description | +|--|--| +| [`CSid::operator =`](#operator_eq) | Assignment operator. | +| [`CSid::operator const SID *`](#operator_const_sid__star) | Casts a `CSid` object to a pointer to a `SID` structure. | ### Global Operators -|Name|Description| -|-|-| -|[operator ==](#operator_eq_eq)|Tests two security descriptor objects for equality| -|[operator !=](#operator_neq)|Tests two security descriptor objects for inequality| -|[operator \<](#operator_lt)|Compares relative value of two security descriptor objects.| -|[operator >](#operator_gt)|Compares relative value of two security descriptor objects.| -|[operator \<=](#operator_lt__eq)|Compares relative value of two security descriptor objects.| -|[operator >=](#operator_gt__eq)|Compares relative value of two security descriptor objects.| +| Name | Description | +|--|--| +| [`operator ==`](#operator_eq_eq) | Tests two security descriptor objects for equality | +| [`operator !=`](#operator_neq) | Tests two security descriptor objects for inequality | +| [`operator <`](#operator_lt) | Compares relative value of two security descriptor objects. | +| [`operator >`](#operator_gt) | Compares relative value of two security descriptor objects. | +| [`operator <=`](#operator_lt__eq) | Compares relative value of two security descriptor objects. | +| [`operator >=`](#operator_gt__eq) | Compares relative value of two security descriptor objects. | ## Remarks The `SID` structure is a variable-length structure used to uniquely identify users or groups. -Applications should not modify the `SID` structure directly, but instead use the methods provided in this wrapper class. See also [AtlGetOwnerSid](security-global-functions.md#atlgetownersid), [AtlSetGroupSid](security-global-functions.md#atlsetgroupsid), [AtlGetGroupSid](security-global-functions.md#atlgetgroupsid), and [AtlSetOwnerSid](security-global-functions.md#atlsetownersid). +Applications shouldn't modify the `SID` structure directly, but instead use the methods provided in this wrapper class. See also [`AtlGetOwnerSid`](security-global-functions.md#atlgetownersid), [`AtlSetGroupSid`](security-global-functions.md#atlsetgroupsid), [`AtlGetGroupSid`](security-global-functions.md#atlgetgroupsid), and [`AtlSetOwnerSid`](security-global-functions.md#atlsetownersid). For an introduction to the access control model in Windows, see [Access Control](/windows/win32/SecAuthZ/access-control) in the Windows SDK. @@ -81,29 +81,29 @@ For an introduction to the access control model in Windows, see [Access Control] **Header:** atlsecurity.h -## CSid::AccountName +## `CSid::AccountName` Returns the name of the account associated with the `CSid` object. -``` +```cpp LPCTSTR AccountName() const throw(...); ``` -### Return Value +### Return value -Returns the LPCTSTR pointing to the name of the account. +Returns the `LPCTSTR` pointing to the name of the account. ### Remarks -This method attempts to find a name for the specified `SID` (security identifier). For full details, see [LookupAccountSid](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). +This method attempts to find a name for the specified `SID` (security identifier). For full details, see [`LookupAccountSid`](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). -If no account name for the `SID` can be found, `AccountName` returns an empty string. This can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as an `SID` that identifies a sign-in session. +If no account name for the `SID` can be found, `AccountName` returns an empty string. This result can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as an `SID` that identifies a sign-in session. -## CSid::CSid +## `CSid::CSid` The constructor. -``` +```cpp CSid() throw(); CSid(const SID& rhs) throw(...); CSid(const CSid& rhs) throw(...); @@ -124,35 +124,35 @@ explicit CSid( ### Parameters -*rhs*
+*`rhs`*\ An existing `CSid` object or `SID` (security identifier) structure. -*IdentifierAuthority*
+*`IdentifierAuthority`*\ The authority. -*nSubAuthorityCount*
+*`nSubAuthorityCount`*\ The subauthority count. -*pszAccountName*
+*`pszAccountName`*\ The account name. -*pszSystem*
+*`pszSystem`*\ The system name. This string can be the name of a remote computer. If this string is NULL, the local system is used instead. -*pSid*
+*`pSid`*\ A pointer to a `SID` structure. ### Remarks -The constructor initializes the `CSid` object, setting an internal data member to *SidTypeInvalid*, or by copying the settings from an existing `CSid`, `SID`, or existing account. +The constructor initializes the `CSid` object, setting an internal data member to *`SidTypeInvalid`*, or by copying the settings from an existing `CSid`, `SID`, or existing account. -If initialization fails, the constructor will throw a [CAtlException Class](../../atl/reference/catlexception-class.md). +If initialization fails, the constructor will throw a [`CAtlException` Class](../../atl/reference/catlexception-class.md). -## CSid::~CSid +## `CSid::~CSid` The destructor. -``` +```cpp virtual ~CSid() throw(); ``` @@ -160,166 +160,166 @@ virtual ~CSid() throw(); The destructor frees any resources acquired by the object. -## CSid::CSidArray +## `CSid::CSidArray` -An array of [CSid](../../atl/reference/csid-class.md) objects. +An array of [`CSid`](../../atl/reference/csid-class.md) objects. -``` +```cpp typedef CAtlArray CSidArray; ``` ### Remarks -This typedef specifies the array type that can be used to retrieve security identifiers from an ACL (access-control list). See [CAcl::GetAclEntries](../../atl/reference/cacl-class.md#getaclentries). +This typedef specifies the array type that can be used to retrieve security identifiers from an ACL (access-control list). See [`CAcl::GetAclEntries`](../../atl/reference/cacl-class.md#getaclentries). -## CSid::Domain +## `CSid::Domain` Returns the name of the domain associated with the `CSid` object. -``` +```cpp LPCTSTR Domain() const throw(...); ``` -### Return Value +### Return value Returns the `LPCTSTR` pointing to the domain. ### Remarks -This method attempts to find a name for the specified `SID` (security identifier). For full details, see [LookupAccountSid](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). +This method attempts to find a name for the specified `SID` (security identifier). For full details, see [`LookupAccountSid`](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). -If no account name for the `SID` can be found, `Domain` returns the domain as an empty string. This can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as an `SID` that identifies a sign-in session. +If no account name for the `SID` can be found, `Domain` returns the domain as an empty string. This result can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as an `SID` that identifies a sign-in session. -## CSid::EqualPrefix +## `CSid::EqualPrefix` Tests `SID` (security identifier) prefixes for equality. -``` +```cpp bool EqualPrefix(const SID& rhs) const throw(); bool EqualPrefix(const CSid& rhs) const throw(); ``` ### Parameters -*rhs*
+*`rhs`*\ The `SID` (security identifier) structure or `CSid` object to compare. -### Return Value +### Return value -Returns TRUE on success, FALSE on failure. +Returns `TRUE` on success, `FALSE` on failure. ### Remarks -See [EqualPrefixSid](/windows/win32/api/securitybaseapi/nf-securitybaseapi-equalprefixsid) in the Windows SDK for more details. +For more information, see [`EqualPrefixSid`](/windows/win32/api/securitybaseapi/nf-securitybaseapi-equalprefixsid). -## CSid::GetLength +## `CSid::GetLength` Returns the length of the `CSid` object. -``` +```cpp UINT GetLength() const throw(); ``` -### Return Value +### Return value Returns the length in bytes of the `CSid` object. ### Remarks -If the `CSid` structure is not valid, the return value is undefined. Before calling `GetLength`, use the [CSid::IsValid](#isvalid) member function to verify that `CSid` is valid. +If the `CSid` structure isn't valid, the return value is undefined. Before calling `GetLength`, use the [`CSid::IsValid`](#isvalid) member function to verify that `CSid` is valid. > [!NOTE] -> Under debug builds the function will cause an ASSERT if the `CSid` object is not valid. +> Under debug builds the function will cause an ASSERT if the `CSid` object isn't valid. -## CSid::GetPSID +## `CSid::GetPSID` Returns a pointer to a `SID` (security identifier) structure. -``` +```cpp const SID* GetPSID() const throw(...); ``` -### Return Value +### Return value Returns the address of the `CSid` object's underlying `SID` structure. -## CSid::GetPSID_IDENTIFIER_AUTHORITY +## `CSid::GetPSID_IDENTIFIER_AUTHORITY` Returns a pointer to the `SID_IDENTIFIER_AUTHORITY` structure. -``` +```cpp const SID_IDENTIFIER_AUTHORITY* GetPSID_IDENTIFIER_AUTHORITY() const throw(); ``` -### Return Value +### Return value -If the method succeeds, it returns the address of the `SID_IDENTIFIER_AUTHORITY` structure. If it fails, the return value is undefined. Failure may occur if the `CSid` object is not valid, in which case the [CSid::IsValid](#isvalid) method returns FALSE. The function `GetLastError` can be called for extended error information. +If the method succeeds, it returns the address of the `SID_IDENTIFIER_AUTHORITY` structure. If it fails, the return value is undefined. Failure may occur if the `CSid` object isn't valid, in which case the [`CSid::IsValid`](#isvalid) method returns `FALSE`. The function `GetLastError` can be called for extended error information. > [!NOTE] -> Under debug builds the function will cause an ASSERT if the `CSid` object is not valid. +> Under debug builds the function will cause an ASSERT if the `CSid` object isn't valid. -## CSid::GetSubAuthority +## `CSid::GetSubAuthority` Returns a specified subauthority in a `SID` (security identifier) structure. -``` +```cpp DWORD GetSubAuthority(DWORD nSubAuthority) const throw(); ``` ### Parameters -*nSubAuthority*
+*`nSubAuthority`*\ The subauthority. -### Return Value +### Return value -Returns the subauthority referenced by *nSubAuthority.* The subauthority value is a relative identifier (RID). +Returns the subauthority referenced by *`nSubAuthority`*. The subauthority value is a relative identifier (RID). ### Remarks -The *nSubAuthority* parameter specifies an index value identifying the subauthority array element the method will return. The method performs no validation tests on this value. An application can call [CSid::GetSubAuthorityCount](#getsubauthoritycount) to discover the range of acceptable values. +The *`nSubAuthority`* parameter specifies an index value identifying the subauthority array element the method will return. The method performs no validation tests on this value. An application can call [`CSid::GetSubAuthorityCount`](#getsubauthoritycount) to discover the range of acceptable values. > [!NOTE] -> Under debug builds the function will cause an ASSERT if the `CSid` object is not valid. +> Under debug builds the function will cause an ASSERT if the `CSid` object isn't valid. -## CSid::GetSubAuthorityCount +## `CSid::GetSubAuthorityCount` Returns the subauthority count. -``` +```cpp UCHAR GetSubAuthorityCount() const throw(); ``` -### Return Value +### Return value If the method succeeds, the return value is the subauthority count. If the method fails, the return value is undefined. The method fails if the `CSid` object is invalid. To get extended error information, call `GetLastError`. > [!NOTE] -> Under debug builds the function will cause an ASSERT if the `CSid` object is not valid. +> Under debug builds the function will cause an ASSERT if the `CSid` object isn't valid. -## CSid::IsValid +## `CSid::IsValid` Tests the `CSid` object for validity. -``` +```cpp bool IsValid() const throw(); ``` -### Return Value +### Return value -Returns TRUE if the `CSid` object is valid, FALSE if not. There is no extended error information for this method; do not call `GetLastError`. +Returns `TRUE` if the `CSid` object is valid, `FALSE` if not. There's no extended error information for this method; don't call `GetLastError`. ### Remarks The `IsValid` method validates the `CSid` object by verifying that the revision number is within a known range and that the number of subauthorities is less than the maximum. -## CSid::LoadAccount +## `CSid::LoadAccount` -Updates the `CSid` object given the account name and domain, or an existing SID (security identifier) structure. +Updates the `CSid` object given the account name and domain, or an existing `SID` (security identifier) structure. -``` +```cpp bool LoadAccount( LPCTSTR pszAccountName, LPCTSTR pszSystem = NULL) throw(...); @@ -331,46 +331,46 @@ bool LoadAccount( ### Parameters -*pszAccountName*
+*`pszAccountName`*\ The account name. -*pszSystem*
+*`pszSystem`*\ The system name. This string can be the name of a remote computer. If this string is NULL, the local system is used instead. -*pSid*
-A pointer to a [SID](/windows/win32/api/winnt/ns-winnt-sid) structure. +*`pSid`*\ +A pointer to a [`SID`](/windows/win32/api/winnt/ns-winnt-sid) structure. -### Return Value +### Return value -Returns TRUE on success, FALSE on failure. To get extended error information, call `GetLastError`. +Returns `TRUE` on success, `FALSE` on failure. To get extended error information, call `GetLastError`. ### Remarks -`LoadAccount` attempts to find a security identifier for the specified name. See [LookupAccountSid](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw) for more details. +`LoadAccount` attempts to find a security identifier for the specified name. For more information, see [`LookupAccountSid`](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). -## CSid::operator = +## `CSid::operator =` Assignment operator. -``` +```cpp CSid& operator= (const CSid& rhs) throw(...); CSid& operator= (const SID& rhs) throw(...); ``` ### Parameters -*rhs*
+*`rhs`*\ The `SID` (security identifier) or `CSid` to assign to the `CSid` object. -### Return Value +### Return value Returns a reference to the updated `CSid` object. -## CSid::operator == +## `operator ==` Tests two security descriptor objects for equality. -``` +```cpp bool operator==( const CSid& lhs, const CSid& rhs) throw(); @@ -378,21 +378,21 @@ bool operator==( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the == operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`==`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the == operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`==`** operator. -### Return Value +### Return value -TRUE if the security descriptors are equal, otherwise FALSE. +`TRUE` if the security descriptors are equal, otherwise `FALSE`. -## CSid::operator != +## `operator !=` Tests two security descriptor objects for inequality. -``` +```cpp bool operator!=( const CSid& lhs, const CSid& rhs) throw(); @@ -400,21 +400,21 @@ bool operator!=( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`!=`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`!=`** operator. -### Return Value +### Return value -TRUE if the security descriptors are not equal, otherwise FALSE. +`TRUE` if the security descriptors aren't equal, otherwise `FALSE`. -## CSid::operator < +## `operator <` Compares relative value of two security descriptor objects. -``` +```cpp bool operator<( const CSid& lhs, const CSid& rhs) throw(); @@ -422,21 +422,21 @@ bool operator<( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`<`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`<`** operator. -### Return Value +### Return value -TRUE if *lhs* is less than *rhs*, otherwise FALSE. +`TRUE` if *`lhs`* is less than *`rhs`*, otherwise `FALSE`. -## CSid::operator <= +## `operator <=` Compares relative value of two security descriptor objects. -``` +```cpp bool operator<=( const CSid& lhs, const CSid& rhs) throw(); @@ -444,21 +444,21 @@ bool operator<=( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`<=`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`<=`** operator. -### Return Value +### Return value -TRUE if *lhs* is less than or equal to *rhs*, otherwise FALSE. +`TRUE` if *`lhs`* is less than or equal to *`rhs`*, otherwise `FALSE`. -## CSid::operator > +## `operator >` Compares relative value of two security descriptor objects. -``` +```cpp bool operator>( const CSid& lhs, const CSid& rhs) throw(); @@ -466,21 +466,21 @@ bool operator>( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`>`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`>`** operator. -### Return Value +### Return value -TRUE if *lhs* is greater than *rhs*, otherwise FALSE. +`TRUE` if *`lhs`* is greater than *`rhs`*, otherwise `FALSE`. -## CSid::operator >= +## `operator >=` Compares relative value of two security descriptor objects. -``` +```cpp bool operator>=( const CSid& lhs, const CSid& rhs) throw()); @@ -488,71 +488,71 @@ bool operator>=( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`>=`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`>=`** operator. -### Return Value +### Return value -TRUE if *lhs* is greater than or equal to *rhs*, otherwise FALSE. +`TRUE` if *`lhs`* is greater than or equal to *`rhs`*, otherwise `FALSE`. -## CSid::operator const SID \* +## `CSid::operator const SID *` Casts a `CSid` object to a pointer to a `SID` (security identifier) structure. -``` -operator const SID *() const throw(...); +```cpp +operator const SID *() const; ``` ### Remarks Returns the address of the `SID` structure. -## CSid::Sid +## `CSid::Sid` Returns the `SID` (security identifier) structure as a string. -``` +```cpp LPCTSTR Sid() const throw(...); ``` -### Return Value +### Return value -Returns the `SID` structure as a string in a format suitable for display, storage, or transmission. Equivalent to [ConvertSidToStringSid](/windows/win32/api/sddl/nf-sddl-convertsidtostringsidw). +Returns the `SID` structure as a string in a format suitable for display, storage, or transmission. Equivalent to [`ConvertSidToStringSid`](/windows/win32/api/sddl/nf-sddl-convertsidtostringsidw). -## CSid::SidNameUse +## `CSid::SidNameUse` Returns a description of the state of the `CSid` object. -``` +```cpp SID_NAME_USE SidNameUse() const throw(); ``` -### Return Value +### Return value Returns the value of the data member that stores a value describing the state of the `CSid` object. -|Value|Description| -|-----------|-----------------| -|SidTypeUser|Indicates a user `SID` (security identifier).| -|SidTypeGroup|Indicates a group `SID`.| -|SidTypeDomain|Indicates a domain `SID`.| -|SidTypeAlias|Indicates an alias `SID`.| -|SidTypeWellKnownGroup|Indicates a `SID` for a well-known group.| -|SidTypeDeletedAccount|Indicates a `SID` for a deleted account.| -|SidTypeInvalid|Indicates an invalid `SID`.| -|SidTypeUnknown|Indicates an unknown `SID` type.| -|SidTypeComputer|Indicates a `SID` for a computer.| +| Value | Description | +|--|--| +| SidTypeUser | Indicates a user `SID` (security identifier). | +| SidTypeGroup | Indicates a group `SID`. | +| SidTypeDomain | Indicates a domain `SID`. | +| SidTypeAlias | Indicates an alias `SID`. | +| SidTypeWellKnownGroup | Indicates a `SID` for a well-known group. | +| SidTypeDeletedAccount | Indicates a `SID` for a deleted account. | +| SidTypeInvalid | Indicates an invalid `SID`. | +| SidTypeUnknown | Indicates an unknown `SID` type. | +| SidTypeComputer | Indicates a `SID` for a computer. | ### Remarks -Call [CSid::LoadAccount](#loadaccount) to update the `CSid` object before calling `SidNameUse` to return its state. `SidNameUse` does not change the state of the object (by calling to `LookupAccountName` or `LookupAccountSid`), but only returns the current state. +Call [`CSid::LoadAccount`](#loadaccount) to update the `CSid` object before calling `SidNameUse` to return its state. `SidNameUse` doesn't change the state of the object (by calling to `LookupAccountName` or `LookupAccountSid`), but only returns the current state. ## See also -[Security Sample](../../overview/visual-cpp-samples.md)
-[Class Overview](../../atl/atl-class-overview.md)
-[Security Global Functions](../../atl/reference/security-global-functions.md)
+[Security sample](../../overview/visual-cpp-samples.md)\ +[Class overview](../../atl/atl-class-overview.md)\ +[Security global functions](../../atl/reference/security-global-functions.md)\ [Operators](../../atl/reference/atl-operators.md) diff --git a/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md b/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md index 5b02d58d9d7..b85c149a468 100644 --- a/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md +++ b/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md @@ -16,6 +16,7 @@ The platform toolset consists of the C++ compiler (cl.exe) and linker (link.exe) - Visual Studio 2015: v140 - Visual Studio 2017: v141 - Visual Studio 2019: v142 +- Visual Studio 2022: v143 These toolsets support the .NET Framework 4.5 and later. diff --git a/docs/build/reference/c-visual-cpp.md b/docs/build/reference/c-visual-cpp.md index 985f3dd8ad6..ebfab859c0a 100644 --- a/docs/build/reference/c-visual-cpp.md +++ b/docs/build/reference/c-visual-cpp.md @@ -1,29 +1,29 @@ --- -description: "Learn more about: <c>" -title: "<c> (C++ documentation comments)" +description: "Learn more about: XML documentation tag " +title: " (C++ documentation comments)" ms.date: "11/04/2016" f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "c C++ XML tag"] ms.assetid: 3b23fc0f-e10d-4dd0-b197-48a46cbddd9f --- -# <c> +# `` documentation tag -The \ tag indicates that text within a description should be marked as code. Use [\](code-visual-cpp.md) to indicate multiple lines as code. +The `` tag indicates that text within a description should be marked as code. Use [``](code-visual-cpp.md) to indicate multiple lines as code. ## Syntax -``` -text +```cpp +/// text ``` -#### Parameters +### Parameters -*text*
+*`text`*\ The text you want to indicate as code. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -48,4 +48,4 @@ public: ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/code-visual-cpp.md b/docs/build/reference/code-visual-cpp.md index cba638edb9c..baeb3355fdf 100644 --- a/docs/build/reference/code-visual-cpp.md +++ b/docs/build/reference/code-visual-cpp.md @@ -1,36 +1,41 @@ --- -description: "Learn more about: <code>" +description: "Learn more about: XML Documentation tag " title: "<code> (C++ documentation comments)" ms.date: "11/04/2016" f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "code C++ XML tag"] ms.assetid: 687db3f8-d435-4a90-b781-8da503fa39bc --- -# <code> +# `` documentation tag -The \ tag gives you a way to indicate one or more lines as code. +The `` tag gives you a way to indicate one or more lines as code. ## Syntax -``` -content +```cpp +/// content + +/// +/// content +/// content +/// ``` -#### Parameters +### Parameters -*content*
+*`content`*\ The text you want marked as code. ## Remarks -Use [\](c-visual-cpp.md) to indicate a portion of text should be marked as code. +Use [``](c-visual-cpp.md) to indicate a portion of text should be marked as code. -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example -See the [\](example-visual-cpp.md) topic for an example of how to use the \ tag. +For an example of how to use the `` tag, see [``](example-visual-cpp.md). ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/example-visual-cpp.md b/docs/build/reference/example-visual-cpp.md index 476048e4e39..ae2293c4997 100644 --- a/docs/build/reference/example-visual-cpp.md +++ b/docs/build/reference/example-visual-cpp.md @@ -1,29 +1,29 @@ --- -description: "Learn more about: <example>" +description: "Learn more about: XML documentation tag " title: "<example> (C++ documentation comments)" ms.date: "11/04/2016" f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "example C++ XML tag"] ms.assetid: c821aaa7-7ea7-4bee-9922-6705ad57f877 --- -# <example> +# `` documentation tag -The \ tag lets you specify an example of how to use a method or other library member. Commonly, this would also involve use of the [\](code-visual-cpp.md) tag. +The `` tag lets you specify an example of how to use a method or other library member. Commonly, use of this tag would also involve the [``](code-visual-cpp.md) tag. ## Syntax -``` -description +```cpp +/// description ``` -#### Parameters +### Parameters -*description*
+*`description`*\ A description of the code sample. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -54,4 +54,4 @@ public: ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/exception-visual-cpp.md b/docs/build/reference/exception-visual-cpp.md index b0e291b5cb9..0e047d8a41d 100644 --- a/docs/build/reference/exception-visual-cpp.md +++ b/docs/build/reference/exception-visual-cpp.md @@ -1,37 +1,37 @@ --- -description: "Learn more about: <exception> tag" -title: "<exception> (C++ documentation comments)" +description: "Learn more about: XML documentation tag " +title: " (C++ documentation comments)" ms.date: "11/04/2016" helpviewer_keywords: [" C++ XML tag", "exception C++ XML tag"] ms.assetid: 24451e79-9b89-4b77-98fb-702c6516b818 --- -# <exception> tag +# `` documentation tag -The \ tag lets you specify which exceptions can be thrown. This tag is applied to a method definition. +The `` tag lets you specify which exceptions can be thrown. This tag is applied to a method definition. ## Syntax -``` -description +```cpp +/// description ``` -#### Parameters +### Parameters -*member*
-A reference to an exception that is available from the current compilation environment. Using name lookup rules, the compiler checks that the given exception exists, and translates `member` to the canonical element name in the output XML. The compiler issues a warning if it does not find `member`. +*`member`*\ +A reference to an exception that's available from the current compilation environment. Using name lookup rules, the compiler checks that the given exception exists, and translates `member` to the canonical element name in the output XML. The compiler issues a warning if it doesn't find `member`. Enclose the name in single or double quotation marks. -For information on how to create a cref reference to a generic type, see [\](see-visual-cpp.md). +For more information on how to create a `cref` reference to a generic type, see [``](see-visual-cpp.md). -*description*
+*`description`*\ A description. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. -The MSVC compiler will attempt to resolve cref references in one pass through the documentation comments. Therefore, if using the C++ lookup rules, a symbol is not found by the compiler the reference will be marked as unresolved. See [\](seealso-visual-cpp.md) for more information. +The MSVC compiler attempts to resolve `cref` references in one pass through the documentation comments. If using the C++ lookup rules, when a symbol isn't found by the compiler the reference is marked as unresolved. For more information, see [``](seealso-visual-cpp.md). ## Example @@ -59,4 +59,4 @@ public ref class TestClass { ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/fpcvt.md b/docs/build/reference/fpcvt.md index 16cfc9a5d91..031b38e42e6 100644 --- a/docs/build/reference/fpcvt.md +++ b/docs/build/reference/fpcvt.md @@ -30,7 +30,7 @@ In Visual Studio 2019 version 16.8 and later versions, the **`/fpcvt`** compiler For Visual Studio 2019, the default behavior for x64 targets is consistent with **`/fpcvt:BC`** unless **`/arch:AVX512`** is specified. Usually, the behavior for x86 targets is consistent with **`/fpcvt:IA`**, except under **`/arch:IA32`**, **`/arch:SSE`**, or sometimes where the result of a function call is directly converted to an unsigned integer. Use of **`/fpcvt`** overrides the default, so all conversions are handled consistently on either target. The behavior of conversions for ARM and ARM64 targets isn't consistent with either **`/fpcvt:BC`** or **`/fpcvt:IA`**. -Standard C++ specifies that if a floating-point value can be exactly represented in an integer type, conversion from floating-point to that integer type must return that value. Otherwise, any behavior at all is allowed. Both **`/fpcvt`** options conform with Standard C++. The only difference is in what values are returned for invalid source values. +Standard C++ specifies that if a floating-point value can be truncated to a value that can be exactly represented in an integer type, conversion of that floating-point value to that integer type must return the truncated value. Otherwise, any behavior at all is allowed. Both **`/fpcvt`** options conform with Standard C++. The only difference is in what values are returned for invalid source values. The **`/fpcvt:IA`** option causes any invalid conversion to return a single *sentinel* value, which is the destination value farthest from zero. For conversion to signed types, the sentinel is the minimum value for that type. Unsigned types use the maximum value. Floating-point operations may return a Not-a-Number (NaN) value to indicate an invalid operation. That's not an option for conversion to integer types, which don't have NaN values. The sentinel is used as a proxy for a NaN value, although it can also be the result of a valid conversion. diff --git a/docs/build/reference/include-visual-cpp.md b/docs/build/reference/include-visual-cpp.md index 43276ff176b..49c281b1280 100644 --- a/docs/build/reference/include-visual-cpp.md +++ b/docs/build/reference/include-visual-cpp.md @@ -1,44 +1,44 @@ --- -description: "Learn more about: <include>" +description: "Learn more about: XML documentation tag " title: "<include> (C++ documentation comments)" ms.date: "11/04/2016" f1_keywords: [""] helpviewer_keywords: ["include C++ XML tag", " C++ XML tag"] ms.assetid: 392a3e61-0371-4617-8362-446650876ce3 --- -# <include> +# `` documentation tag -The \ tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file. For example, you can use \ to insert standard "boilerplate" comments that are used throughout your team or company. +The `` tag lets you refer to comments in another file that describe the types and members in your source code. This tag is an alternative to placing documentation comments directly in your source code file. For example, you can use `` to insert standard "boilerplate" comments that are used throughout your team or company. ## Syntax -``` - +```cpp +/// ``` -#### Parameters +### Parameters -*filename*
-The name of the file containing the documentation. The file name can be qualified with a path. Enclose the name in single or double quotation marks. The compiler issues a warning if it does not find `filename`. +*`filename`*\ +The name of the file containing the documentation. The file name can be qualified with a path. Enclose the name in single or double quotation marks. The compiler issues a warning if it doesn't find *`filename`*. -*tagpath*
-A valid XPath expression that selects the desired node-set contained in the file. +*`tag-path`*\ +A valid XPath expression that selects the wanted node-set contained in the file. -*name*
-The name specifier in the tag that precedes the comments; `name` will have an `id`. +*`name`*\ +The name specifier in the tag that precedes the comments; *`name`* will have an *`ID`*. -*id*
-The ID for the tag that precedes the comments. Enclose the name in single or double quotation marks. +*`ID`*\ +The ID for the tag that precedes the comments. Enclose the ID in single or double quotation marks. ## Remarks -The \ tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize using \. +The `` tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize using ``. -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example -This is a multifile example. The first file, which uses \, contains the following documentation comments: +This example uses multiple files. The first file, which uses ``, contains the following documentation comments: ```cpp // xml_include_tag.cpp @@ -58,7 +58,7 @@ public ref class Test2 { }; ``` -The second file, xml_include_tag.doc, contains the following documentation comments: +The second file, *`xml_include_tag.doc`*, contains the following documentation comments: ```xml @@ -103,4 +103,4 @@ The summary for this other type. ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/cpp/address-of-operator-amp.md b/docs/cpp/address-of-operator-amp.md index 94aac88a3bb..7e379867c53 100644 --- a/docs/cpp/address-of-operator-amp.md +++ b/docs/cpp/address-of-operator-amp.md @@ -1,26 +1,27 @@ --- -title: "Address-of Operator: &" +title: "Address-of operator: &" description: "The address-of operator in the C++ language." ms.date: 10/02/2020 f1_keywords: ["&"] helpviewer_keywords: ["address-of operator (&)", "& operator", "& operator [C++], address-of operator"] ms.assetid: 2828221a-15f6-4acc-87fe-25e34feebb88 --- -# Address-of Operator: `&` +# Address-of operator: `&` ## Syntax -> **`&`** *`cast-expression`* +*`address-of-expression`*:\ +  **`&`** *`cast-expression`* ## Remarks -The unary address-of operator (**`&`**) takes the address of its operand. The operand of the address-of operator can be either a function designator or an l-value that designates an object that's not a bit field. +The unary address-of operator (**`&`**) returns the address of (that is, a pointer to) its operand. The operand of the address-of operator can be a function designator. Or, it can be an lvalue that refers to an object that's not a bit field. -The address-of operator can only be applied to variables of fundamental, structure, class, or union types that are declared at the file-scope level, or to subscripted array references. In these expressions, a constant expression that doesn't include the address-of operator can be added to or subtracted from the address-of expression. +The address-of operator can only be applied to certain lvalue expressions: either to variables of fundamental, structure, class, or union types, or to subscripted array references. In these expressions, a constant expression (one that doesn't include the address-of operator) can be added to or subtracted from the address-of expression. -When applied to functions or l-values, the result of the expression is a pointer type (an r-value) derived from the type of the operand. For example, if the operand is of type **`char`**, the result of the expression is of type pointer to **`char`**. The address-of operator, applied to **`const`** or **`volatile`** objects, evaluates to `const type *` or `volatile type *`, where `type` is the type of the original object. +When applied to functions or lvalues, the result of the expression is a pointer type (an rvalue) derived from the type of the operand. For example, if the operand is of type **`char`**, the result of the expression is of type pointer to **`char`**. The address-of operator, applied to **`const`** or **`volatile`** objects, evaluates to `const type *` or `volatile type *`, where `type` is the type of the original object. -The address of an overloaded function can be taken only when it's clear which version of the function is being referenced. See [Function Overloading](function-overloading.md) for information about how to obtain the address of a particular overloaded function. +You can only take the address of an overloaded function when it's clear which version of the function is referenced. For more information about how to obtain the address of a particular overloaded function, see [Function overloading](function-overloading.md). When the address-of operator is applied to a qualified name, the result depends on whether the *qualified-name* specifies a static member. If so, the result is a pointer to the type specified in the declaration of the member. For a member that isn't static, the result is a pointer to the member *name* of the class indicated by *qualified-class-name*. For more information about *qualified-class-name*, see [Primary expressions](../cpp/primary-expressions.md). @@ -98,7 +99,7 @@ int main() { ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
-[C++ Built-in Operators, Precedence, and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
-[Lvalue Reference Declarator: &](../cpp/lvalue-reference-declarator-amp.md)
-[Indirection and Address-of Operators](../c-language/indirection-and-address-of-operators.md) +[Expressions with unary operators](../cpp/expressions-with-unary-operators.md)\ +[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ +[Lvalue reference declarator: `&`](../cpp/lvalue-reference-declarator-amp.md)\ +[Indirection and address-of operators](../c-language/indirection-and-address-of-operators.md) diff --git a/docs/cpp/bitwise-and-operator-amp.md b/docs/cpp/bitwise-and-operator-amp.md index e0fadaea1b2..790c3682935 100644 --- a/docs/cpp/bitwise-and-operator-amp.md +++ b/docs/cpp/bitwise-and-operator-amp.md @@ -10,15 +10,17 @@ ms.assetid: 76f40de3-c417-47b9-8a77-532f3fc990a5 ## Syntax -> *expression* **`&`** *expression* +*`and-expression`*:\ +  *`equality-expression`*\ +  *`and-expression`* **`&`** *`equality-expression`* ## Remarks The bitwise AND operator (**`&`**) compares each bit of the first operand to the corresponding bit of the second operand. If both bits are 1, the corresponding result bit is set to 1. Otherwise, the corresponding result bit is set to 0. -Both operands to the bitwise AND operator must have integral types. The usual arithmetic conversions covered in [Standard Conversions](standard-conversions.md) are applied to the operands. +Both operands to the bitwise AND operator must have integral types. The usual arithmetic conversions covered in [Standard conversions](standard-conversions.md) are applied to the operands. -## Operator keyword for & +## Operator keyword for `&` C++ specifies **`bitand`** as an alternative spelling for **`&`**. In C, the alternative spelling is provided as a macro in the \ header. In C++, the alternative spelling is a keyword; use of \ or the C++ equivalent \ is deprecated. In Microsoft C++, the [`/permissive-`](../build/reference/permissive-standards-conformance.md) or [`/Za`](../build/reference/za-ze-disable-language-extensions.md) compiler option is required to enable the alternative spelling. @@ -31,14 +33,14 @@ C++ specifies **`bitand`** as an alternative spelling for **`&`**. In C, the alt #include using namespace std; int main() { - unsigned short a = 0xFFFF; // pattern 1111 ... + unsigned short a = 0xCCCC; // pattern 1100 ... unsigned short b = 0xAAAA; // pattern 1010 ... - cout << hex << ( a & b ) << endl; // prints "aaaa", pattern 1010 ... + cout << hex << ( a & b ) << endl; // prints "8888", pattern 1000 ... } ``` ## See also -[C++ built-in operators, precedence, and associativity](cpp-built-in-operators-precedence-and-associativity.md)
+[C++ built-in operators, precedence, and associativity](cpp-built-in-operators-precedence-and-associativity.md)\ [C bitwise operators](../c-language/c-bitwise-operators.md) diff --git a/docs/cpp/logical-and-operator-amp-amp.md b/docs/cpp/logical-and-operator-amp-amp.md index a0572816c3a..940b6a39863 100644 --- a/docs/cpp/logical-and-operator-amp-amp.md +++ b/docs/cpp/logical-and-operator-amp-amp.md @@ -10,11 +10,13 @@ ms.assetid: 50cfa664-a8c4-4b31-9bab-2f80d7cd2d1f ## Syntax -> *expression* **`&&`** *expression* +*`logical-and-expression`*:\ +  *`equality-expression`*\ +  *`logical-and-expression`* **`&&`** *`equality-expression`* ## Remarks -The logical AND operator (**&&**) returns **`true`** if both operands are **`true`** and returns **`false`** otherwise. The operands are implicitly converted to type **`bool`** before evaluation, and the result is of type **`bool`**. Logical AND has left-to-right associativity. +The logical AND operator (**`&&`**) returns **`true`** if both operands are **`true`** and returns **`false`** otherwise. The operands are implicitly converted to type **`bool`** before evaluation, and the result is of type **`bool`**. Logical AND has left-to-right associativity. The operands to the logical AND operator don't need to have the same type, but they must have boolean, integral, or pointer type. The operands are commonly relational or equality expressions. @@ -30,7 +32,7 @@ char *pch = 0; If `pch` is null (0), the right side of the expression is never evaluated. This short-circuit evaluation makes the assignment through a null pointer impossible. -## Operator keyword for && +## Operator keyword for `&&` C++ specifies **`and`** as an alternative spelling for **`&&`**. In C, the alternative spelling is provided as a macro in the \ header. In C++, the alternative spelling is a keyword; use of \ or the C++ equivalent \ is deprecated. In Microsoft C++, the [`/permissive-`](../build/reference/permissive-standards-conformance.md) or [`/Za`](../build/reference/za-ze-disable-language-extensions.md) compiler option is required to enable the alternative spelling. @@ -58,5 +60,5 @@ int main() { ## See also -[C++ built-in operators, precedence, and associativity](cpp-built-in-operators-precedence-and-associativity.md)
+[C++ built-in operators, precedence, and associativity](cpp-built-in-operators-precedence-and-associativity.md)\ [C logical operators](../c-language/c-logical-operators.md) diff --git a/docs/cpp/lvalue-reference-declarator-amp.md b/docs/cpp/lvalue-reference-declarator-amp.md index 5b1da6e037b..c68189be760 100644 --- a/docs/cpp/lvalue-reference-declarator-amp.md +++ b/docs/cpp/lvalue-reference-declarator-amp.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: Lvalue Reference Declarator: &" -title: "Lvalue Reference Declarator: &" +description: "Learn more about: Lvalue reference declarator: &" +title: "Lvalue reference declarator: &" ms.date: "11/04/2016" f1_keywords: ["&"] helpviewer_keywords: ["reference operator", "& operator [C++], reference operator"] ms.assetid: edf0513d-3dcc-4663-b276-1269795dda51 --- -# Lvalue Reference Declarator: `&` +# Lvalue reference declarator: `&` Holds the address of an object but behaves syntactically like an object. ## Syntax -``` -type-id & cast-expression -``` +*`lvalue-reference-type-id`*:\ + *`type-specifier-seq`* **`&`** *`attribute-specifier-seq`*opt *`ptr-abstract-declarator`*opt ## Remarks @@ -22,7 +21,7 @@ You can think of an lvalue reference as another name for an object. An lvalue re Any object whose address can be converted to a given pointer type can also be converted to the similar reference type. For example, any object whose address can be converted to type `char *` can also be converted to type `char &`. -Do not confuse reference declarations with use of the [address-of operator](../cpp/address-of-operator-amp.md). When the `&`*identifier* is preceded by a type, such as **`int`** or **`char`**, *identifier* is declared as a reference to the type. When `&`*identifier* is not preceded by a type, the usage is that of the address-of operator. +Don't confuse reference declarations with use of the [address-of operator](../cpp/address-of-operator-amp.md). When the `&`*identifier* is preceded by a type, such as **`int`** or **`char`**, *identifier* is declared as a reference to the type. When `&`*identifier* is not preceded by a type, the usage is that of the address-of operator. ## Example @@ -65,7 +64,7 @@ Bill is 40 ## See also -[References](../cpp/references-cpp.md)
-[Reference-Type Function Arguments](../cpp/reference-type-function-arguments.md)
-[Reference-Type Function Returns](../cpp/reference-type-function-returns.md)
-[References to Pointers](../cpp/references-to-pointers.md) +[References](../cpp/references-cpp.md)\ +[Reference-type function arguments](../cpp/reference-type-function-arguments.md)\ +[Reference-type function returns](../cpp/reference-type-function-returns.md)\ +[References to pointers](../cpp/references-to-pointers.md) diff --git a/docs/cpp/rvalue-reference-declarator-amp-amp.md b/docs/cpp/rvalue-reference-declarator-amp-amp.md index 7bf30cdb718..aa24139baf8 100644 --- a/docs/cpp/rvalue-reference-declarator-amp-amp.md +++ b/docs/cpp/rvalue-reference-declarator-amp-amp.md @@ -1,34 +1,33 @@ --- -description: "Learn more about: Rvalue Reference Declarator: &&" -title: "Rvalue Reference Declarator: &&" +description: "Learn more about: Rvalue reference declarator: &&" +title: "Rvalue reference declarator: &&" ms.date: "11/04/2016" f1_keywords: ["&&"] helpviewer_keywords: ["&& rvalue reference declarator"] ms.assetid: eab0ce3a-c5a3-4992-aa70-6a8ab1f7491d --- -# Rvalue Reference Declarator: && +# Rvalue reference declarator: `&&` Holds a reference to an rvalue expression. ## Syntax -``` -type-id && cast-expression -``` +*`rvalue-reference-type-id`*:\ + *`type-specifier-seq`* **`&&`** *`attribute-specifier-seq`*opt *`ptr-abstract-declarator`*opt ## Remarks -Rvalue references enable you to distinguish an lvalue from an rvalue. Lvalue references and rvalue references are syntactically and semantically similar, but they follow somewhat different rules. For more information about lvalues and rvalues, see [Lvalues and Rvalues](../cpp/lvalues-and-rvalues-visual-cpp.md). For more information about lvalue references, see [Lvalue Reference Declarator: &](../cpp/lvalue-reference-declarator-amp.md). +Rvalue references enable you to distinguish an lvalue from an rvalue. Lvalue references and rvalue references are syntactically and semantically similar, but they follow slightly different rules. For more information about lvalues and rvalues, see [Lvalues and Rvalues](../cpp/lvalues-and-rvalues-visual-cpp.md). For more information about lvalue references, see [Lvalue Reference Declarator: &](../cpp/lvalue-reference-declarator-amp.md). The following sections describe how rvalue references support the implementation of *move semantics* and *perfect forwarding*. ## Move Semantics -Rvalue references support the implementation of *move semantics*, which can significantly increase the performance of your applications. Move semantics enables you to write code that transfers resources (such as dynamically allocated memory) from one object to another. Move semantics works because it enables resources to be transferred from temporary objects that cannot be referenced elsewhere in the program. +Rvalue references support the implementation of *move semantics*, which can significantly increase the performance of your applications. Move semantics enables you to write code that transfers resources (such as dynamically allocated memory) from one object to another. Move semantics works because it enables transfer of resources from temporary objects: ones that can't be referenced elsewhere in the program. -To implement move semantics, you typically provide a *move constructor,* and optionally a move assignment operator (**operator=**), to your class. Copy and assignment operations whose sources are rvalues then automatically take advantage of move semantics. Unlike the default copy constructor, the compiler does not provide a default move constructor. For more information about how to write a move constructor and how to use it in your application, see [Move Constructors and Move Assignment Operators (C++)](../cpp/move-constructors-and-move-assignment-operators-cpp.md). +To implement move semantics, you typically provide a *move constructor,* and optionally a move assignment operator (**`operator=`**), to your class. Copy and assignment operations whose sources are rvalues then automatically take advantage of move semantics. Unlike the default copy constructor, the compiler doesn't provide a default move constructor. For more information about how to write and use a move constructor, see [Move constructors and move assignment operators](../cpp/move-constructors-and-move-assignment-operators-cpp.md). -You can also overload ordinary functions and operators to take advantage of move semantics. Visual Studio 2010 introduces move semantics into the C++ Standard Library. For example, the `string` class implements operations that perform move semantics. Consider the following example that concatenates several strings and prints the result: +You can also overload ordinary functions and operators to take advantage of move semantics. Visual Studio 2010 introduces move semantics into the C++ Standard Library. For example, the `string` class implements operations that use move semantics. Consider the following example that concatenates several strings and prints the result: ```cpp // string_concatenation.cpp @@ -44,11 +43,11 @@ int main() } ``` -Before Visual Studio 2010, each call to **operator+** allocates and returns a new temporary `string` object (an rvalue). **operator+** cannot append one string to the other because it does not know whether the source strings are lvalues or rvalues. If the source strings are both lvalues, they might be referenced elsewhere in the program and therefore must not be modified. By using rvalue references, **operator+** can be modified to take rvalues, which cannot be referenced elsewhere in the program. Therefore, **operator+** can now append one string to another. This can significantly reduce the number of dynamic memory allocations that the `string` class must perform. For more information about the `string` class, see [basic_string Class](../standard-library/basic-string-class.md). +Before Visual Studio 2010, each call to **`operator+`** allocates and returns a new temporary `string` object (an rvalue). **`operator+`** can't append one string to the other because it doesn't know whether the source strings are lvalues or rvalues. If the source strings are both lvalues, they might be referenced elsewhere in the program and so must not be modified. By using rvalue references, **`operator+`** can be modified to take rvalues, which can't be referenced elsewhere in the program. With this change, **`operator+`** can now append one string to another. The change significantly reduces the number of dynamic memory allocations that the `string` class must make. For more information about the `string` class, see [basic_string Class](../standard-library/basic-string-class.md). -Move semantics also helps when the compiler cannot use Return Value Optimization (RVO) or Named Return Value Optimization (NRVO). In these cases, the compiler calls the move constructor if the type defines it. +Move semantics also helps when the compiler can't use Return Value Optimization (RVO) or Named Return Value Optimization (NRVO). In these cases, the compiler calls the move constructor if the type defines it. -To better understand move semantics, consider the example of inserting an element into a `vector` object. If the capacity of the `vector` object is exceeded, the `vector` object must reallocate memory for its elements and then copy each element to another memory location to make room for the inserted element. When an insertion operation copies an element, it creates a new element, calls the copy constructor to copy the data from the previous element to the new element, and then destroys the previous element. Move semantics enables you to move objects directly without having to perform expensive memory allocation and copy operations. +To better understand move semantics, consider the example of inserting an element into a `vector` object. If the capacity of the `vector` object is exceeded, the `vector` object must reallocate memory for its elements and then copy each element to another memory location to make room for the inserted element. When an insertion operation copies an element, it first creates a new element. Then it calls the copy constructor to copy the data from the previous element to the new element. Finally, it destroys the previous element. Move semantics enables you to move objects directly without having to make expensive memory allocation and copy operations. To take advantage of move semantics in the `vector` example, you can write a move constructor to move data from one object to another. @@ -56,9 +55,9 @@ For more information about the introduction of move semantics into the C++ Stand ## Perfect Forwarding -Perfect forwarding reduces the need for overloaded functions and helps avoid the forwarding problem. The *forwarding problem* can occur when you write a generic function that takes references as its parameters and it passes (or *forwards*) these parameters to another function. For example, if the generic function takes a parameter of type `const T&`, then the called function cannot modify the value of that parameter. If the generic function takes a parameter of type `T&`, then the function cannot be called by using an rvalue (such as a temporary object or integer literal). +Perfect forwarding reduces the need for overloaded functions and helps avoid the forwarding problem. The *forwarding problem* can occur when you write a generic function that takes references as its parameters. If it passes (or *forwards*) these parameters to another function, for example, if it takes a parameter of type `const T&`, then the called function can't modify the value of that parameter. If the generic function takes a parameter of type `T&`, then the function can't be called by using an rvalue (such as a temporary object or integer literal). -Ordinarily, to solve this problem, you must provide overloaded versions of the generic function that take both `T&` and `const T&` for each of its parameters. As a result, the number of overloaded functions increases exponentially with the number of parameters. Rvalue references enable you to write one version of a function that accepts arbitrary arguments and forwards them to another function as if the other function had been called directly. +Ordinarily, to solve this problem, you must provide overloaded versions of the generic function that take both `T&` and `const T&` for each of its parameters. As a result, the number of overloaded functions increases exponentially with the number of parameters. Rvalue references enable you to write one version of a function that accepts arbitrary arguments. Then that function can forward them to another function as if the other function had been called directly. Consider the following example that declares four types, `W`, `X`, `Y`, and `Z`. The constructor for each type takes a different combination of **`const`** and non-**`const`** lvalue references as its parameters. @@ -101,7 +100,7 @@ int a = 4, b = 5; W* pw = factory(a, b); ``` -However, the following example does not contain a valid call to the `factory` function because `factory` takes lvalue references that are modifiable as its parameters, but it is called by using rvalues: +However, the following example doesn't contain a valid call to the `factory` function. That's because `factory` takes lvalue references that are modifiable as its parameters, but it's called by using rvalues: ```cpp Z* pz = factory(2, 2); @@ -137,7 +136,7 @@ int main() } ``` -## Additional Properties of Rvalue References +## Properties of Rvalue References **You can overload a function to take an lvalue reference and an rvalue reference.** @@ -157,7 +156,7 @@ class MemoryBlock void f(const MemoryBlock&) { - cout << "In f(const MemoryBlock&). This version cannot modify the parameter." << endl; + cout << "In f(const MemoryBlock&). This version can't modify the parameter." << endl; } void f(MemoryBlock&&) @@ -176,15 +175,15 @@ int main() This example produces the following output: ```Output -In f(const MemoryBlock&). This version cannot modify the parameter. +In f(const MemoryBlock&). This version can't modify the parameter. In f(MemoryBlock&&). This version can modify the parameter. ``` -In this example, the first call to `f` passes a local variable (an lvalue) as its argument. The second call to `f` passes a temporary object as its argument. Because the temporary object cannot be referenced elsewhere in the program, the call binds to the overloaded version of `f` that takes an rvalue reference, which is free to modify the object. +In this example, the first call to `f` passes a local variable (an lvalue) as its argument. The second call to `f` passes a temporary object as its argument. Because the temporary object can't be referenced elsewhere in the program, the call binds to the overloaded version of `f` that takes an rvalue reference, which is free to modify the object. **The compiler treats a named rvalue reference as an lvalue and an unnamed rvalue reference as an rvalue.** -When you write a function that takes an rvalue reference as its parameter, that parameter is treated as an lvalue in the body of the function. The compiler treats a named rvalue reference as an lvalue because a named object can be referenced by several parts of a program; it would be dangerous to allow multiple parts of a program to modify or remove resources from that object. For example, if multiple parts of a program try to transfer resources from the same object, only the first part will successfully transfer the resource. +Functions that take an rvalue reference as a parameter treat the parameter as an lvalue in the body of the function. The compiler treats a named rvalue reference as an lvalue. That's because a named object can be referenced by several parts of a program. It's dangerous to allow multiple parts of a program to modify or remove resources from that object. For example, if multiple parts of a program try to transfer resources from the same object, only the first transfer succeeds. The following example shows the function `g`, which is overloaded to take an lvalue reference and an rvalue reference. The function `f` takes an rvalue reference as its parameter (a named rvalue reference) and returns an rvalue reference (an unnamed rvalue reference). In the call to `g` from `f`, overload resolution selects the version of `g` that takes an lvalue reference because the body of `f` treats its parameter as an lvalue. In the call to `g` from `main`, overload resolution selects the version of `g` that takes an rvalue reference because `f` returns an rvalue reference. @@ -229,11 +228,11 @@ In g(const MemoryBlock&). In g(MemoryBlock&&). ``` -In this example, the `main` function passes an rvalue to `f`. The body of `f` treats its named parameter as an lvalue. The call from `f` to `g` binds the parameter to an lvalue reference (the first overloaded version of `g`). +In the example, the `main` function passes an rvalue to `f`. The body of `f` treats its named parameter as an lvalue. The call from `f` to `g` binds the parameter to an lvalue reference (the first overloaded version of `g`). - **You can cast an lvalue to an rvalue reference.** -The C++ Standard Library [std::move](../standard-library/utility-functions.md#move) function enables you to convert an object to an rvalue reference to that object. Alternatively, you can use the **`static_cast`** keyword to cast an lvalue to an rvalue reference, as shown in the following example: +The C++ Standard Library [`std::move`](../standard-library/utility-functions.md#move) function enables you to convert an object to an rvalue reference to that object. You can also use the **`static_cast`** keyword to cast an lvalue to an rvalue reference, as shown in the following example: ```cpp // cast-reference.cpp @@ -274,9 +273,9 @@ In g(MemoryBlock&&). **Function templates deduce their template argument types and then use reference collapsing rules.** -It is common to write a function template that passes (or *forwards*) its parameters to another function. It is important to understand how template type deduction works for function templates that take rvalue references. +A function template that passes (or *forwards*) its parameters to another function is a common pattern. It's important to understand how template type deduction works for function templates that take rvalue references. -If the function argument is an rvalue, the compiler deduces the argument to be an rvalue reference. For example, if you pass an rvalue reference to an object of type `X` to a template function that takes type `T&&` as its parameter, template argument deduction deduces `T` to be `X`. Therefore, the parameter has type `X&&`. If the function argument is an lvalue or **`const`** lvalue, the compiler deduces its type to be an lvalue reference or **`const`** lvalue reference of that type. +If the function argument is an rvalue, the compiler deduces the argument to be an rvalue reference. For example, assume you pass an rvalue reference to an object of type `X` to a template function that takes type `T&&` as its parameter. Template argument deduction deduces `T` to be `X`, so the parameter has type `X&&`. If the function argument is an lvalue or **`const`** lvalue, the compiler deduces its type to be an lvalue reference or **`const`** lvalue reference of that type. The following example declares one structure template and then specializes it for various reference types. The `print_type_and_value` function takes an rvalue reference as its parameter and forwards it to the appropriate specialized version of the `S::print` method. The `main` function demonstrates the various ways to call the `S::print` method. @@ -368,13 +367,13 @@ print: third print: fourth ``` -To resolve each call to the `print_type_and_value` function, the compiler first performs template argument deduction. The compiler then applies reference collapsing rules when it substitutes the deduced template arguments for the parameter types. For example, passing the local variable `s1` to the `print_type_and_value` function causes the compiler to produce the following function signature: +To resolve each call to the `print_type_and_value` function, the compiler first does template argument deduction. The compiler then applies reference collapsing rules when it replaces the parameter types with the deduced template arguments. For example, passing the local variable `s1` to the `print_type_and_value` function causes the compiler to produce the following function signature: ```cpp print_type_and_value(string& && t) ``` -The compiler uses reference collapsing rules to reduce the signature to the following: +The compiler uses reference collapsing rules to reduce the signature: ```cpp print_type_and_value(string& t) @@ -391,16 +390,16 @@ The following table summarizes the reference collapsing rules for template argum | `T&& &` | `T&` | | `T&& &&` | `T&&` | -Template argument deduction is an important element of implementing perfect forwarding. The section Perfect Forwarding, which is presented earlier in this topic, describes perfect forwarding in more detail. +Template argument deduction is an important element of implementing perfect forwarding. The [Perfect Forwarding](#perfect-forwarding) section describes perfect forwarding in more detail. ## Summary -Rvalue references distinguish lvalues from rvalues. They can help you improve the performance of your applications by eliminating the need for unnecessary memory allocations and copy operations. They also enable you to write one version of a function that accepts arbitrary arguments and forwards them to another function as if the other function had been called directly. +Rvalue references distinguish lvalues from rvalues. To improve the performance of your applications, they can eliminate the need for unnecessary memory allocations and copy operations. They also enable you to write a function that accepts arbitrary arguments. That function can forward them to another function as if the other function had been called directly. ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
-[Lvalue Reference Declarator: &](../cpp/lvalue-reference-declarator-amp.md)
-[Lvalues and Rvalues](../cpp/lvalues-and-rvalues-visual-cpp.md)
-[Move Constructors and Move Assignment Operators (C++)](../cpp/move-constructors-and-move-assignment-operators-cpp.md)
+[Expressions with unary operators](../cpp/expressions-with-unary-operators.md)\ +[Lvalue reference declarator: `&`](../cpp/lvalue-reference-declarator-amp.md)\ +[Lvalues and rvalues](../cpp/lvalues-and-rvalues-visual-cpp.md)\ +[Move constructors and move assignment operators (C++)](../cpp/move-constructors-and-move-assignment-operators-cpp.md)\ [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/cppcx/wrl/weakref-class.md b/docs/cppcx/wrl/weakref-class.md index f9101ddb2c0..86e2c5d46a0 100644 --- a/docs/cppcx/wrl/weakref-class.md +++ b/docs/cppcx/wrl/weakref-class.md @@ -1,13 +1,12 @@ --- description: "Learn more about: WeakRef Class" title: "WeakRef Class" -ms.date: "10/03/2018" +ms.date: 11/22/2021 ms.topic: "reference" 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"] 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"] -ms.assetid: 572be703-c641-496c-8af5-ad6164670ba1 --- -# WeakRef Class +# `WeakRef` class 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. @@ -19,26 +18,26 @@ class WeakRef : public ComPtr; ## Members -### Public Constructors +### Public constructors |Name|Description| |----------|-----------------| -|[WeakRef::WeakRef Constructor](#weakref)|Initializes a new instance of the `WeakRef` class.| -|[WeakRef::~WeakRef Destructor](#tilde-weakref)|Deinitializes the current instance of the `WeakRef` class.| +|[`WeakRef::WeakRef` constructor](#weakref)|Initializes a new instance of the `WeakRef` class.| +|[`WeakRef::~WeakRef` destructor](#tilde-weakref)|Deinitializes the current instance of the `WeakRef` class.| -### Public Methods +### Public methods |Name|Description| |----------|-----------------| -|[WeakRef::As Method](#as)|Sets the specified `ComPtr` pointer parameter to represent the specified interface.| -|[WeakRef::AsIID Method](#asiid)|Sets the specified `ComPtr` pointer parameter to represent the specified interface ID.| -|[WeakRef::CopyTo Method](#copyto)|Assigns a pointer to an interface, if available, to the specified pointer variable.| +|[`WeakRef::As`](#as)|Sets the specified `ComPtr` pointer parameter to represent the specified interface.| +|[`WeakRef::AsIID`](#asiid)|Sets the specified `ComPtr` pointer parameter to represent the specified interface ID.| +|[`WeakRef::CopyTo`](#copyto)|Assigns a pointer to an interface, if available, to the specified pointer variable.| -### Public Operators +### Public operators |Name|Description| |----------|-----------------| -|[WeakRef::operator& Operator](#operator-ampersand-operator)|Returns a `ComPtrRef` object that represents the current `WeakRef` object.| +|[`WeakRef::operator&`](#operator-ampersand-operator)|Returns a `ComPtrRef` object that represents the current `WeakRef` object.| ## Remarks @@ -65,7 +64,7 @@ if(wr == nullptr) } ``` -The above code does not work when using the Windows 10 SDK (or later). Instead, check the pointer that was passed in for **`nullptr`**. +The above code doesn't work when using the Windows 10 SDK (or later). Instead, check the pointer that was passed in for **`nullptr`**. ```cpp if (strongRef == nullptr) @@ -74,19 +73,54 @@ if (strongRef == nullptr) } ``` -## Inheritance Hierarchy +## Inheritance hierarchy -`ComPtr` - -`WeakRef` +[`ComPtr`](comptr-class.md)\ + └ [`WeakRef`](weakref-class.md) ## Requirements -**Header:** client.h +**Header:** *`client.h`* + +**Namespace:** `Microsoft::WRL` + +## `WeakRef::WeakRef` constructor + +Initializes a new instance of the `WeakRef` class. + +```cpp +WeakRef(); +WeakRef( + decltype(__nullptr) +); + +WeakRef( + _In_opt_ IWeakReference* ptr +); + +WeakRef( + const ComPtr& ptr +); + +WeakRef( + const WeakRef& ptr +); + +WeakRef( + _Inout_ WeakRef&& ptr +); +``` + +### Parameters + +*`ptr`*\ +A pointer, reference, or rvalue-reference to an existing object that initializes the current `WeakRef` object. + +### Remarks -**Namespace:** Microsoft::WRL +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` object. The fourth and fifth constructors initialize a `WeakRef` object from another `WeakRef` object. -## WeakRef::~WeakRef Destructor +## `WeakRef::~WeakRef` destructor Deinitializes the current instance of the `WeakRef` class. @@ -94,7 +128,7 @@ Deinitializes the current instance of the `WeakRef` class. ~WeakRef(); ``` -## WeakRef::As Method +## `WeakRef::As` Sets the specified `ComPtr` pointer parameter to represent the specified interface. @@ -112,29 +146,29 @@ HRESULT As( ### Parameters -*U*
+*`U`*\ An interface ID. -*ptr*
+*`ptr`*\ When this operation completes, an object that represents parameter *U*. -### Return Value +### Return value -- S_OK if this operation succeeds; otherwise, an HRESULT that indicates the reason the operation failed, and *ptr* is set to **`nullptr`**. +- `S_OK` if this operation succeeds; otherwise, an HRESULT that indicates the reason the operation failed, and *`ptr`* is set to **`nullptr`**. -- S_OK if this operation succeeds, but the current `WeakRef` object has already been released. Parameter *ptr* is set to **`nullptr`**. +- `S_OK` if this operation succeeds, but the current `WeakRef` object has already been released. Parameter *`ptr`* is set to **`nullptr`**. -- S_OK if this operation succeeds, but the current `WeakRef` object is not derived from parameter *U*. Parameter *ptr* is set to **`nullptr`**. +- `S_OK` if this operation succeeds, but the current `WeakRef` object isn't derived from parameter *`U`*. Parameter *`ptr`* is set to **`nullptr`**. ### Remarks -An error is emitted if parameter *U* is `IWeakReference`, or is not derived from `IInspectable`. +An error is emitted if parameter *`U`* is `IWeakReference`, or isn't derived from `IInspectable`. -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. +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. -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`**. +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`**. -## WeakRef::AsIID Method +## `WeakRef::AsIID` Sets the specified `ComPtr` pointer parameter to represent the specified interface ID. @@ -147,29 +181,29 @@ HRESULT AsIID( ### Parameters -*riid*
+*`riid`*\ An interface ID. -*ptr*
-When this operation completes, an object that represents parameter *riid*. +*`ptr`*\ +When this operation completes, an object that represents parameter *`riid`*. -### Return Value +### Return value -- S_OK if this operation succeeds; otherwise, an HRESULT that indicates the reason the operation failed, and *ptr* is set to **`nullptr`**. +- `S_OK` if this operation succeeds; otherwise, an HRESULT that indicates the reason the operation failed, and *`ptr`* is set to **`nullptr`**. -- S_OK if this operation succeeds, but the current `WeakRef` object has already been released. Parameter *ptr* is set to **`nullptr`**. +- `S_OK` if this operation succeeds, but the current `WeakRef` object has already been released. Parameter *`ptr`* is set to **`nullptr`**. -- 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.) +- `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.) ### Remarks -An error is emitted if parameter *riid* is not derived from `IInspectable`. This error supersedes the return value. +An error is emitted if parameter *`riid`* isn't derived from `IInspectable`. This error supersedes the return value. -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. +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. -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`**. +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`**. -## WeakRef::CopyTo Method +## `WeakRef::CopyTo` Assigns a pointer to an interface, if available, to the specified pointer variable. @@ -191,26 +225,26 @@ HRESULT CopyTo( ### Parameters -*U*
-Pointer an `IInspectable` interface. An error is emitted if *U* is not derived from `IInspectable`. +*`U`*\ +Pointer an `IInspectable` interface. An error is emitted if *`U`* isn't derived from `IInspectable`. -*riid*
-An interface ID. An error is emitted if *riid* is not derived from `IWeakReference`. +*`riid`*\ +An interface ID. An error is emitted if *`riid`* isn't derived from `IWeakReference`. -*ptr*
-A doubly-indirect pointer to `IInspectable` or `IWeakReference`. +*`ptr`*\ +A doubly indirect pointer to `IInspectable` or `IWeakReference`. -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that describes the failure. For more information, see **Remarks**. +`S_OK` if successful; otherwise, an HRESULT that describes the failure. For more information, see **Remarks**. ### Remarks -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`**. +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`**. -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`**. +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`**. -## WeakRef::operator& Operator +## `WeakRef::operator&` Returns a `ComPtrRef` object that represents the current `WeakRef` object. @@ -218,46 +252,10 @@ Returns a `ComPtrRef` object that represents the current `WeakRef` object. Details::ComPtrRef operator&() throw() ``` -### Return Value +### Return value A `ComPtrRef` object that represents the current `WeakRef` object. ### Remarks -This is an internal helper operator that is not meant to be used in your code. - -## WeakRef::WeakRef Constructor - -Initializes a new instance of the `WeakRef` class. - -```cpp -WeakRef(); -WeakRef( - decltype(__nullptr) -); - -WeakRef( - _In_opt_ IWeakReference* ptr -); - -WeakRef( - const ComPtr& ptr -); - -WeakRef( - const WeakRef& ptr -); - -WeakRef( - _Inout_ WeakRef&& ptr -); -``` - -### Parameters - -*ptr*
-A pointer, reference, or rvalue-reference to an existing object that initializes the current `WeakRef` object. - -### Remarks - -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` object. The fourth and fifth constructors initializes a `WeakRef` object from another `WeakRef` object. +`WeakRef::operator&` is an internal helper operator that's not meant to be used in your code. diff --git a/docs/data/oledb/cdataconnection-class.md b/docs/data/oledb/cdataconnection-class.md index a852fec8b24..6185ad46918 100644 --- a/docs/data/oledb/cdataconnection-class.md +++ b/docs/data/oledb/cdataconnection-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: CDataConnection Class" -title: "CDataConnection Class" +description: "Learn more about: CDataConnection class" +title: "CDataConnection class" ms.date: "03/27/2019" f1_keywords: ["ATL::CDataConnection", "ATL.CDataConnection", "CDataConnection", "CDataConnection.CDataConnection", "ATL.CDataConnection.CDataConnection", "CDataConnection::CDataConnection", "ATL::CDataConnection::CDataConnection", "CDataConnection.Copy", "ATL.CDataConnection.Copy", "ATL::CDataConnection::Copy", "CDataConnection::Copy", "CDataConnection.Open", "ATL.CDataConnection.Open", "CDataConnection::Open", "ATL::CDataConnection::Open", "CDataConnection.OpenNewSession", "ATL.CDataConnection.OpenNewSession", "ATL::CDataConnection::OpenNewSession", "OpenNewSession", "CDataConnection::OpenNewSession", "CDataConnection::operatorBOOL", "ATL::CDataConnection::operatorBOOL", "CDataConnection.operatorBOOL", "ATL.CDataConnection.operatorBOOL", "CDataSource&", "CDataConnection.operatorCDataSource&", "operatorCDataSource&", "CDataConnection::operatorCDataSource&", "CDataSource*", "CDataConnection::operatorCDataSource*", "CDataConnection.operatorCDataSource*", "operatorCDataSource*", "CSession&", "CDataConnection::operatorCSession&", "CDataConnection.operatorCSession&", "operatorCSession&", "CDataConnection.operatorCSession*", "CDataConnection::operatorCSession*", "operatorCSession*", "CSession*"] helpviewer_keywords: ["CDataConnection class", "CDataConnection class, constructor", "Copy method", "Open method", "OpenNewSession method", "BOOL operator", "operator bool", "BOOL operator", "operator bool", "CDataSource& operator", "operator & (CDataSource)", "CDataSource* operator", "operator * (CDataSource)", "operator CSession&", "CSession& operator", "operator CSession*", "CSession* operator"] ms.assetid: 77432d85-4e20-49ec-a0b0-142137828471 --- -# CDataConnection Class +# `CDataConnection` class Manages the connection with the data source. @@ -25,35 +25,35 @@ class CDataConnection ### Methods | Name | Description | -|-|-| -|[CDataConnection](#cdataconnection)|Constructor. Instantiates and initializes a `CDataConnection` object.| -|[Copy](#copy)|Creates a copy of an existing data connection.| -|[Open](#open)|Opens a connection to a data source using an initialization string.| -|[OpenNewSession](#opennewsession)|Opens a new session on the current connection.| +|--|--| +| [`CDataConnection::CDataConnection`](#cdataconnection) | Constructor. Instantiates and initializes a `CDataConnection` object. | +| [`CDataConnection::Copy`](#copy) | Creates a copy of an existing data connection. | +| [`CDataConnection::Open`](#open) | Opens a connection to a data source using an initialization string. | +| [`CDataConnection::OpenNewSession`](#opennewsession) | Opens a new session on the current connection. | ### Operators | Name | Description | -|-|-| -|[operator BOOL](#op_bool)|Determines whether the current session is open or not.| -|[operator bool](#op_bool_ole)|Determines whether the current session is open or not.| -|[operator CDataSource&](#op_cdata_amp)|Returns a reference to the contained `CDataSource` object.| -|[operator CDataSource*](#op_cdata_star)|Returns a pointer to the contained `CDataSource` object.| -|[operator CSession&](#op_csession_amp)|Returns a reference to the contained `CSession` object.| -|[operator CSession*](#op_csession_star)|Returns a pointer to the contained `CSession` object.| +|--|--| +| [`CDataConnection::operator BOOL`](#op_bool) | Determines whether the current session is open or not. | +| [`CDataConnection::operator bool`](#op_bool_ole) | Determines whether the current session is open or not. | +| [`CDataConnection::operator CDataSource&`](#op_cdata_amp) | Returns a reference to the contained `CDataSource` object. | +| [`CDataConnection::operator CDataSource*`](#op_cdata_star) | Returns a pointer to the contained `CDataSource` object. | +| [`CDataConnection::operator CSession&`](#op_csession_amp) | Returns a reference to the contained `CSession` object. | +| [`CDataConnection::operator CSession*`](#op_csession_star) | Returns a pointer to the contained `CSession` object. | ## Remarks `CDataConnection` is a useful class for creating clients because it encapsulates necessary objects (data source and session) and some of the work you need to do when connecting to a data source -Without `CDataConnection`, you have to create a `CDataSource` object, call its [OpenFromInitializationString](./cdatasource-class.md#openfrominitializationstring) method, then create an instance of a [CSession](../../data/oledb/csession-class.md) object, call its [Open](./csession-class.md#open) method, then create a [CCommand](../../data/oledb/ccommand-class.md) object and call its `Open`* methods. +Without `CDataConnection`, you have to create a `CDataSource` object, call its [`OpenFromInitializationString`](./cdatasource-class.md#openfrominitializationstring) method, then create an instance of a [`CSession`](../../data/oledb/csession-class.md) object, call its [`Open`](./csession-class.md#open) method, then create a [`CCommand`](../../data/oledb/ccommand-class.md) object and call its `Open`* methods. -With `CDataConnection`, you only need to create a connection object, pass it an initialization string, then use that connection to open commands. If you plan on using your connection to the database repeatedly, it is a good idea to keep the connection open, and `CDataConnection` provides a convenient way to do that. +With `CDataConnection`, you only need to create a connection object, pass it an initialization string, then use that connection to open commands. If you plan on using your connection to the database repeatedly, it's a good idea to keep the connection open, and `CDataConnection` provides a convenient way to do that. > [!NOTE] -> If you are creating a database application that needs to handle multiple sessions, you will need to use [OpenNewSession](#opennewsession). +> If you are creating a database application that needs to handle multiple sessions, you will need to use [`OpenNewSession`](#opennewsession). -## CDataConnection::CDataConnection +## `CDataConnection::CDataConnection` Instantiates and initializes a `CDataConnection` object. @@ -66,7 +66,7 @@ CDataConnection(const CDataConnection &ds); #### Parameters -*ds*
+*`ds`*\ [in] A reference to an existing data connection. ### Remarks @@ -75,7 +75,7 @@ The first override creates a new `CDataConnection` object with default settings. The second override creates a new `CDataConnection` object with settings equivalent to the data connection object you specify. -## CDataConnection::Copy +## `CDataConnection::Copy` Creates a copy of an existing data connection. @@ -87,10 +87,10 @@ CDataConnection& Copy(const CDataConnection & ds) throw(); #### Parameters -*ds*
+*`ds`*\ [in] A reference to an existing data connection to copy. -## CDataConnection::Open +## `CDataConnection::Open` Opens a connection to a data source using an initialization string. @@ -102,14 +102,14 @@ HRESULT Open(LPCOLESTR szInitString) throw(); #### Parameters -*szInitString*
+*`szInitString`*\ [in] The initialization string for the data source. -### Return Value +### Return value -A standard HRESULT. +A standard `HRESULT`. -## CDataConnection::OpenNewSession +## `CDataConnection::OpenNewSession` Opens a new session using the current connection object's data source. @@ -121,18 +121,18 @@ HRESULT OpenNewSession(CSession & session) throw(); #### Parameters -*session*
+*`session`*\ [in/out] A reference to the new session object. ### Remarks The new session uses the current connection object's contained data source object as its parent, and can access all of the same information as the data source. -### Return Value +### Return value -A standard HRESULT. +A standard `HRESULT`. -## CDataConnection::operator BOOL +## `CDataConnection::operator BOOL` Determines whether the current session is open or not. @@ -144,9 +144,9 @@ operator BOOL() throw(); ### Remarks -Returns **BOOL** (MFC typedef) value. **TRUE** means the current session is open; **FALSE** means the current session is closed. +Returns `BOOL` (MFC typedef) value. `TRUE` means the current session is open; `FALSE` means the current session is closed. -## CDataConnection::operator bool (OLE DB) +## `CDataConnection::operator bool` (OLE DB) Determines whether the current session is open or not. @@ -160,7 +160,7 @@ operator bool() throw(); Returns a **`bool`** (C++ data type) value. **`true`** means the current session is open; **`false`** means the current session is closed. -## CDataConnection::operator CDataSource& +## `CDataConnection::operator CDataSource&` Returns a reference to the contained `CDataSource` object. @@ -182,7 +182,7 @@ If you have a function (such as `func` below) that takes a `CDataSource` referen [!code-cpp[NVC_OLEDB_Consumer#4](../../data/oledb/codesnippet/cpp/cdataconnection-operator-cdatasource-amp_2.cpp)] -## CDataConnection::operator CDataSource* +## `CDataConnection::operator CDataSource*` Returns a pointer to the contained `CDataSource` object. @@ -196,9 +196,9 @@ operator const CDataSource*() throw(); This operator returns a pointer to the contained `CDataSource` object, allowing you to pass a `CDataConnection` object where a `CDataSource` pointer is expected. -See [operator CDataSource&](#op_cdata_amp) for a usage example. +See [`operator CDataSource&`](#op_cdata_amp) for a usage example. -## CDataConnection::operator CSession& +## `CDataConnection::operator CSession&` Returns a reference to the contained `CSession` object. @@ -220,7 +220,7 @@ If you have a function (such as `func` below) that takes a `CSession` reference, [!code-cpp[NVC_OLEDB_Consumer#6](../../data/oledb/codesnippet/cpp/cdataconnection-operator-csession-amp_2.cpp)] -## CDataConnection::operator CSession* +## `CDataConnection::operator CSession*` Returns a pointer to the contained `CSession` object. @@ -236,9 +236,9 @@ This operator returns a pointer to the contained `CSession` object, allowing you ### Example -See [operator CSession&](#op_csession_amp) for a usage example. +See [`operator CSession&`](#op_csession_amp) for a usage example. ## See also -[OLE DB Consumer Templates](../../data/oledb/ole-db-consumer-templates-cpp.md)
-[OLE DB Consumer Templates Reference](../../data/oledb/ole-db-consumer-templates-reference.md) +[OLE DB consumer templates](../../data/oledb/ole-db-consumer-templates-cpp.md)\ +[OLE DB consumer templates reference](../../data/oledb/ole-db-consumer-templates-reference.md) diff --git a/docs/parallel/concrt/reference/concurrency-namespace-operators.md b/docs/parallel/concrt/reference/concurrency-namespace-operators.md index 4e80dd0749c..24054bc061f 100644 --- a/docs/parallel/concrt/reference/concurrency-namespace-operators.md +++ b/docs/parallel/concrt/reference/concurrency-namespace-operators.md @@ -26,7 +26,7 @@ ms.assetid: 8e373f23-fc8e-49f7-82e6-ba0c57b822f8 :::column-end::: :::row-end::: -## operator|| Operator +## `operator||` Operator Creates a task that will complete successfully when either of the tasks supplied as arguments completes successfully. @@ -70,7 +70,7 @@ A task that completes successfully when either of the input tasks has completed If both of the tasks are canceled or throw exceptions, the returned task will complete in the canceled state, and one of the exceptions, if any are encountered, will be thrown when you call `get()` or `wait()` on that task. -## operator&& Operator +## `operator&&` Operator Creates a task that will complete successfully when both of the tasks supplied as arguments complete successfully. From a49a001bc72c30585e28c0adef54b0d37d07b616 Mon Sep 17 00:00:00 2001 From: Taojunshen Date: Thu, 25 Nov 2021 02:39:22 +0800 Subject: [PATCH 2/3] 11/24/2021 AM Publish (#3941) * Add gray border * LinkFix: cpp-docs-pr (2021-11) * Clarify C4146 per VCSig list (#3923) * Clarify C4146 per VCSig list * Fix link issues. * Update enable CMake Presets * fix rel links * fix github 3528 * acrolinx * change order of example * Add version info to NMAKE macro functions * Bulk fix entity `&` part 3 * threshhold test * Eliminate even more `&` entities * Minimum Viable Phix * Once more into the `&` breech * Add Visual Studio 2022 Platform Toolset Version * Add /fpcvt compiler option docs (#3886) * Add /fpcvt compiler option docs * Fix copypasta error * Update fp conversion intrinsics, too. * Replace deleted table row * Acrolinx pass * Fix TOC issues * Add useful links to intrinsics * Updates per John Morgan, plus acrolink * Update version info * Clean up rvalue reference article * Fix to `/fpcvt` per John Morgan email * Reformat WeakRef class document. * Minimizing entity form of & (#3916) * Initial pass minimizing on > entities (#3919) * Initial pass on > entities * Fix everything. * Try without `<` entities in title/desc * Clean up pass * Update docs/atl-mfc-shared/reference/cfiletime-class.md Co-authored-by: Tracey Torble Co-authored-by: Erika Co-authored-by: opbld16 Co-authored-by: Colin Robertson Co-authored-by: opbld17 Co-authored-by: Christopher McClister Co-authored-by: PRMerger16 Co-authored-by: Laura Brenner <90344170+laurabren@users.noreply.github.com> Co-authored-by: opbld15 Co-authored-by: TylerMSFT Co-authored-by: PRMerger18 Co-authored-by: PRMerger4 Co-authored-by: PRMerger6 Co-authored-by: MohammadHadi Attarieh Co-authored-by: PRMerger15 Co-authored-by: PRMerger10 Co-authored-by: Haig MacGregor <92189915+hmacgregor1@users.noreply.github.com> Co-authored-by: Tracey Torble From d9ac2de53b06467f23ad31d5f884d9d02213b272 Mon Sep 17 00:00:00 2001 From: Taojunshen Date: Fri, 26 Nov 2021 02:27:48 +0800 Subject: [PATCH 3/3] 11/25/2021 AM Publish (#3942) * Add gray border * LinkFix: cpp-docs-pr (2021-11) * Clarify C4146 per VCSig list (#3923) * Clarify C4146 per VCSig list * Fix link issues. * Update enable CMake Presets * fix rel links * fix github 3528 * acrolinx * change order of example * Add version info to NMAKE macro functions * Bulk fix entity `&` part 3 * threshhold test * Eliminate even more `&` entities * Minimum Viable Phix * Once more into the `&` breech * Add Visual Studio 2022 Platform Toolset Version * Add /fpcvt compiler option docs (#3886) * Add /fpcvt compiler option docs * Fix copypasta error * Update fp conversion intrinsics, too. * Replace deleted table row * Acrolinx pass * Fix TOC issues * Add useful links to intrinsics * Updates per John Morgan, plus acrolink * Update version info * Clean up rvalue reference article * Fix to `/fpcvt` per John Morgan email * Reformat WeakRef class document. * Minimizing entity form of & (#3916) * Initial pass minimizing on > entities (#3919) * Initial pass on > entities * Fix everything. * Try without `<` entities in title/desc * Clean up pass * Update docs/atl-mfc-shared/reference/cfiletime-class.md Co-authored-by: Tracey Torble Co-authored-by: Erika Co-authored-by: opbld16 Co-authored-by: Colin Robertson Co-authored-by: opbld17 Co-authored-by: Christopher McClister Co-authored-by: PRMerger16 Co-authored-by: Laura Brenner <90344170+laurabren@users.noreply.github.com> Co-authored-by: opbld15 Co-authored-by: TylerMSFT Co-authored-by: PRMerger18 Co-authored-by: PRMerger4 Co-authored-by: PRMerger6 Co-authored-by: MohammadHadi Attarieh Co-authored-by: PRMerger15 Co-authored-by: PRMerger10 Co-authored-by: Haig MacGregor <92189915+hmacgregor1@users.noreply.github.com> Co-authored-by: Tracey Torble