com::ptr (Clase)com::ptr Class

Contenedor de un objeto COM que se puede utilizar como miembro de una clase de CLR.A wrapper for a COM object that can be used as a member of a CLR class. El contenedor también automatiza la administración de la duración del objeto COM, liberando todas las referencias de propiedad en el objeto cuando se llama a su destructor.The wrapper also automates lifetime management of the COM object, releasing all owned references on the object when its destructor is called. Análogo a la Clase CComPtr.Analogous to CComPtr class.

SintaxisSyntax

template<class _interface_type>
ref class ptr;

ParámetrosParameters

_interface_type_interface_type
Interfaz COM.COM interface.

ObservacionesRemarks

com::ptrTambién se puede usar como una variable de función local para simplificar varias tareas com y automatizar la administración de la duración.A com::ptr can also be used as a local function variable to simplify various COM tasks and to automate lifetime management.

com::ptrNo se puede usar directamente como parámetro de función; en su lugar, use un operador de referencia de seguimiento o un identificador para el operador de objeto (^) .A com::ptr can't be used directly as a function parameter; use a Tracking reference operator or a Handle to object operator (^) instead.

com::ptrNo se puede devolver directamente desde una función; use un identificador en su lugar.A com::ptr can't be directly returned from a function; use a handle instead.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Llamar a los métodos públicos de la clase produce llamadas al objeto contenido IXMLDOMDocument .Calling the public methods of the class results in calls to the contained IXMLDOMDocument object. En el ejemplo se crea una instancia de un documento XML, se llena con algún XML simple y se realiza un recorrido simplificado de los nodos del árbol del documento analizado para imprimir el XML en la consola.The sample creates an instance of an XML document, fills it with some simple XML, and does a simplified walk of the nodes in the parsed document tree to print the XML to the console.

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

MiembrosMembers

Constructores públicosPublic constructors

NombreName DescripciónDescription
ptr::ptrptr::ptr Construye un com::ptr para encapsular un objeto com.Constructs a com::ptr to wrap a COM object.
PTR:: ~ PTRptr::~ptr Destruye un com::ptr .Destructs a com::ptr.

Métodos públicosPublic methods

NombreName DescripciónDescription
ptr::Attachptr::Attach Adjunta un objeto COM a un objeto com::ptr .Attaches a COM object to a com::ptr.
ptr::CreateInstanceptr::CreateInstance Crea una instancia de un objeto COM dentro de una com::ptr .Creates an instance of a COM object within a com::ptr.
ptr::Detachptr::Detach Proporciona la propiedad del objeto COM y devuelve un puntero al objeto.Gives up ownership of the COM object, returning a pointer to the object.
ptr::GetInterfaceptr::GetInterface Crea una instancia de un objeto COM dentro de una com::ptr .Creates an instance of a COM object within a com::ptr.
ptr::QueryInterfaceptr::QueryInterface Consulta el objeto COM de propiedad de una interfaz y asocia el resultado a otro com::ptr .Queries the owned COM object for an interface and attaches the result to another com::ptr.
ptr::Releaseptr::Release Libera todas las referencias propiedad del objeto COM.Releases all owned references on the COM object.

Operadores públicosPublic operators

NombreName DescripciónDescription
PTR:: Operator->ptr::operator-> Operador de acceso a miembros, que se usa para llamar a métodos en el objeto COM de propiedad.Member access operator, used to call methods on the owned COM object.
PTR:: Operator =ptr::operator= Adjunta un objeto COM a un objeto com::ptr .Attaches a COM object to a com::ptr.
PTR:: Operator   boolptr::operator bool Operador para usar com::ptr en una expresión condicional.Operator for using com::ptr in a conditional expression.
ptr::operator!ptr::operator! Para determinar si el objeto COM de propiedad no es válido.Operator to determine if the owned COM object is invalid.

RequisitosRequirements

Archivo de encabezado <msclr\com\ptr.h>Header file <msclr\com\ptr.h>

Espacio de nombres msclr:: comNamespace msclr::com

PTR::p TRptr::ptr

Devuelve un puntero al objeto COM de propiedad.Returns a pointer to the owned COM object.

ptr();
ptr(
   _interface_type * p
);

ParámetrosParameters

PP
Puntero a interfaz COM.A COM interface pointer.

ObservacionesRemarks

El constructor sin argumentos nullptr se asigna al identificador de objeto subyacente.The no-argument constructor assigns nullptr to the underlying object handle. Las llamadas futuras a com::ptr validarán el objeto interno y producirán un error de forma silenciosa hasta que se cree o adjunte un objeto.Future calls to the com::ptr will validate the internal object and silently fail until an object is created or attached.

