com::ptr-Klasse

2023-10-12

Ein Wrapper für ein COM-Objekt, das als Mitglied einer CLR-Klasse verwendet werden kann. Der Wrapper automatisiert auch die Lebensdauerverwaltung des COM-Objekts, wobei alle eigenen Verweise auf das Objekt freigegeben werden, wenn der Destruktor aufgerufen wird. Analog zur CComPtr-Klasse.

Syntax

template<class _interface_type>
ref class ptr;

Parameter

_interface_type
COM-Schnittstelle.

Hinweise

Eine com::ptr kann auch als lokale Funktionsvariable verwendet werden, um verschiedene COM-Aufgaben zu vereinfachen und die Lebensdauerverwaltung zu automatisieren.

A com::ptr kann nicht direkt als Funktionsparameter verwendet werden. Verwenden Sie stattdessen einen Tracking-Verweisoperator oder einen Handle to Object Operator (^ ).

Eine com::ptr Funktion kann nicht direkt zurückgegeben werden. Verwenden Sie stattdessen ein Handle.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Das Aufrufen der öffentlichen Methoden der Klasse führt zu Aufrufen des enthaltenen IXMLDOMDocument Objekts. Das Beispiel erstellt eine Instanz eines XML-Dokuments, füllt es mit einem einfachen XML-Code und führt eine vereinfachte Exemplarik der Knoten in der analysierten Dokumentstruktur aus, um den XML-Code in der Konsole zu drucken.

// 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>

Member

Öffentliche Konstruktoren

Name	Beschreibung
ptr::ptr	Erstellt ein `com::ptr` COM-Objekt, um ein COM-Objekt umzuschließen.
ptr::~ptr	Destruktiert ein `com::ptr`.

Öffentliche Methoden

Name	Beschreibung
ptr::Attach	Fügt ein COM-Objekt an ein `com::ptr`.
ptr::CreateInstance	Erstellt eine Instanz eines COM-Objekts in einem `com::ptr`.
ptr::Detach	Gibt den Besitz des COM-Objekts auf und gibt einen Zeiger auf das Objekt zurück.
ptr::GetInterface	Erstellt eine Instanz eines COM-Objekts in einem `com::ptr`.
ptr::QueryInterface	Fragt das eigene COM-Objekt für eine Schnittstelle ab und fügt das Ergebnis an eine andere `com::ptr`an.
ptr::Release	Veröffentlicht alle eigenen Verweise auf das COM-Objekt.

Öffentliche Operatoren

Name	Beschreibung
`ptr::operator->`	Memberzugriffsoperator, der zum Aufrufen von Methoden für das eigene COM-Objekt verwendet wird.
ptr::operator=	Fügt ein COM-Objekt an ein `com::ptr`.
ptr::operator bool	Operator für die Verwendung `com::ptr` in einem bedingten Ausdruck.
ptr::operator!	Operator, um festzustellen, ob das eigene COM-Objekt ungültig ist.

Anforderungen

Headerdatei<msclr\com\ptr.h>

Namespace msclr::com

ptr::ptr

Gibt einen Zeiger auf das eigene COM-Objekt zurück.

ptr();
ptr(
   _interface_type * p
);

Parameter

P
Ein COM-Schnittstellenzeiger.

Hinweise

Der No-Argument-Konstruktor weist nullptr dem zugrunde liegenden Objekthandle zu. Zukünftige Aufrufe des com::ptr internen Objekts werden überprüft und im Hintergrund fehlschlagen, bis ein Objekt erstellt oder angefügt wird.

Der Konstruktor mit einem Argument fügt einen Verweis auf das COM-Objekt hinzu, gibt jedoch den Verweis des Aufrufers nicht frei, sodass der Aufrufer das COM-Objekt aufrufen Release muss, um die Kontrolle wirklich aufzugeben. Wenn der com::ptrDestruktor aufgerufen wird, wird er automatisch seine Verweise auf das COM-Objekt freigeben.

Das Übergeben NULL an diesen Konstruktor entspricht dem Aufrufen der No-Argument-Version.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Es veranschaulicht die Verwendung beider Versionen des Konstruktors.

// 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

Destruktiert ein com::ptr.

~ptr();

Hinweise

Bei der Zerstörung gibt die com::ptr Veröffentlichung alle Verweise, die es besitzt, auf sein COM-Objekt. Wenn es keine anderen Verweise auf das COM-Objekt gibt, wird das COM-Objekt gelöscht und sein Speicher freigegeben.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. In der main Funktion werden die Destruktoren der beiden XmlDocument Objekte aufgerufen, wenn sie aus dem Bereich des try Blocks gehen, wodurch der zugrunde liegende com::ptr Destruktor aufgerufen wird und alle eigenen Verweise auf das COM-Objekt freigegeben werden.

// 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

Fügt ein COM-Objekt an ein com::ptr.

void Attach(
   _interface_type * _right
);

Parameter

_Rechts
Der anzufügende COM-Schnittstellenzeiger.

Ausnahmen

