Uwaga
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Otoka dla obiektu COM, który może być używany jako składowa klasy CLR. Otoka automatyzuje również zarządzanie okresem istnienia obiektu COM, zwalniając wszystkie odwołania należące do obiektu, gdy jest wywoływany jego destruktor. Analogicznie do klasy CComPtr.
Składnia
template<class _interface_type>
ref class ptr;
Parametry
_interface_type
Interfejs COM.
Uwagi
Można com::ptr
również użyć jako zmiennej funkcji lokalnej, aby uprościć różne zadania MODELU COM i zautomatyzować zarządzanie okresem istnienia.
Nie com::ptr
można użyć elementu bezpośrednio jako parametru funkcji; zamiast tego użyj operatora odwołania Śledzenie lub operatora Dojście do obiektu (^).
com::ptr
Nie można bezpośrednio zwrócić obiektu z funkcji; zamiast tego użyj uchwytu.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Wywołanie metod publicznych klasy powoduje wywołania zawartego IXMLDOMDocument
obiektu. Przykład tworzy wystąpienie dokumentu XML, wypełnia go prostym kodem XML i wykonuje uproszczony przewodnik po węzłach w przeanalizowanym drzewie dokumentów, aby wydrukować kod XML w konsoli programu .
// comptr.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
void LoadXml(String^ xml) {
pin_ptr<const wchar_t> pinnedXml = PtrToStringChars(xml);
BSTR bstr = NULL;
try {
// load some XML into the document
bstr = ::SysAllocString(pinnedXml);
if (NULL == bstr) {
throw gcnew OutOfMemoryException;
}
VARIANT_BOOL bIsSuccessful = false;
// use operator -> to call IXMODOMDocument member function
Marshal::ThrowExceptionForHR(m_ptrDoc->loadXML(bstr, &bIsSuccessful));
}
finally {
::SysFreeString(bstr);
}
}
// simplified function to write just the first xml node to the console
void WriteXml() {
IXMLDOMNode* pNode = NULL;
try {
// the first child of the document is the first real xml node
Marshal::ThrowExceptionForHR(m_ptrDoc->get_firstChild(&pNode));
if (NULL != pNode) {
WriteNode(pNode);
}
}
finally {
if (NULL != pNode) {
pNode->Release();
}
}
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
// simplified function that only writes the node
void WriteNode(IXMLDOMNode* pNode) {
BSTR bstr = NULL;
try {
// write out the name and text properties
Marshal::ThrowExceptionForHR(pNode->get_nodeName(&bstr));
String^ strName = gcnew String(bstr);
Console::Write("<{0}>", strName);
::SysFreeString(bstr);
bstr = NULL;
Marshal::ThrowExceptionForHR(pNode->get_text(&bstr));
Console::Write(gcnew String(bstr));
::SysFreeString(bstr);
bstr = NULL;
Console::WriteLine("</{0}>", strName);
}
finally {
::SysFreeString(bstr);
}
}
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// use the ref class to handle an XML DOM Document object
int main() {
try {
// create the class from a progid string
XmlDocument doc("Msxml2.DOMDocument.3.0");
// stream some xml into the document
doc.LoadXml("<word>persnickety</word>");
// write the document to the console
doc.WriteXml();
}
catch (Exception^ e) {
Console::WriteLine(e);
}
}
<word>persnickety</word>
Elementy członkowskie
Konstruktory publiczne
Nazwa/nazwisko | opis |
---|---|
ptr::ptr | Konstruuje obiekt com::ptr COM do opakowania. |
ptr::~ptr | Destrukuje element com::ptr . |
Metody publiczne
Nazwa/nazwisko | opis |
---|---|
ptr::Attach | Dołącza obiekt COM do obiektu com::ptr . |
ptr::CreateInstance | Tworzy wystąpienie obiektu COM w obiekcie com::ptr . |
ptr::Detach | Daje własność obiektu COM, zwracając wskaźnik do obiektu. |
ptr::GetInterface | Tworzy wystąpienie obiektu COM w obiekcie com::ptr . |
ptr::QueryInterface | Wysyła zapytanie do obiektu COM należącego do interfejsu i dołącza wynik do innego com::ptr obiektu . |
ptr::Release | Zwalnia wszystkie odwołania należące do obiektu COM. |
Operatory publiczne
Nazwa/nazwisko | opis |
---|---|
ptr::operator-> |
Operator dostępu do składowych używany do wywoływania metod na należącym do niego obiekcie COM. |
ptr::operator= | Dołącza obiekt COM do obiektu com::ptr . |
ptr::operator, wartość logiczna | Operator do użycia com::ptr w wyrażeniu warunkowym. |
ptr::operator! | Operator określający, czy należący do niego obiekt COM jest nieprawidłowy. |
Wymagania
Plik<nagłówka msclr\com\ptr.h>
Przestrzeń nazw msclr::com
ptr::ptr
Zwraca wskaźnik do należącego obiektu COM.
ptr();
ptr(
_interface_type * p
);
Parametry
P
Wskaźnik interfejsu COM.
Uwagi
Konstruktor no-argument przypisuje nullptr
do uchwytu obiektu bazowego. Przyszłe wywołania com::ptr
obiektu zweryfikują wewnętrzny obiekt i w trybie dyskretnym kończą się niepowodzeniem, dopóki obiekt nie zostanie utworzony lub dołączony.
Konstruktor z jednym argumentem dodaje odwołanie do obiektu COM, ale nie zwalnia odwołania obiektu wywołującego, więc obiekt wywołujący musi wywołać Release
obiekt COM, aby naprawdę zrezygnować z kontroli. Po wywołaniu com::ptr
destruktora zostanie automatycznie wydany odwołania do obiektu COM.
Przekazywanie NULL
do tego konstruktora jest takie samo jak wywoływanie wersji bez argumentu.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Demonstruje użycie obu wersji konstruktora.
// comptr_ptr.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
// construct the internal com::ptr with a COM object
XmlDocument(IXMLDOMDocument* pDoc) : m_ptrDoc(pDoc) {}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// use the ref class to handle an XML DOM Document object
int main() {
IXMLDOMDocument* pDoc = NULL;
try {
// create an XML DOM document object
Marshal::ThrowExceptionForHR(CoCreateInstance(CLSID_DOMDocument30, NULL,
CLSCTX_ALL, IID_IXMLDOMDocument, (void**)&pDoc));
// construct the ref class with the COM object
XmlDocument doc1(pDoc);
// or create the class from a progid string
XmlDocument doc2("Msxml2.DOMDocument.3.0");
}
// doc1 and doc2 destructors are called when they go out of scope
// and the internal com::ptr releases its reference to the COM object
catch (Exception^ e) {
Console::WriteLine(e);
}
finally {
if (NULL != pDoc) {
pDoc->Release();
}
}
}
ptr::~ptr
Destrukuje element com::ptr
.
~ptr();
Uwagi
W przypadku zniszczenia com::ptr
wszystkie odwołania są do niego własnością obiektu COM. Zakładając, że nie ma żadnych innych odwołań przechowywanych w obiekcie COM, obiekt COM zostanie usunięty i jego pamięć zostanie zwolniona.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. main
W funkcji destruktory dwóch XmlDocument
obiektów będą wywoływane, gdy wyjdą z zakresu try
bloku, co spowoduje wywołanie bazowego com::ptr
destruktora, zwalniając wszystkie odwołania własności do obiektu COM.
// comptr_dtor.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
// construct the internal com::ptr with a COM object
XmlDocument(IXMLDOMDocument* pDoc) : m_ptrDoc(pDoc) {}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// use the ref class to handle an XML DOM Document object
int main() {
IXMLDOMDocument* pDoc = NULL;
try {
// create an XML DOM document object
Marshal::ThrowExceptionForHR(CoCreateInstance(CLSID_DOMDocument30, NULL,
CLSCTX_ALL, IID_IXMLDOMDocument, (void**)&pDoc));
// construct the ref class with the COM object
XmlDocument doc1(pDoc);
// or create the class from a progid string
XmlDocument doc2("Msxml2.DOMDocument.3.0");
}
// doc1 and doc2 destructors are called when they go out of scope
// and the internal com::ptr releases its reference to the COM object
catch (Exception^ e) {
Console::WriteLine(e);
}
finally {
if (NULL != pDoc) {
pDoc->Release();
}
}
}
ptr::Attach
Dołącza obiekt COM do obiektu com::ptr
.
void Attach(
_interface_type * _right
);
Parametry
_Prawy
Wskaźnik interfejsu COM do dołączenia.
Wyjątki
com::ptr
Jeśli obiekt COM jest już właścicielem odwołania do obiektu COM, Attach
zwraca wartość InvalidOperationException.
Uwagi
Wywołanie odwołujące się do Attach
obiektu COM, ale nie zwalnia odwołania obiektu wywołującego do niego.
Przekazywanie NULL
do Attach
wyników nie powoduje podjęcia żadnej akcji.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Funkcja ReplaceDocument
składowa najpierw wywołuje Release
dowolny wcześniej należący obiekt, a następnie wywołuje metodę Attach
dołączania nowego obiektu dokumentu.
// comptr_attach.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
// replace currently held COM object with another one
void ReplaceDocument(IXMLDOMDocument* pDoc) {
// release current document object
m_ptrDoc.Release();
// attach the new document object
m_ptrDoc.Attach(pDoc);
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// unmanaged function that creates a raw XML DOM Document object
IXMLDOMDocument* CreateDocument() {
IXMLDOMDocument* pDoc = NULL;
Marshal::ThrowExceptionForHR(CoCreateInstance(CLSID_DOMDocument30, NULL,
CLSCTX_INPROC_SERVER, IID_IXMLDOMDocument, (void**)&pDoc));
return pDoc;
}
// use the ref class to handle an XML DOM Document object
int main() {
IXMLDOMDocument* pDoc = NULL;
try {
// create the class from a progid string
XmlDocument doc("Msxml2.DOMDocument.3.0");
// get another document object from unmanaged function and
// store it in place of the one held by our ref class
pDoc = CreateDocument();
doc.ReplaceDocument(pDoc);
// no further need for raw object reference
pDoc->Release();
pDoc = NULL;
}
catch (Exception^ e) {
Console::WriteLine(e);
}
finally {
if (NULL != pDoc) {
pDoc->Release();
}
}
}
ptr::CreateInstance
Tworzy wystąpienie obiektu COM w obiekcie com::ptr
.
void CreateInstance(
System::String ^ progid,
LPUNKNOWN pouter,
DWORD cls_context
);
void CreateInstance(
System::String ^ progid,
LPUNKNOWN pouter
);
void CreateInstance(
System::String ^ progid
);
void CreateInstance(
const wchar_t * progid,
LPUNKNOWN pouter,
DWORD cls_context
);
void CreateInstance(
const wchar_t * progid,
LPUNKNOWN pouter
);
void CreateInstance(
const wchar_t * progid
);
void CreateInstance(
REFCLSID rclsid,
LPUNKNOWN pouter,
DWORD cls_context
);
void CreateInstance(
REFCLSID rclsid,
LPUNKNOWN pouter
);
void CreateInstance(
REFCLSID rclsid
);
Parametry
progid
ProgID
Ciąg.
pouter
Wskaźnik do interfejsu IUnknown obiektu agregacji (kontrolka IUnknown). Jeśli pouter
nie zostanie określony, NULL
zostanie użyty.
cls_context
Kontekst, w którym zostanie uruchomiony kod zarządzający nowo utworzonym obiektem. Wartości są pobierane z CLSCTX
wyliczenia. Jeśli cls_context
nie zostanie określona, zostanie użyta wartość CLSCTX_ALL.
rclsid
CLSID
skojarzone z danymi i kodem, które zostaną użyte do utworzenia obiektu.
Wyjątki
com::ptr
Jeśli obiekt COM jest już właścicielem odwołania do obiektu COM, CreateInstance
zwraca wartość InvalidOperationException.
Ta funkcja wywołuje CoCreateInstance
i używa metody ThrowExceptionForHR , aby przekonwertować dowolny błąd HRESULT
na odpowiedni wyjątek.
Uwagi
CreateInstance
używa CoCreateInstance
metody do utworzenia nowego wystąpienia określonego obiektu zidentyfikowanego na podstawie identyfikatora ProgID lub CLSID. Odwołania com::ptr
do nowo utworzonego obiektu i automatycznie zwalniają wszystkie odwołania własności po zniszczeniu.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Konstruktory klas używają dwóch różnych formularzy CreateInstance
, aby utworzyć obiekt dokumentu na podstawie identyfikatora ProgID lub CLSID oraz CLSCTX.
// comptr_createinstance.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
XmlDocument(REFCLSID clsid, DWORD clsctx) {
m_ptrDoc.CreateInstance(clsid, NULL, clsctx);
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// use the ref class to handle an XML DOM Document object
int main() {
try {
// create the class from a progid string
XmlDocument doc1("Msxml2.DOMDocument.3.0");
// or from a clsid with specific CLSCTX
XmlDocument doc2(CLSID_DOMDocument30, CLSCTX_INPROC_SERVER);
}
catch (Exception^ e) {
Console::WriteLine(e);
}
}
ptr::Detach
Daje własność obiektu COM, zwracając wskaźnik do obiektu.
_interface_type * Detach();
Wartość zwracana
Wskaźnik do obiektu COM.
Jeśli żaden obiekt nie jest własnością, zwracana jest wartość NULL.
Wyjątki
QueryInterface
Wewnętrznie wywoływany jest obiekt COM, a każdy błąd HRESULT
jest konwertowany na wyjątek przez ThrowExceptionForHR.
Uwagi
Detach
najpierw dodaje odwołanie do obiektu COM w imieniu obiektu wywołującego, a następnie zwalnia wszystkie odwołania należące do obiektu com::ptr
. Obiekt wywołujący musi ostatecznie zwolnić zwrócony obiekt, aby go zniszczyć.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Funkcja DetachDocument
składowa wywołuje Detach
funkcję, aby zrezygnować z własności obiektu COM i zwrócić wskaźnik do obiektu wywołującego.
// comptr_detach.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
// detach the COM object and return it
// this releases the internal reference to the object
IXMLDOMDocument* DetachDocument() {
return m_ptrDoc.Detach();
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// unmanaged function that loads XML into a raw XML DOM Document object
HRESULT LoadXml(IXMLDOMDocument* pDoc, BSTR bstrXml) {
HRESULT hr = S_OK;
VARIANT_BOOL bSuccess;
hr = pDoc->loadXML(bstrXml, &bSuccess);
if (S_OK == hr && !bSuccess) {
hr = E_FAIL;
}
return hr;
}
// use the ref class to handle an XML DOM Document object
int main() {
IXMLDOMDocument* pDoc = NULL;
BSTR bstrXml = NULL;
try {
// create the class from a progid string
XmlDocument doc("Msxml2.DOMDocument.3.0");
bstrXml = ::SysAllocString(L"<word>persnickety</word>");
if (NULL == bstrXml) {
throw gcnew OutOfMemoryException("bstrXml");
}
// detach the document object from the ref class
pDoc = doc.DetachDocument();
// use unmanaged function and raw object to load xml
Marshal::ThrowExceptionForHR(LoadXml(pDoc, bstrXml));
// release document object as the ref class no longer owns it
pDoc->Release();
pDoc = NULL;
}
catch (Exception^ e) {
Console::WriteLine(e);
}
finally {
if (NULL != pDoc) {
pDoc->Release();
}
}
}
ptr::GetInterface
Zwraca wskaźnik do należącego obiektu COM.
_interface_type * GetInterface();
Wartość zwracana
Wskaźnik do należącego do niego obiektu COM.
Wyjątki
QueryInterface
Wewnętrznie wywoływany jest obiekt COM, a każdy błąd HRESULT
jest konwertowany na wyjątek przez ThrowExceptionForHR.
Uwagi
Element com::ptr
dodaje odwołanie do obiektu COM w imieniu obiektu wywołującego, a także przechowuje własne odwołanie do obiektu COM. Obiekt wywołujący musi ostatecznie zwolnić odwołanie do zwróconego obiektu lub nigdy nie zostanie zniszczony.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Funkcja GetDocument
składowa używa GetInterface
metody , aby zwrócić wskaźnik do obiektu COM.
// comptr_getinterface.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
// add a reference to and return the COM object
// but keep an internal reference to the object
IXMLDOMDocument* GetDocument() {
return m_ptrDoc.GetInterface();
}
// simplified function that only writes the first node
void WriteDocument() {
IXMLDOMNode* pNode = NULL;
BSTR bstr = NULL;
try {
// use operator -> to call XML Doc member
Marshal::ThrowExceptionForHR(m_ptrDoc->get_firstChild(&pNode));
if (NULL != pNode) {
// write out the xml
Marshal::ThrowExceptionForHR(pNode->get_nodeName(&bstr));
String^ strName = gcnew String(bstr);
Console::Write("<{0}>", strName);
::SysFreeString(bstr);
bstr = NULL;
Marshal::ThrowExceptionForHR(pNode->get_text(&bstr));
Console::Write(gcnew String(bstr));
::SysFreeString(bstr);
bstr = NULL;
Console::WriteLine("</{0}>", strName);
}
}
finally {
if (NULL != pNode) {
pNode->Release();
}
::SysFreeString(bstr);
}
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// unmanaged function that loads XML into a raw XML DOM Document object
HRESULT LoadXml(IXMLDOMDocument* pDoc, BSTR bstrXml) {
HRESULT hr = S_OK;
VARIANT_BOOL bSuccess;
hr = pDoc->loadXML(bstrXml, &bSuccess);
if (S_OK == hr && !bSuccess) {
hr = E_FAIL;
}
return hr;
}
// use the ref class to handle an XML DOM Document object
int main() {
IXMLDOMDocument* pDoc = NULL;
BSTR bstrXml = NULL;
try {
// create the class from a progid string
XmlDocument doc("Msxml2.DOMDocument.3.0");
bstrXml = ::SysAllocString(L"<word>persnickety</word>");
if (NULL == bstrXml) {
throw gcnew OutOfMemoryException("bstrXml");
}
// detach the document object from the ref class
pDoc = doc.GetDocument();
// use unmanaged function and raw object to load xml
Marshal::ThrowExceptionForHR(LoadXml(pDoc, bstrXml));
// release reference to document object (but ref class still references it)
pDoc->Release();
pDoc = NULL;
// call another function on the ref class
doc.WriteDocument();
}
catch (Exception^ e) {
Console::WriteLine(e);
}
finally {
if (NULL != pDoc) {
pDoc->Release();
}
}
}
<word>persnickety</word>
ptr::QueryInterface
Wysyła zapytanie do obiektu COM należącego do interfejsu i dołącza wynik do innego com::ptr
obiektu .
template<class _other_type>
void QueryInterface(
ptr<_other_type> % other
);
Parametry
inny
Spowoduje com::ptr
to pobranie interfejsu.
Wyjątki
QueryInterface
Wewnętrznie wywoływany jest obiekt COM, a każdy błąd HRESULT
jest konwertowany na wyjątek przez ThrowExceptionForHR.
Uwagi
Użyj tej metody, aby utworzyć otokę COM dla innego interfejsu obiektu COM należącego do bieżącej otoki. Ta metoda wywołuje QueryInterface
obiekt COM własnością, aby zażądać wskaźnika do określonego interfejsu obiektu COM i dołącza zwrócony wskaźnik interfejsu do przekazanego elementu com::ptr
.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Funkcja WriteTopLevelNode
składowa służy QueryInterface
do wypełniania lokalnego com::ptr
elementem , IXMLDOMNode
a następnie przekazuje com::ptr
element (przez odwołanie do śledzenia) do prywatnej funkcji członkowskiej, która zapisuje nazwę węzła i właściwości tekstowe w konsoli.
// comptr_queryinterface.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
void LoadXml(String^ xml) {
pin_ptr<const wchar_t> pinnedXml = PtrToStringChars(xml);
BSTR bstr = NULL;
try {
// load some XML into our document
bstr = ::SysAllocString(pinnedXml);
if (NULL == bstr) {
throw gcnew OutOfMemoryException;
}
VARIANT_BOOL bIsSuccessful = false;
// use operator -> to call IXMODOMDocument member function
Marshal::ThrowExceptionForHR(m_ptrDoc->loadXML(bstr, &bIsSuccessful));
}
finally {
::SysFreeString(bstr);
}
}
// write the top level node to the console
void WriteTopLevelNode() {
com::ptr<IXMLDOMNode> ptrNode;
// query for the top level node interface
m_ptrDoc.QueryInterface(ptrNode);
WriteNode(ptrNode);
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
// simplified function that only writes the node
void WriteNode(com::ptr<IXMLDOMNode> % node) {
BSTR bstr = NULL;
try {
// write out the name and text properties
Marshal::ThrowExceptionForHR(node->get_nodeName(&bstr));
String^ strName = gcnew String(bstr);
Console::Write("<{0}>", strName);
::SysFreeString(bstr);
bstr = NULL;
Marshal::ThrowExceptionForHR(node->get_text(&bstr));
Console::Write(gcnew String(bstr));
::SysFreeString(bstr);
bstr = NULL;
Console::WriteLine("</{0}>", strName);
}
finally {
::SysFreeString(bstr);
}
}
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// use the ref class to handle an XML DOM Document object
int main() {
try {
// create the class from a progid string
XmlDocument doc("Msxml2.DOMDocument.3.0");
// stream some xml into the document
doc.LoadXml("<word>persnickety</word>");
// write the document to the console
doc.WriteTopLevelNode();
}
catch (Exception^ e) {
Console::WriteLine(e);
}
}
<#document>persnickety</#document>
ptr::Release
Zwalnia wszystkie odwołania należące do obiektu COM.
void Release();
Uwagi
Wywołanie tej funkcji zwalnia wszystkie odwołania należące do obiektu COM i ustawia wewnętrzne dojście do obiektu COM na nullptr
wartość . Jeśli nie istnieją żadne inne odwołania do obiektu COM, zostanie on zniszczony.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Funkcja ReplaceDocument
składowa używa Release
polecenia do zwolnienia dowolnego wcześniejszego obiektu dokumentu przed dołączeniem nowego dokumentu.
// comptr_release.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
// replace currently held COM object with another one
void ReplaceDocument(IXMLDOMDocument* pDoc) {
// release current document object
m_ptrDoc.Release();
// attach the new document object
m_ptrDoc.Attach(pDoc);
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// unmanaged function that creates a raw XML DOM Document object
IXMLDOMDocument* CreateDocument() {
IXMLDOMDocument* pDoc = NULL;
Marshal::ThrowExceptionForHR(CoCreateInstance(CLSID_DOMDocument30, NULL,
CLSCTX_INPROC_SERVER, IID_IXMLDOMDocument, (void**)&pDoc));
return pDoc;
}
// use the ref class to handle an XML DOM Document object
int main() {
IXMLDOMDocument* pDoc = NULL;
try {
// create the class from a progid string
XmlDocument doc("Msxml2.DOMDocument.3.0");
// get another document object from unmanaged function and
// store it in place of the one held by our ref class
pDoc = CreateDocument();
doc.ReplaceDocument(pDoc);
// no further need for raw object reference
pDoc->Release();
pDoc = NULL;
}
catch (Exception^ e) {
Console::WriteLine(e);
}
finally {
if (NULL != pDoc) {
pDoc->Release();
}
}
}
ptr::operator->
Operator dostępu do składowych używany do wywoływania metod na należącym do niego obiekcie COM.
_detail::smart_com_ptr<_interface_type> operator->();
Wartość zwracana
A smart_com_ptr
do obiektu COM.
Wyjątki
QueryInterface
Wewnętrznie wywoływany jest obiekt COM, a każdy błąd HRESULT
jest konwertowany na wyjątek przez ThrowExceptionForHR.
Uwagi
Ten operator umożliwia wywoływanie metod obiektu COM należącego do użytkownika. Zwraca tymczasową funkcję smart_com_ptr
, która automatycznie obsługuje własne AddRef
i Release
.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Funkcja WriteDocument
używa operator->
metody do wywoływania get_firstChild
elementu członkowskiego obiektu dokumentu.
// comptr_op_member.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
// add a reference to and return the COM object
// but keep an internal reference to the object
IXMLDOMDocument* GetDocument() {
return m_ptrDoc.GetInterface();
}
// simplified function that only writes the first node
void WriteDocument() {
IXMLDOMNode* pNode = NULL;
BSTR bstr = NULL;
try {
// use operator -> to call XML Doc member
Marshal::ThrowExceptionForHR(m_ptrDoc->get_firstChild(&pNode));
if (NULL != pNode) {
// write out the xml
Marshal::ThrowExceptionForHR(pNode->get_nodeName(&bstr));
String^ strName = gcnew String(bstr);
Console::Write("<{0}>", strName);
::SysFreeString(bstr);
bstr = NULL;
Marshal::ThrowExceptionForHR(pNode->get_text(&bstr));
Console::Write(gcnew String(bstr));
::SysFreeString(bstr);
bstr = NULL;
Console::WriteLine("</{0}>", strName);
}
}
finally {
if (NULL != pNode) {
pNode->Release();
}
::SysFreeString(bstr);
}
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// unmanaged function that loads XML into a raw XML DOM Document object
HRESULT LoadXml(IXMLDOMDocument* pDoc, BSTR bstrXml) {
HRESULT hr = S_OK;
VARIANT_BOOL bSuccess;
hr = pDoc->loadXML(bstrXml, &bSuccess);
if (S_OK == hr && !bSuccess) {
hr = E_FAIL;
}
return hr;
}
// use the ref class to handle an XML DOM Document object
int main() {
IXMLDOMDocument* pDoc = NULL;
BSTR bstrXml = NULL;
try {
// create the class from a progid string
XmlDocument doc("Msxml2.DOMDocument.3.0");
bstrXml = ::SysAllocString(L"<word>persnickety</word>");
if (NULL == bstrXml) {
throw gcnew OutOfMemoryException("bstrXml");
}
// detach the document object from the ref class
pDoc = doc.GetDocument();
// use unmanaged function and raw object to load xml
Marshal::ThrowExceptionForHR(LoadXml(pDoc, bstrXml));
// release reference to document object (but ref class still references it)
pDoc->Release();
pDoc = NULL;
// call another function on the ref class
doc.WriteDocument();
}
catch (Exception^ e) {
Console::WriteLine(e);
}
finally {
if (NULL != pDoc) {
pDoc->Release();
}
}
}
<word>persnickety</word>
ptr::operator=
Dołącza obiekt COM do obiektu com::ptr
.
ptr<_interface_type> % operator=(
_interface_type * _right
);
Parametry
_Prawy
Wskaźnik interfejsu COM do dołączenia.
Wartość zwracana
Odwołanie do śledzenia w pliku com::ptr
.
Wyjątki
com::ptr
Jeśli obiekt COM jest już właścicielem odwołania do obiektu COM, operator=
zwraca wartość InvalidOperationException.
Uwagi
Przypisanie obiektu COM do odwołania do com::ptr
obiektu COM, ale nie zwalnia odwołania obiektu wywołującego do niego.
Ten operator ma taki sam efekt jak Attach
.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Funkcja ReplaceDocument
składowa najpierw wywołuje Release
dowolny wcześniej należący obiekt, a następnie używa operator=
go do dołączania nowego obiektu dokumentu.
// comptr_op_assign.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
// construct the internal com::ptr with a null interface
// and use CreateInstance to fill it
XmlDocument(String^ progid) {
m_ptrDoc.CreateInstance(progid);
}
// replace currently held COM object with another one
void ReplaceDocument(IXMLDOMDocument* pDoc) {
// release current document object
m_ptrDoc.Release();
// attach the new document object
m_ptrDoc = pDoc;
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// unmanaged function that creates a raw XML DOM Document object
IXMLDOMDocument* CreateDocument() {
IXMLDOMDocument* pDoc = NULL;
Marshal::ThrowExceptionForHR(CoCreateInstance(CLSID_DOMDocument30, NULL,
CLSCTX_INPROC_SERVER, IID_IXMLDOMDocument, (void**)&pDoc));
return pDoc;
}
// use the ref class to handle an XML DOM Document object
int main() {
IXMLDOMDocument* pDoc = NULL;
try {
// create the class from a progid string
XmlDocument doc("Msxml2.DOMDocument.3.0");
// get another document object from unmanaged function and
// store it in place of the one held by the ref class
pDoc = CreateDocument();
doc.ReplaceDocument(pDoc);
// no further need for raw object reference
pDoc->Release();
pDoc = NULL;
}
catch (Exception^ e) {
Console::WriteLine(e);
}
finally {
if (NULL != pDoc) {
pDoc->Release();
}
}
}
ptr::operator, wartość logiczna
Operator do użycia com::ptr
w wyrażeniu warunkowym.
operator bool();
Wartość zwracana
true
jeśli należący do niego obiekt COM jest prawidłowy; false
inaczej.
Uwagi
Obiekt COM będący własnością jest prawidłowy, jeśli nie nullptr
jest .
Ten operator konwertuje na element, który _detail_class::_safe_bool
jest bezpieczniejszy, ponieważ bool
nie można go przekonwertować na typ całkowity.
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Funkcja CreateInstance
składowa jest używana operator bool
po utworzeniu nowego obiektu dokumentu w celu określenia, czy jest on prawidłowy i czy jest zapisywany w konsoli programu .
// comptr_op_bool.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
void CreateInstance(String^ progid) {
if (!m_ptrDoc) {
m_ptrDoc.CreateInstance(progid);
if (m_ptrDoc) { // uses operator bool
Console::WriteLine("DOM Document created.");
}
}
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// use the ref class to handle an XML DOM Document object
int main() {
try {
XmlDocument doc;
// create the instance from a progid string
doc.CreateInstance("Msxml2.DOMDocument.3.0");
}
catch (Exception^ e) {
Console::WriteLine(e);
}
}
DOM Document created.
ptr::operator!
Operator określający, czy należący do niego obiekt COM jest nieprawidłowy.
bool operator!();
Wartość zwracana
true
jeśli należący do niego obiekt COM jest nieprawidłowy; false
inaczej.
Uwagi
Obiekt COM będący własnością jest prawidłowy, jeśli nie nullptr
jest .
Przykład
W tym przykładzie zaimplementowano klasę CLR, która używa com::ptr
klasy do opakowania jej prywatnego obiektu członkowskiego IXMLDOMDocument
. Funkcja CreateInstance
składowa służy operator!
do określania, czy obiekt dokumentu jest już własnością, i tworzy nowe wystąpienie tylko wtedy, gdy obiekt jest nieprawidłowy.
// comptr_op_not.cpp
// compile with: /clr /link msxml2.lib
#include <msxml2.h>
#include <msclr\com\ptr.h>
#import <msxml3.dll> raw_interfaces_only
using namespace System;
using namespace System::Runtime::InteropServices;
using namespace msclr;
// a ref class that uses a com::ptr to contain an
// IXMLDOMDocument object
ref class XmlDocument {
public:
void CreateInstance(String^ progid) {
if (!m_ptrDoc) {
m_ptrDoc.CreateInstance(progid);
if (m_ptrDoc) {
Console::WriteLine("DOM Document created.");
}
}
}
// note that the destructor will call the com::ptr destructor
// and automatically release the reference to the COM object
private:
com::ptr<IXMLDOMDocument> m_ptrDoc;
};
// use the ref class to handle an XML DOM Document object
int main() {
try {
XmlDocument doc;
// create the instance from a progid string
doc.CreateInstance("Msxml2.DOMDocument.3.0");
}
catch (Exception^ e) {
Console::WriteLine(e);
}
}
DOM Document created.