Introduction

COM (Common Object Model)

COM is a Microsoft Technology that allows reusing pieces of software. COM can be used to control a program from another program. COM can be used from C, C++, C# and Visual Basic. Two programs written in different languages can communicate each other using COM.
COM es una tecnología de Microsoft que permite reusar piezas de software. COM puede ser usado para controlar un programa desde otro programa. COM puede ser usado desde C, C++, C# y Visual Basic. Dos programas escritos en distintos lenguajes pueden comunicarte entre ellos usando COM.

Tip
COM allows the quick integration of features offered by other software. It reduces software implementation time by re-using pieces of software. One of the main problems when using COM is that sometimes the user does not have the software that we would like to use through COM; in other cases it may happen that the version of the software is different.
El uso de COM permite la integración rápida de capacidades ofrecidas por otro software. Reduce el tiempo de implementación del software al re-usar piezas de software. Uno de los problemas de usar COM es que a veces el usuario no tiene instalado el software que se quiere accesar vía COM; en otros casos pudiera ocurrir que las versiones del software pueden ser diferentes.

ActiveX

An ActiveX is a Windows control that uses the COM technology. An ActiveX control can be re-used in other applications. It is usually a file with the extension *.ocx. An Applet is the Java version of an ActiveX. The Flash Player that shows animations in a web page is an ActiveX created by Adobe.
Un ActiveX es un control de Windows que usa la tecnología COM. Un control ActiveX puede ser re-usado en otras aplicaciones. Es usualmente un archivo con la extensión *.ocx. Un Applet es la versión en Java de un ActiveX. El Flash Player que muestra animaciones en una página web es un ActiveX creado por la compañía Adobe.

_variant_t

COM uses the _variant_t data type to declare any variable as shown in the figure below. A _variant_t variable can store: integer values, double values, strings, etc. In some cases, this is a problem because the programmer does not know in advance the data type of a variable and the program may crash during execution. As using VARIANT variables is difficult, there is a class called _variant_t that simplifies the manipulation of VARIANT variables.
COM usa el tipo de datos _variant_t para declarar cualquier variable como se muestra en la figura de abajo. Una variable del tipo _variant_t puede almacenar: valores enteros, valores de punto flotante, texto, etc. En algunos casos, esto es un problema porque el programador no sabe el tipo de datos de una variable y el programa puede generar errores durante la ejecución. Como usar variables VARIANT es difícil, hay una clase llamada _variant_t que simplifica la manipulación de las variables VARIANT.

variant

VARIANT

The code below shows the implementation of the VARIANT struct. The first member of the struct, vt, can take the values of VT_I8 (for integer values of eight bytes), VT_I4 (for integer values of four bytes), etc.
El código de abajo muestra la implementación de la estructura VARIANT. El primer miembro de la estructura vt puede tomar los valores de VT_I8 (para enteros de ocho bytes), VT_I4 (para enteros de cuatro bytes), etc.