Wenn der com::ptr bereits besitzer eines Verweises auf ein COM-Objekt ist, Attach wird ausgelöst InvalidOperationException.

Hinweise

Ein Aufruf, der Attach auf das COM-Objekt verweist, aber den Verweis des Aufrufers auf das Objekt nicht freigibt.

Übergeben NULL an Attach Ergebnisse, in der keine Aktion ausgeführt wird.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die ReplaceDocument Memberfunktion ruft zuerst alle zuvor im Besitz befindlichen Objekte auf Release und ruft dann auf Attach , um ein neues Dokumentobjekt anzufügen.

// 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

Erstellt eine Instanz eines COM-Objekts in einem 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
);

Parameter

progid
Eine ProgID-Zeichenfolge.

Kropftaube
Zeiger auf die IUnknown-Schnittstelle des Aggregatobjekts (das steuernde IUnknown). Wenn pouter nicht angegeben, NULL wird verwendet.

cls_context
Kontext, in dem der Code, der das neu erstellte Objekt verwaltet, ausgeführt wird. Die Werte werden aus der CLSCTX Enumeration entnommen. Wenn cls_context nicht angegeben, wird der Wert CLSCTX_ALL verwendet.

rclsid
CLSID den Daten und Code zugeordnet, die zum Erstellen des Objekts verwendet werden.

Ausnahmen

Wenn der com::ptr bereits besitzer eines Verweises auf ein COM-Objekt ist, CreateInstance wird ausgelöst InvalidOperationException.

Diese Funktion ruft CoCreateInstance alle Fehler HRESULT in eine entsprechende Ausnahme auf und konvertiert ThrowExceptionForHR diesen.

Hinweise

CreateInstance verwendet CoCreateInstance , um eine neue Instanz des angegebenen Objekts zu erstellen, die entweder von einer ProgID oder einer CLSID identifiziert wird. Die com::ptr Verweise auf das neu erstellte Objekt und werden automatisch alle eigenen Verweise auf die Zerstörung freigeben.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die Klassenkonstruktoren verwenden zwei verschiedene Formen, CreateInstance um das Dokumentobjekt entweder aus einer ProgID oder aus einer CLSID sowie einem CLSCTX zu erstellen.

// 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

Gibt den Besitz des COM-Objekts auf und gibt einen Zeiger auf das Objekt zurück.

_interface_type * Detach();

Rückgabewert

Der Zeiger auf das COM-Objekt.

Wenn kein Objekt gehört, wird NULL zurückgegeben.

Ausnahmen

QueryInterface Intern wird für das eigene COM-Objekt aufgerufen, und jeder Fehler HRESULT wird in eine Ausnahme konvertiert.ThrowExceptionForHR

Hinweise

Detach fügt zuerst einen Verweis auf das COM-Objekt im Namen des Aufrufers hinzu und gibt dann alle Verweise frei, die im Besitz der com::ptr. Der Aufrufer muss das zurückgegebene Objekt letztendlich freigeben, um es zu zerstören.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die DetachDocument Memberfunktion ruft auf Detach , um den Besitz des COM-Objekts aufzugeben und einen Zeiger auf den Aufrufer zurückzugeben.

// 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

Gibt einen Zeiger auf das eigene COM-Objekt zurück.

_interface_type * GetInterface();

Rückgabewert

Ein Zeiger auf das eigene COM-Objekt.

Ausnahmen

QueryInterface Intern wird für das eigene COM-Objekt aufgerufen, und jeder Fehler HRESULT wird in eine Ausnahme konvertiert.ThrowExceptionForHR

Hinweise

Das com::ptr Addieren eines Verweises auf das COM-Objekt im Namen des Aufrufers und behält auch einen eigenen Verweis auf das COM-Objekt bei. Der Aufrufer muss letztendlich den Verweis für das zurückgegebene Objekt freigeben, oder er wird nie zerstört.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die GetDocument Memberfunktion verwendet GetInterface , um einen Zeiger auf das COM-Objekt zurückzugeben.

// 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

Fragt das eigene COM-Objekt für eine Schnittstelle ab und fügt das Ergebnis an eine andere com::ptran.

template<class _other_type>
void QueryInterface(
   ptr<_other_type> % other
);

Parameter

sonstige
Die com::ptr Schnittstelle wird abgerufen.

Ausnahmen

QueryInterface Intern wird für das eigene COM-Objekt aufgerufen, und jeder Fehler HRESULT wird in eine Ausnahme konvertiert.ThrowExceptionForHR

Hinweise

Verwenden Sie diese Methode, um einen COM-Wrapper für eine andere Schnittstelle des COM-Objekts zu erstellen, das dem aktuellen Wrapper gehört. Diese Methode ruft QueryInterface das im Besitz befindliche COM-Objekt auf, um einen Zeiger auf eine bestimmte Schnittstelle des COM-Objekts com::ptranzufordern und fügt den zurückgegebenen Schnittstellenzeiger an die übergebene Schnittstelle an.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die WriteTopLevelNode Memberfunktion verwendet QueryInterface , um ein lokales com::ptr Element mit einer IXMLDOMNode zu füllen, und übergibt dann die com::ptr (nachverfolgungsverweis) an eine private Memberfunktion, die den Namen und die Texteigenschaften des Knotens in die Konsole schreibt.

