winrt::com_ptr 구조체 템플릿(C++/WinRT)
참조 계산 COM 스마트 포인터 템플릿입니다. com_ptr 템플릿 매개 변수로 지정된 인터페이스 또는 런타임 클래스 구현 형식에 대한 포인터를 나타냅니다. 프라이빗 원시 포인터를 통해 대상에 대한 참조 수를 자동으로 관리합니다.
Syntax
template <typename T>
struct com_ptr
템플릿 매개 변수
typename T
com_ptr 나타내는 포인터인 인터페이스 또는 런타임 클래스 구현 형식입니다. 스마트 포인터 대상의 형식입니다.
요구 사항
지원되는 최소 SDK: Windows SDK 버전 10.0.17134.0(Windows 10, 버전 1803)
네임스페이스: winrt
헤더: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h(기본적으로 포함)
멤버 형식 별칭
별칭 이름 | 형식 |
---|---|
com_ptr::type | 템플릿 매개 변수의 구현 정의 표현에 typename T 대한 동의어입니다. |
생성자
생성자 | Description |
---|---|
com_ptr::com_ptr 생성자 | 필요에 따라 입력 데이터의 복사 또는 이동을 사용하여 com_ptr 구조체의 새 instance 초기화합니다. |
멤버 함수
함수 | Description |
---|---|
com_ptr::as 함수 | 지원되는 경우 요청된 인터페이스를 반환합니다. 그렇지 않으면 을 throw합니다. |
com_ptr::attach 함수 | 대상에 대한 참조를 소유하는 원시 포인터에 연결합니다. 추가 참조가 추가되지 않습니다. |
com_ptr::capture 함수 | 지정된 함수 또는 메서드( winrt::check_hresult 자동으로 호출)를 호출하고 함수 또는 메서드에서 출력되는 인터페이스 포인터를 void** 로 캡처합니다. |
com_ptr::copy_from 함수 | 다른 포인터에서 복사합니다. 현재 참조된 모든 인터페이스 또는 개체에서 참조 횟수를 감소시키고, 원시 포인터 매개 변수를 복사하고, 이 매개 변수가 가리키는 인터페이스 또는 개체의 수명 관리를 시작합니다. |
com_ptr::copy_to 함수 | com_ptr 개체에서 다른 포인터로 복사합니다. 현재 참조된 인터페이스 또는 개체에 대한 참조 횟수를 증가시키고 해당 인터페이스 또는 개체의 메모리 주소를 매개 변수에 복사합니다. |
com_ptr::d etach 함수 | 참조 횟수를 감소하지 않고 참조된 인터페이스 또는 개체에서 분리하여 호출자에게 반환할 수 있습니다. |
com_ptr::get 함수 | 함수에 전달해야 하는 경우 기본 원시 포인터를 반환합니다. |
com_ptr::p ut 함수 | 기본 원시 포인터의 주소를 반환합니다. 이 함수는 포인터에 대한 포인터를 통해 참조를 out 매개 변수로 반환하는 메서드(예: COM 메서드)를 호출하는 데 도움이 됩니다. |
com_ptr::p ut_void 함수 | 기본 원시 포인터의 주소를 void에 대한 포인터에 대한 포인터로 반환합니다. 이 함수는 void에 대한 포인터를 통해 참조를 out 매개 변수로 반환하는 메서드(예: COM 메서드)를 호출하는 데 도움이 됩니다. |
com_ptr::try_as 함수 | 지원되는 경우 요청된 인터페이스를 반환합니다. 가 아닌 경우 또는 를 false 반환nullptr 합니다. |
com_ptr::try_capture 함수 | 실패 시 throw하지 않고 성공하거나 false 그렇지 않은 경우 반환을 반환 true 하는 com_ptr::capture 버전입니다. |
멤버 연산자
연산자 | Description |
---|---|
com_ptr::operator bool | 스마트 포인터가 인터페이스 또는 개체를 참조하는지 여부를 확인합니다. |
com_ptr::operator*(간접 참조 연산자) | 대상 형식 T에 대한 참조가 필요한 함수에 전달할 수 있도록 com_ptr 대상에 대한 참조를 반환합니다. |
com_ptr::operator=(대입 연산자) | com_ptr 개체에 값을 할당합니다. |
com_ptr::operator-> (화살표 연산자) | 참조된 인터페이스 또는 개체의 메서드에 대한 액세스 권한을 부여하려면 기본 원시 포인터를 반환합니다. |
무료 함수
함수 | Description |
---|---|
attach_abi 함수 | 대상에 대한 참조를 소유하는 원시 포인터에 com_ptr 개체를 연결합니다. 추가 참조가 추가되지 않습니다. |
detach_abi 함수 | 참조 수를 감소하지 않고 원시 인터페이스에서 com_ptr 개체를 분리하여 호출자에게 반환할 수 있습니다. |
swap 함수 | 두 com_ptr 매개 변수의 내용을 서로의 대상을 가리키도록 바꿉니다. |
무료 연산자
함수 | Description |
---|---|
operator!= (같지 않음 연산자) | 두 매개 변수가 서로 다른 대상을 참조하는지 여부를 나타내는 값을 반환합니다. |
연산자< (보다 작음 연산자) | 첫 번째 매개 변수의 대상이 두 번째 매개 변수보다 메모리에서 일찍 발생하는지 여부를 나타내는 값을 반환합니다. |
operator<= (less-than-or-equal-to 연산자) | 첫 번째 매개 변수의 대상이 두 번째 매개 변수의 대상보다 이전 메모리에서 발생하는지 또는 동일한 위치에서 발생하는지 여부를 나타내는 값을 반환합니다. |
operator== (같음 연산자) | 두 매개 변수가 동일한 인터페이스 및/또는 개체를 참조하는지 여부를 나타내는 값을 반환합니다. |
연산자> (보다 큼 연산자) | 첫 번째 매개 변수의 대상이 두 번째 매개 변수의 대상보다 메모리에서 나중에 발생하는지 여부를 나타내는 값을 반환합니다. |
operator>= (greater-than-or-equal-to 연산자) | 첫 번째 매개 변수의 대상이 두 번째 매개 변수의 대상보다 나중에 메모리에서 발생하는지 또는 동일한 위치에서 발생하는지 여부를 나타내는 값을 반환합니다. |
com_ptr::com_ptr 생성자
필요에 따라 입력 데이터의 복사 또는 이동을 사용하여 com_ptr 구조체의 새 instance 초기화합니다.
void*
생성자는 T*를 사용하고 소유권을 가정합니다. winrt::take_ownership_from_abi_t이 포인터를 해제할 책임이 com_ptr 전송되고 있음을 명시적으로 나타내는 표식 형식입니다. refcount가 정확히 1일 필요는 없습니다. 그것은 단지 책임이 이전되고 있다는 것을 말하는 것입니다.
Syntax
com_ptr(winrt::com_ptr const& other) noexcept;
com_ptr(std::nullptr_t = nullptr) noexcept;
com_ptr(void* ptr, winrt::take_ownership_from_abi_t) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U> const& other) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U>&& other) noexcept;
템플릿 매개 변수
typename U
입력 스마트 포인터가 가리키는 대상 형식입니다.
매개 변수
other
com_ptr 개체를 초기화하는 또 다른 com_ptr. 매개 변수의 T 는 com_ptr 개체의 T로 변환할 수 있어야 합니다.
com_ptr::as 함수
지원되는 경우 요청된 인터페이스를 반환합니다. 그렇지 않으면 을 throw합니다. 이 함수는 호출자에게 다시 전달할 필요가 없는 인터페이스를 쿼리하려는 경우에 유용합니다.
코드 예제는 프로젝션된 형식 및 인터페이스 인스턴스화 및 반환 섹션과 해당 항목의 다른 섹션을 참조하세요.
Syntax
template <typename To> auto as() const;
template <typename To> void as(To& to) const;
템플릿 매개 변수
typename To
요청된 인터페이스의 형식입니다.
매개 변수
to
요청된 인터페이스를 받을 값에 대한 참조입니다.
반환 값
요청된 인터페이스를 참조하는 com_ptr 또는 요청된 인터페이스(C++/WinRT 또는 타사에 의해 선언됨)에 대한 강력한 형식의 스마트 포인터입니다.
com_ptr::attach 함수
대상에 대한 참조를 소유하는 원시 포인터에 연결합니다. 추가 참조가 추가되지 않습니다. 필요한 경우 이 함수를 사용하여 참조를 병합할 수 있습니다.
구문
void attach(T* value) noexcept;
매개 변수
value
대상에 대한 참조를 소유하는 원시 포인터입니다.
com_ptr::capture 함수
지정된 함수 또는 메서드( winrt::check_hresult 자동으로 호출)를 호출하고 함수 또는 메서드에서 출력되는 인터페이스 포인터를 void**
로 캡처합니다.
winrt::capture 함수 템플릿도 참조하세요.
Syntax
template <typename F, typename...Args>
void capture(F function, Args&&...args);
template <typename O, typename M, typename...Args>
void capture(O* p, M method, Args&& ...args);
template <typename O, typename M, typename...Args>
void capture(winrt::com_ptr<O> const& object, M method, Args&&...args);
템플릿 매개 변수
typename F
자유 함수 또는 std::function과 같은 함수 개체 형식입니다.
typename O
인터페이스 형식입니다.
typename M
메서드 형식입니다.
typename Args
인수 형식이 0개 이상입니다.
매개 변수
function
형식 F
의 함수 개체입니다.
p
형식 O
의 개체에 대한 포인터입니다.
object
형식O
의 winrt::com_ptr.
method
형식M
의 메서드(에 의해 O
구현됨)입니다.
args
형식의 인수가 0개 이상입니다 Args
.
설명
- 오버로드는
capture(F function, Args&&...args)
함수 개체를 호출합니다. capture(O* p, M method, Args&& ...args)
오버로드는 포인터에서 메서드를 호출합니다.capture(winrt::com_ptr<O> const& object, M method, Args&&...args)
오버로드는 개체에서 메서드를 호출합니다.
모든 오버로드는 사용자가 제공하는 추가 인수를 통해(호출자에게) 전달됩니다. 또한 모든 오버로드는 이러한 호출에 필요한 두 개의 추가 인수,특히 REFIID ( winrt::com_ptr 대상의 ID) 및 void** ( winrt::com_ptr 대상에 대한 포인터의 주소)를 전달합니다.
예제
winrt::com_ptr<IDXGIAdapter> adapter
...
winrt::com_ptr<IDXGIFactory2> factory;
factory.capture(adapter, &IDXGIAdapter::GetParent);
com_ptr::copy_from 함수
다른 포인터에서 복사합니다. 현재 참조된 인터페이스 또는 개체에 대한 참조 횟수를 감소시키고, 원시 포인터 매개 변수를 복사하고, 이 매개 변수가 가리키는 인터페이스 또는 개체의 수명 관리를 시작합니다.
구문
void copy_from(T* other) noexcept;
매개 변수
other
com_ptr 개체에서 수명을 관리해야 하는 대상에 대한 원시 포인터입니다.
com_ptr::copy_to 함수
com_ptr 개체의 다른 포인터로 복사합니다. 현재 참조된 인터페이스 또는 개체에 대한 참조 수를 증분하고 해당 인터페이스 또는 개체의 메모리 주소를 매개 변수에 복사합니다. 이 함수를 사용하면 QueryInterface를 호출하지 않고 동일한 인터페이스에 대한 참조를 전달할 수 있습니다.
구문
void copy_to(T** other) const noexcept;
매개 변수
other
원시 포인터의 주소입니다. com_ptr 개체의 대상에 대한 포인터를 복사할 입니다.
com_ptr::d etach 함수
참조된 인터페이스 또는 개체에서 참조 횟수를 감소하지 않고 분리하여 호출자에게 반환할 수 있습니다.
구문
T* detach() noexcept;
반환 값
com_ptr 개체에서 참조하는 인터페이스 또는 개체에 대한 포인터입니다.
com_ptr::get 함수
함수에 전달해야 하는 경우 기본 원시 포인터를 반환합니다. 반환된 포인터 에서 AddRef, Release 또는 QueryInterface 를 호출할 수 있습니다.
구문
T* get() const noexcept;
반환 값
com_ptr 개체에서 참조하는 인터페이스 또는 개체에 대한 포인터입니다.
com_ptr::p ut 함수
기본 원시 포인터의 주소를 반환합니다. 이 함수는 포인터에 대한 포인터를 통해 참조를 out 매개 변수로 반환하는 메서드(예: COM 메서드)를 호출하는 데 도움이 됩니다. com_ptr 개체에 이미 대상이 있는 경우 이 함수를 호출하기 전에 com_ptr 개체에 할당 nullptr
합니다. 그렇지 않으면 함수가 어설션됩니다.
구문
T** put() noexcept;
반환 값
기본 원시 포인터의 주소입니다.
com_ptr::p ut_void 함수
기본 원시 포인터의 주소를 void에 대한 포인터로 반환합니다. 이 함수는 void에 대한 포인터를 통해 참조를 out 매개 변수로 반환하는 메서드(예: COM 메서드)를 호출하는 데 도움이 됩니다. com_ptr 개체에 이미 대상이 있는 경우 이 함수를 호출하기 전에 com_ptr 개체에 할당 nullptr
합니다. 그렇지 않으면 함수가 어설션됩니다.
구문
void** put_void() noexcept;
반환 값
void에 대한 포인터에 대한 포인터로 기본 원시 포인터의 주소입니다.
com_ptr::try_as 함수
지원되는 경우 요청된 인터페이스를 반환합니다. 반환 오버로드가 auto
아닌 경우 (반환 오버로드) 또는 false
(bool
반환 오버로드)를 반환 nullptr
합니다. 이 함수는 호출자에게 다시 전달할 필요가 없는 인터페이스를 쿼리하려는 경우에 유용합니다.
Syntax
template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;
템플릿 매개 변수
typename To
요청된 인터페이스의 형식입니다.
매개 변수
to
요청된 인터페이스를 받을 값에 대한 참조입니다.
반환 값
요청된 인터페이스를 참조하는 com_ptr 또는 요청된 인터페이스(C++/WinRT 또는 타사에 의해 선언됨)에 대한 강력한 형식의 스마트 포인터이며, nullptr
요청된 인터페이스가 지원되는 경우( -returning overload) 또는 false
(auto
bool
반환 오버로드)입니다.
com_ptr::try_capture 함수
실패 시 throw하지 않고 성공하거나 false
그렇지 않은 경우 반환 true
하는 com_ptr::capture 버전입니다.
winrt::try_capture 함수 템플릿도 참조하세요.
com_ptr::operator bool
스마트 포인터가 인터페이스 또는 개체를 참조하는지 여부를 확인합니다. 스마트 포인터가 인터페이스 또는 개체를 참조하지 않는 경우 논리적으로 null입니다. 그렇지 않으면 논리적으로 null이 아닙니다.
구문
explicit operator bool() const noexcept;
반환 값
true
스마트 포인터가 인터페이스 또는 개체를 참조하는 경우(논리적으로 null이 아님) 그렇지 않으면 false
(논리적으로 null).
com_ptr::operator*(간접 연산자)
대상 형식 T에 대한 참조가 필요한 함수에 전달할 수 있도록 com_ptr 대상에 대한 참조를 반환합니다.
구문
T& operator*() const noexcept;
반환 값
com_ptr 대상에 대한 참조입니다.
com_ptr::operator=(대입 연산자)
com_ptr 개체에 값을 할당합니다.
Syntax
winrt::com_ptr& operator=(winrt::com_ptr const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U> const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U>&& other) noexcept;
템플릿 매개 변수
typename U
할당되는 값이 가리키는 형식입니다.
매개 변수
other
com_ptr 개체에 할당할 com_ptr 값입니다. 매개 변수의 T 는 com_ptr 개체의 T로 변환할 수 있어야 합니다.
반환 값
com_ptr 개체에 대한 참조입니다.
com_ptr::operator-> (화살표 연산자)
참조된 인터페이스 또는 개체의 메서드에 대한 액세스 권한을 부여하려면 기본 원시 포인터를 반환합니다. 반환된 포인터에서 AddRef 또는 Release 를 호출할 수 없지만 QueryInterface를 호출할 수 있습니다.
구문
auto operator->() const noexcept;
반환 값
com_ptr 개체에서 참조하는 인터페이스 또는 개체에 대한 포인터입니다.
attach_abi 함수
대상에 대한 참조를 소유하는 원시 포인터에 com_ptr 개체를 연결합니다. 추가 참조가 추가되지 않습니다. 필요한 경우 이 함수를 사용하여 참조를 병합할 수 있습니다.
구문
void attach_abi(winrt::com_ptr<T>& object, T* value) noexcept;
매개 변수
object
작동할 com_ptr 개체입니다.
value
대상에 대한 참조를 소유하는 원시 포인터입니다.
detach_abi 함수
참조 수를 감소하지 않고 원시 인터페이스에서 com_ptr 개체를 분리하여 호출자에게 반환할 수 있습니다.
구문
auto detach_abi(winrt::com_ptr<T>& object) noexcept;
매개 변수
object
작동할 com_ptr 개체입니다.
반환 값
com_ptr 개체에서 참조하는 원시 인터페이스에 대한 포인터입니다.
operator!= (같지 않음 연산자)
두 매개 변수가 서로 다른 대상을 참조하는지 여부를 나타내는 값을 반환합니다.
구문
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator!=(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
매개 변수
left
right
대상의 메모리 주소가 다른 매개 변수의 메모리 주소와 비교할 com_ptr 값입니다 .
반환 값
true
두 매개 변수가 서로 다른 대상을 가리키면 이고, 그렇지 않으면 false
입니다.
연산자< (보다 작음 연산자)
첫 번째 매개 변수의 대상이 두 번째 매개 변수보다 메모리에서 일찍 발생하는지 여부를 나타내는 값을 반환합니다.
구문
template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
매개 변수
left
right
대상의 메모리 주소가 다른 매개 변수의 메모리 주소와 비교할 com_ptr 값입니다 .
반환 값
true
첫 번째 매개 변수의 대상 메모리 주소가 두 번째 매개 변수의 메모리 주소보다 작으면 이고, 그렇지 않으면 false
입니다.
operator<= (less-than-or-equal-to 연산자)
첫 번째 매개 변수의 대상이 두 번째 매개 변수의 대상보다 이전 메모리에서 발생하는지 또는 동일한 위치에서 발생하는지 여부를 나타내는 값을 반환합니다.
구문
template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
매개 변수
left
right
대상의 메모리 주소가 다른 매개 변수의 메모리 주소와 비교할 com_ptr 값입니다 .
반환 값
true
첫 번째 매개 변수의 대상 메모리 주소가 두 번째 매개 변수의 메모리 주소보다 작거나 같으면 이고, 그렇지 않으면 false
입니다.
operator== (같음 연산자)
두 매개 변수가 동일한 인터페이스 및/또는 개체를 참조하는지 여부를 나타내는 값을 반환합니다.
구문
template <typename T> bool operator==(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator==(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
매개 변수
left
right
대상의 메모리 주소가 다른 매개 변수의 메모리 주소와 비교할 com_ptr 값입니다 .
반환 값
true
두 매개 변수가 동일한 대상을 가리키면 이고, 그렇지 않으면 false
입니다.
연산자> (보다 큼 연산자)
첫 번째 매개 변수의 대상이 두 번째 매개 변수의 대상보다 메모리에서 나중에 발생하는지 여부를 나타내는 값을 반환합니다.
구문
template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
매개 변수
left
right
대상의 메모리 주소가 다른 매개 변수의 메모리 주소와 비교할 com_ptr 값입니다 .
반환 값
true
첫 번째 매개 변수의 대상 메모리 주소가 두 번째 매개 변수보다 크면 이고, 그렇지 않으면 false
입니다.
operator>= (greater-than-or-equal-to 연산자)
첫 번째 매개 변수의 대상이 두 번째 매개 변수의 대상보다 나중에 메모리에서 발생하는지 또는 동일한 위치에서 발생하는지 여부를 나타내는 값을 반환합니다.
구문
template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
매개 변수
left
right
대상의 메모리 주소가 다른 매개 변수의 메모리 주소와 비교할 com_ptr 값입니다 .
반환 값
true
첫 번째 매개 변수의 대상 메모리 주소가 두 번째 매개 변수의 메모리 주소보다 크거나 같으면 이고, 그렇지 않으면 false
입니다.
swap 함수
두 com_ptr 매개 변수의 내용을 서로의 대상을 가리키도록 바꿉니다.
구문
void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;
매개 변수
left
right
포인터가 다른 매개 변수의 포인터와 상호 교환되는 com_ptr 값입니다.
추가 정보
피드백
https://aka.ms/ContentUserFeedback
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요.다음에 대한 사용자 의견 제출 및 보기