OAldl.h
/* VARIANT STRUCTURE
*
* VARTYPE vt;
* WORD wReserved1;
* WORD wReserved2;
* WORD wReserved3;
* union {
* LONGLONG VT_I8
* LONG VT_I4
* BYTE VT_UI1
* SHORT VT_I2
* FLOAT VT_R4
* DOUBLE VT_R8
* VARIANT_BOOL VT_BOOL
* SCODE VT_ERROR
* CY VT_CY
* DATE VT_DATE
* BSTR VT_BSTR
* IUnknown * VT_UNKNOWN
* IDispatch * VT_DISPATCH
* SAFEARRAY * VT_ARRAY
* BYTE * VT_BYREF|VT_UI1
* SHORT * VT_BYREF|VT_I2
* LONG * VT_BYREF|VT_I4
* LONGLONG * VT_BYREF|VT_I8
* FLOAT * VT_BYREF|VT_R4
* DOUBLE * VT_BYREF|VT_R8
* VARIANT_BOOL * VT_BYREF|VT_BOOL
* SCODE * VT_BYREF|VT_ERROR
* CY * VT_BYREF|VT_CY
* DATE * VT_BYREF|VT_DATE
* BSTR * VT_BYREF|VT_BSTR
* IUnknown ** VT_BYREF|VT_UNKNOWN
* IDispatch ** VT_BYREF|VT_DISPATCH
* SAFEARRAY ** VT_BYREF|VT_ARRAY
* VARIANT * VT_BYREF|VT_VARIANT
* PVOID VT_BYREF (Generic ByRef)
* CHAR VT_I1
* USHORT VT_UI2
* ULONG VT_UI4
* ULONGLONG VT_UI8
* INT VT_INT
* UINT VT_UINT
* DECIMAL * VT_BYREF|VT_DECIMAL
* CHAR * VT_BYREF|VT_I1
* USHORT * VT_BYREF|VT_UI2
* ULONG * VT_BYREF|VT_UI4
* ULONGLONG * VT_BYREF|VT_UI8
* INT * VT_BYREF|VT_INT
* UINT * VT_BYREF|VT_UINT
* }
*/
struct tagVARIANT
{
     union
     {
          struct __tagVARIANT
          {
               VARTYPE vt;
               WORD wReserved1;
               WORD wReserved2;
               WORD wReserved3;
               union
               {
                    LONGLONG llVal;
                    LONG lVal;
                    BYTE bVal;
                    SHORT iVal;
                    FLOAT fltVal;
                    DOUBLE dblVal;
                    VARIANT_BOOL boolVal;
                    _VARIANT_BOOL bool ;
                    SCODE scode;
                    CY cyVal;
                    DATE date;
                    BSTR bstrVal;
                    IUnknown *punkVal;
                    IDispatch *pdispVal;
                    SAFEARRAY *parray;
                    BYTE *pbVal;
                    SHORT *piVal;
                    LONG *plVal;
                    LONGLONG *pllVal;
                    FLOAT *pfltVal;
                    DOUBLE *pdblVal;
                    VARIANT_BOOL *pboolVal;
                    _VARIANT_BOOL *pbool;
                    SCODE *pscode;
                    CY *pcyVal;
                    DATE *pdate;
                    BSTR *pbstrVal;
                    IUnknown **ppunkVal;
                    IDispatch **ppdispVal;
                    SAFEARRAY **pparray;
                    VARIANT *pvarVal;
                    PVOID byref;
                    CHAR cVal;
                    USHORT uiVal;
                    ULONG ulVal;
                    ULONGLONG ullVal;
                    INT intVal;
                    UINT uintVal;
                    DECIMAL *pdecVal;
                    CHAR *pcVal;
                    USHORT *puiVal;
                    ULONG *pulVal;
                    ULONGLONG *pullVal;
                    INT *pintVal;
                    UINT *puintVal;
                    struct __tagBRECORD
                    {
                         PVOID pvRecord;
                         IRecordInfo *pRecInfo;
                    }      __VARIANT_NAME_4;
               }      __VARIANT_NAME_3;
          }      __VARIANT_NAME_2;
          DECIMAL decVal;
     }      __VARIANT_NAME_1;
};
typedef VARIANT *LPVARIANT;


Tip
The code show below declares an integer value using VARIANT.
El código de abajo declara un valor entero usando VARIANT.

Program.cpp
VARIANT age;
age.vt = VT_I8;
age.llVal = 25;


Missing parameter

Some COM functions require several parameters making very difficult to call these functions. However, in some cases, it is possible to pass the value vtMissing when a precise value is not known.
Algunas funciones COM requieren varios parámetros haciendo difícil llamar estas funciones. Sin embargo, en algunos casos, es posible pasar el valor vtMissing cuando el valor preciso no es conocido.

VARIANT_BOOL

A VARIANT_BOOL variable is typically used in COM and can store only two values: VARIANT_TRUE and VARIANT_FALSE.
Una variable VARIANT_BOOL es usada típicamente en COM y puede almacenar solamente dos valores: VARIANT_TRUE y VARIANT_FALSE.

_bstr_t

COM uses BSTR (basic strings) to manipulate text. The C++ compiler provides the _bstr_t class to simplify the manipulation of text in COM. The example below shows how to use the _bstr_t class to retrieve the full name of a document.
COM usa BSTR (basic strings) para manipular texto. El compilador de C++ proporciona la clase _bstr_t para simplificar la manipulación de texto en COM. El ejemplo de abajo muestra cómo usar la clase _bstr_t para retraer el nombre completo de un documento.