El constructor de un argumento agrega una referencia al objeto COM, pero no libera la referencia del llamador, por lo que el llamador debe llamar a Release en el objeto com para ofrecer realmente el control.The one-argument constructor adds a reference to the COM object but doesn't release the caller's reference, so the caller must call Release on the COM object to truly give up control. Cuando com::ptr se llama al destructor de, se liberarán automáticamente sus referencias en el objeto com.When the com::ptr's destructor is called it will automatically release its references on the COM object.

Pasar NULL a este constructor es igual que llamar a la versión sin argumentos.Passing NULL to this constructor is the same as calling the no-argument version.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Muestra el uso de ambas versiones del constructor.It demonstrates usage of both versions of the constructor.

// 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:: ~ PTRptr::~ptr

Destruye un com::ptr .Destructs a com::ptr.

~ptr();

ObservacionesRemarks

En la destrucción, el com::ptr libera todas las referencias que posee a su objeto com.On destruction, the com::ptr releases all references it owns to its COM object. Suponiendo que no hay otras referencias retenidas al objeto COM, se eliminará el objeto COM y se liberará su memoria.Assuming that there are no other references held to the COM object, the COM object will be deleted and its memory freed.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. En la main función, XmlDocument se llamará a los destructores de los dos objetos cuando salen del ámbito del try bloque, lo que da lugar a que se com::ptr llame al destructor subyacente, liberando todas las referencias de propiedad al objeto com.In the main function, the two XmlDocument objects' destructors will be called when they go out of the scope of the try block, resulting in the underlying com::ptr destructor being called, releasing all owned references to the COM object.

// 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:: Attachptr::Attach

Adjunta un objeto COM a un objeto com::ptr .Attaches a COM object to a com::ptr.

void Attach(
   _interface_type * _right
);

ParámetrosParameters

_right_right
Puntero de interfaz COM que se va a adjuntar.The COM interface pointer to attach.

ExcepcionesExceptions

Si com::ptr ya posee una referencia a un objeto com, Attach produce una excepción InvalidOperationException .If the com::ptr already owns a reference to a COM object, Attach throws InvalidOperationException.

ObservacionesRemarks

Una llamada a Attach hace referencia al objeto com, pero no libera la referencia del llamador a él.A call to Attach references the COM object but doesn't release the caller's reference to it.

NULLAl pasar a, Attach no se realiza ninguna acción.Passing NULL to Attach results in no action being taken.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. La ReplaceDocument función miembro llama primero a Release en cualquier objeto de propiedad anterior y, a continuación, llama Attach a para asociar un nuevo objeto de documento.The ReplaceDocument member function first calls Release on any previously owned object and then calls Attach to attach a new document object.

// 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:: CreateInstanceptr::CreateInstance

Crea una instancia de un objeto COM dentro de una com::ptr .Creates an instance of a COM object within a 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
);

ParámetrosParameters

Programaprogid
Cadena de ProgID.A ProgID string.

pouterpouter
Puntero a la interfaz IUnknown del objeto agregado (control IUnknown).Pointer to the aggregate object's IUnknown interface (the controlling IUnknown). Si pouter no se especifica, NULL se utiliza.If pouter isn't specified, NULL is used.

cls_contextcls_context
Contexto en el que se ejecutará el código que administra el objeto recién creado.Context in which the code that manages the newly created object will run. Los valores se toman de la CLSCTX enumeración.The values are taken from the CLSCTX enumeration. Si cls_context no se especifica, se utiliza el valor CLSCTX_ALL.If cls_context isn't specified, the value CLSCTX_ALL is used.

rclsidrclsid
CLSIDasociado a los datos y el código que se utilizarán para crear el objeto.CLSID associated with the data and code that will be used to create the object.

ExcepcionesExceptions

Si com::ptr ya posee una referencia a un objeto com, CreateInstance produce una excepción InvalidOperationException .If the com::ptr already owns a reference to a COM object, CreateInstance throws InvalidOperationException.

Esta función llama a CoCreateInstance y usa ThrowExceptionForHR para convertir cualquier error HRESULT en una excepción adecuada.This function calls CoCreateInstance and uses ThrowExceptionForHR to convert any error HRESULT to an appropriate exception.

ObservacionesRemarks