// 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

Veröffentlicht alle eigenen Verweise auf das COM-Objekt.

void Release();

Hinweise

Durch Aufrufen dieser Funktion werden alle eigenen Verweise auf das COM-Objekt freigegeben und der interne Handle auf das COM-Objekt nullptrfestgelegt. Wenn keine anderen Verweise auf das COM-Objekt vorhanden sind, wird sie zerstört.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die ReplaceDocument Memberfunktion verwendet Release , um alle vorherigen Dokumentobjekte freizugeben, bevor das neue Dokument angefügt wird.

// 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->`

Memberzugriffsoperator, der zum Aufrufen von Methoden für das eigene COM-Objekt verwendet wird.

_detail::smart_com_ptr<_interface_type> operator->();

Rückgabewert

A smart_com_ptr für das COM-Objekt.

Ausnahmen

QueryInterface Intern wird für das eigene COM-Objekt aufgerufen, und jeder Fehler HRESULT wird in eine Ausnahme konvertiert.ThrowExceptionForHR

Hinweise

Mit diesem Operator können Sie Methoden des eigenen COM-Objekts aufrufen. Sie gibt einen temporären smart_com_ptr Wert zurück, der automatisch eigene AddRef und Release.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die WriteDocument Funktion verwendet operator-> , um das get_firstChild Element des Dokumentobjekts aufzurufen.

// 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=

Fügt ein COM-Objekt an ein com::ptr.

ptr<_interface_type> % operator=(
   _interface_type * _right
);

Parameter

_Rechts
Der anzufügende COM-Schnittstellenzeiger.

Rückgabewert

Ein Nachverfolgungsverweis auf der com::ptr.

Ausnahmen

Wenn der com::ptr bereits besitzer eines Verweises auf ein COM-Objekt ist, operator= wird ausgelöst InvalidOperationException.

Hinweise

Zuweisen eines COM-Objekts zu einem com::ptr Verweis auf das COM-Objekt, gibt jedoch nicht den Verweis des Aufrufers darauf frei.

Dieser Operator hat dieselbe Wirkung wie Attach.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die ReplaceDocument Memberfunktion ruft zuerst alle zuvor im Besitz befindlichen Objekte auf Release und verwendet operator= dann zum Anfügen eines neuen Dokumentobjekts.

// 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 bool

Operator für die Verwendung com::ptr in einem bedingten Ausdruck.

operator bool();

Rückgabewert

true wenn das eigene COM-Objekt gültig ist; false sonst.

Hinweise

Das eigene COM-Objekt ist gültig, wenn es nicht nullptrder Ist.

Dieser Operator konvertiert, was _detail_class::_safe_bool sicherer ist, als bool weil er nicht in einen integralen Typ konvertiert werden kann.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die CreateInstance Memberfunktion verwendet operator bool nach dem Erstellen des neuen Dokumentobjekts, um festzustellen, ob es gültig ist und ob es in die Konsole geschrieben wird.

// 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, um festzustellen, ob das eigene COM-Objekt ungültig ist.

bool operator!();

Rückgabewert

true wenn das eigene COM-Objekt ungültig ist; false sonst.

Hinweise

Das eigene COM-Objekt ist gültig, wenn es nicht nullptrder Ist.

Beispiel

This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Die CreateInstance Memberfunktion bestimmt, operator! ob bereits ein Dokumentobjekt gehört, und erstellt nur eine neue Instanz, wenn das Objekt ungültig ist.

// 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.

Freigeben über

com::ptr-Klasse

Syntax

Parameter

Hinweise

Beispiel

Member

Öffentliche Konstruktoren

Öffentliche Methoden

Öffentliche Operatoren

Anforderungen

ptr::ptr

Parameter

Hinweise

Beispiel

ptr::~ptr

Hinweise

Beispiel

ptr::Attach

Parameter

Ausnahmen

Hinweise

Beispiel

ptr::CreateInstance

Parameter

Ausnahmen

Hinweise

Beispiel

ptr::Detach

Rückgabewert

Ausnahmen

Hinweise

Beispiel

ptr::GetInterface

Rückgabewert

Ausnahmen

Hinweise

Beispiel

ptr::QueryInterface

Parameter

Ausnahmen

Hinweise

Beispiel

ptr::Release

Hinweise

Beispiel

ptr::operator->

Rückgabewert

Ausnahmen

Hinweise

Beispiel

ptr::operator=

Parameter

Rückgabewert

Ausnahmen

Hinweise

Beispiel

ptr::operator bool

Rückgabewert

Hinweise

Beispiel

ptr::operator!

Rückgabewert

Hinweise

Beispiel

Feedback

Zusätzliche Ressourcen

`ptr::operator->`