Program.cpp
_bstr_t fullname;
HRESULT hr = Document->get_FullName(&fullname.GetBSTR());


Smart Pointers

COM uses pointers to manipulate objects. The C++ compiler provides smart pointer (_COM_SMARTPTR_TYPEDEF) to simplify the manipulation of pointers in COM. After, we will show how to use them. The code shown below illustrates how the smart pointer for the IUnknown interface is defined in the comdfsp.h file or Unknwnbase.h; in a program this smart pointer is declared as IUnknownPtr. To use smart pointer you must include , Wintempla includes this file automatically.
COM usa punteros para manipular objetos. El compilador de C++ proporciona los punteros inteligentes (_COM_SMARTPTR_TYPEDEF) para simplificar los punteros en COM. Después, se mostrará cómo usarlos. El código de abajo ilustra como el puntero inteligente para la interface IUnknown es definido en el archivo comdfsp.h o Unknwnbase.h; en el programa este puntero inteligente se declara como IUnknownPtr. Para usar los punteros inteligentes usted debe incluir , Wintempla incluye este archivo automáticamente.

comdfsp.h
_COM_SMARTPTR_TYPEDEF(IUnknown, __uuidof(IUnknown));


ATL

The Activate Template Library is a Technology made by Microsoft that can be used to simplify COM. ATL is bases on class templates. ATL provides other tools to simplify: VARIANT (CComVariant), BSTR (CComBSTR) and pointers (CComPtr, CComQIPtr).
La Librería de Plantillas Activa es una tecnología hecha por Microsoft que puede ser usada para simplificar COM. ATL proporciona otras herramientas para simplificar: VARIANT (CComVariant), BSTR (CComBSTR) y los punteros (CComPtr, CComQIPtr).

HRESULT

HRESULT is a numeric value that is used to know if a COM operation was successful. All COM functions return a HRESULT value. There are many values that an HRESULT variable can take. When everything is OK, the value is S_OK. The macros FAILED(hr) and SUCCEEDED(hr) are used to know the meaning of an HRESULT value.
HRESULT es un valor numérico que se usa para saber si una operación en COM es exitosa. Todas las funciones de COM regresan un valor del tipo HRESULT. Hay muchos valores que una variable del tipo HRESULT puede tomar. Cuando todo está bien, el valor es S_OK. Los macros FAILED(hr) and SUCCEEDED(hr) son usados para saber el significado de un valor del tipo HRESULT.

HR_FAIL

Wintempla defines the HR_FAIL macro to check the HRESULT returned from a COM function. The macro automatically generates debug information that will help you find a correct a bug in your program.
Wintempla define el macro HR_FAIL para verificar el HRESULT que regresa una función COM. El macro automáticamente genera información de depuración que le ayudará a encontrar y corregir un error en su programa.

Program.cpp
wstring errorDescription; // member variable

if (HR_FAIL(::CoCreateInstance(...), errorDescription))
{
      return errorDescription;
}


Tip
Before performing any COM operation, the COM library must be initialized as shown below. In the same way, you must notify the COM library that you do not want to perform more COM operations. You may put these functions at the beginning and at the end of a function, or in the constructor and in the destructor of a class as shown below.
Antes de realizar cualquier operación COM, la librería COM debe ser inicializada como se muestra debajo. En la misma forma, usted debe notificar a la librería COM cuando usted ya no quiere realizar más operaciones COM. Usted puede colocar estas funciones al principio y al final de una función, o en el constructor y en el destructor de una clase como se muestra debajo.

MyClass.cpp
MyClass::MyClass()
{
     ::CoInitialize(NULL);
}

MyClass::~MyClass()
{
     ::CoUninitialize();
}


Indexes in COM

An array index in C++ starts in zero, however, an index in COM starts in one.
Un índice de un arreglo en C++ comienza en cero, sin embargo, un índice en COM comienza en uno.

© Copyright 2000-2021 Wintempla selo. All Rights Reserved. Jul 22 2021. Home