CreateInstanceutiliza CoCreateInstance para crear una nueva instancia del objeto especificado, identificada desde un ProgID o un CLSID.CreateInstance uses CoCreateInstance to create a new instance of the specified object, identified either from a ProgID or a CLSID. com::ptrHace referencia al objeto recién creado y libera automáticamente todas las referencias de propiedad en la destrucción.The com::ptr references the newly created object and will automatically release all owned references upon destruction.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. Los constructores de clase usan dos formas diferentes de CreateInstance para crear el objeto de documento desde un ProgID o desde un CLSID más un CLSCTX.The class constructors use two different forms of CreateInstance to create the document object either from a ProgID or from a CLSID plus a 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::D Etachptr::Detach

Proporciona la propiedad del objeto COM y devuelve un puntero al objeto.Gives up ownership of the COM object, returning a pointer to the object.

_interface_type * Detach();

Valor devueltoReturn value

Puntero al objeto COM.The pointer to the COM object.

Si no hay ningún objeto propiedad, se devuelve NULL.If no object is owned, NULL is returned.

ExcepcionesExceptions

Internamente, QueryInterface se llama a en el objeto com de propiedad y cualquier error HRESULT se convierte en una excepción mediante ThrowExceptionForHR .Internally, QueryInterface is called on the owned COM object and any error HRESULT is converted to an exception by ThrowExceptionForHR.

ObservacionesRemarks

Detachprimero agrega una referencia al objeto COM en nombre del llamador y, a continuación, libera todas las referencias que son propiedad de com::ptr .Detach first adds a reference to the COM object on behalf of the caller and then releases all references owned by the com::ptr. El llamador debe liberar en última instancia el objeto devuelto para destruirlo.The caller must ultimately release the returned object to destroy it.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. La DetachDocument función miembro llama Detach a para proporcionar la propiedad del objeto com y devolver un puntero al llamador.The DetachDocument member function calls Detach to give up ownership of the COM object and return a pointer to the caller.

// 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:: GetInterfaceptr::GetInterface

Devuelve un puntero al objeto COM de propiedad.Returns a pointer to the owned COM object.

_interface_type * GetInterface();

Valor devueltoReturn value

Puntero al objeto COM de propiedad.A pointer to the owned COM object.

ExcepcionesExceptions

Internamente, QueryInterface se llama a en el objeto com de propiedad y cualquier error HRESULT se convierte en una excepción mediante ThrowExceptionForHR .Internally, QueryInterface is called on the owned COM object and any error HRESULT is converted to an exception by ThrowExceptionForHR.

ObservacionesRemarks

com::ptrAgrega una referencia al objeto com en nombre del llamador y también mantiene su propia referencia en el objeto com.The com::ptr adds a reference to the COM object on the caller's behalf and also keeps its own reference on the COM object. En última instancia, el llamador debe liberar la referencia en el objeto devuelto o nunca se destruirá.The caller must ultimately release the reference on the returned object or it will never be destroyed.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. La GetDocument función miembro utiliza GetInterface para devolver un puntero al objeto com.The GetDocument member function uses GetInterface to return a pointer to the COM object.

// 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:: QueryInterfaceptr::QueryInterface

Consulta el objeto COM de propiedad de una interfaz y asocia el resultado a otro com::ptr .Queries the owned COM object for an interface and attaches the result to another com::ptr.

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

ParámetrosParameters

distintaother
com::ptrQue obtendrá la interfaz.The com::ptr that will get the interface.

ExcepcionesExceptions

Internamente, QueryInterface se llama a en el objeto com de propiedad y cualquier error HRESULT se convierte en una excepción mediante ThrowExceptionForHR .Internally, QueryInterface is called on the owned COM object and any error HRESULT is converted to an exception by ThrowExceptionForHR.

ObservacionesRemarks

Utilice este método para crear un contenedor COM para una interfaz diferente del objeto COM propiedad del contenedor actual.Use this method to create a COM wrapper for a different interface of the COM object owned by the current wrapper. Este método llama a QueryInterface través del objeto com de propiedad para solicitar un puntero a una interfaz específica del objeto com y asocia el puntero de interfaz devuelto a la pasada com::ptr .This method calls QueryInterface through the owned COM object to request a pointer to a specific interface of the COM object and attaches the returned interface pointer to the passed-in com::ptr.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. La WriteTopLevelNode función miembro utiliza QueryInterface para rellenar una variable local com::ptr con IXMLDOMNode y, a continuación, pasa com::ptr (por referencia de seguimiento) a una función miembro privada que escribe las propiedades de texto y el nombre del nodo en la consola.The WriteTopLevelNode member function uses QueryInterface to fill a local com::ptr with an IXMLDOMNode and then passes the com::ptr (by tracking reference) to a private member function that writes the node's name and text properties to the console.

// 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:: Releaseptr::Release

Libera todas las referencias propiedad del objeto COM.Releases all owned references on the COM object.

void Release();

ObservacionesRemarks

La llamada a esta función libera todas las referencias propiedad del objeto COM y establece el identificador interno del objeto COM en nullptr .Calling this function releases all owned references on the COM object and sets the internal handle to the COM object to nullptr. Si no existe ninguna otra referencia en el objeto COM, se destruirá.If no other references on the COM object exist, it will be destroyed.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. La ReplaceDocument función miembro utiliza Release para liberar cualquier objeto de documento anterior antes de adjuntar el nuevo documento.The ReplaceDocument member function uses Release to release any prior document object before attaching the new document.

// 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->ptr::operator->

Operador de acceso a miembros, que se usa para llamar a métodos en el objeto COM de propiedad.Member access operator, used to call methods on the owned COM object.

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

Valor devueltoReturn value

smart_com_ptrEn el objeto com.A smart_com_ptr to the COM object.

ExcepcionesExceptions

Internamente, QueryInterface se llama a en el objeto com de propiedad y cualquier error HRESULT se convierte en una excepción mediante ThrowExceptionForHR .Internally, QueryInterface is called on the owned COM object and any error HRESULT is converted to an exception by ThrowExceptionForHR.

ObservacionesRemarks

Este operador le permite llamar a métodos del objeto COM de propiedad.This operator allows you to call methods of the owned COM object. Devuelve un temporal smart_com_ptr que controla automáticamente sus propios AddRef y Release .It returns a temporary smart_com_ptr that automatically handles its own AddRef and Release.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. La WriteDocument función utiliza operator-> para llamar al get_firstChild miembro del objeto de documento.The WriteDocument function uses operator-> to call the get_firstChild member of the document object.

// 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 =ptr::operator=

Adjunta un objeto COM a un objeto com::ptr .Attaches a COM object to a com::ptr.

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

ParámetrosParameters

_right_right
Puntero de interfaz COM que se va a adjuntar.The COM interface pointer to attach.

Valor devueltoReturn value

Referencia de seguimiento en com::ptr .A tracking reference on the com::ptr.

ExcepcionesExceptions

Si com::ptr ya posee una referencia a un objeto com, operator= produce una excepción InvalidOperationException .If the com::ptr already owns a reference to a COM object, operator= throws InvalidOperationException.

ObservacionesRemarks

La asignación de un objeto COM a una com::ptr referencia al objeto com, pero no libera la referencia del llamador a él.Assigning a COM object to a com::ptr references the COM object but doesn't release the caller's reference to it.

Este operador tiene el mismo efecto que Attach .This operator has the same effect as Attach.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. La ReplaceDocument función miembro llama primero a Release en cualquier objeto de propiedad anterior y, a continuación, usa operator= para adjuntar un nuevo objeto de documento.The ReplaceDocument member function first calls Release on any previously owned object and then uses operator= to attach a new document object.

// 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 boolptr::operator bool

Operador para usar com::ptr en una expresión condicional.Operator for using com::ptr in a conditional expression.

operator bool();

Valor devueltoReturn value

true Si el objeto COM de propiedad es válido; false en caso contrario,.true if the owned COM object is valid; false otherwise.

ObservacionesRemarks

El objeto COM de propiedad es válido si no lo es nullptr .The owned COM object is valid if it's not nullptr.

Este operador convierte en _detail_class::_safe_bool que es más seguro que bool porque no se puede convertir en un tipo entero.This operator converts to _detail_class::_safe_bool which is safer than bool because it can't be converted to an integral type.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. La CreateInstance función miembro utiliza operator bool después de crear el nuevo objeto de documento para determinar si es válido y escribe en la consola si es.The CreateInstance member function uses operator bool after creating the new document object to determine if it's valid and writes to the console if it is.

// 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!ptr::operator!

Para determinar si el objeto COM de propiedad no es válido.Operator to determine if the owned COM object is invalid.

bool operator!();

Valor devueltoReturn value

true Si el objeto COM de propiedad no es válido; false en caso contrario,.true if the owned COM object is invalid; false otherwise.

ObservacionesRemarks

El objeto COM de propiedad es válido si no lo es nullptr .The owned COM object is valid if it's not nullptr.

EjemploExample

En este ejemplo se implementa una clase de CLR que utiliza com::ptr para contener su objeto de miembro privado IXMLDOMDocument .This example implements a CLR class that uses a com::ptr to wrap its private member IXMLDOMDocument object. La CreateInstance función miembro utiliza operator! para determinar si un objeto de documento ya es propiedad y solo crea una nueva instancia si el objeto no es válido.The CreateInstance member function uses operator! to determine if a document object is already owned, and only creates a new instance if the object is invalid.

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