Microsoft Visual C++  
 

The SocketTools controls can be used in Visual C++ in several ways, depending on the type of program being developed and the way in which the control will be utilized. Although much of the complexity of COM can be hidden through the use of wrapper classes and smart pointers, development using COM objects is still more complex than simply using the MFC classes with which most Windows developers are familiar.

One of the first things that a C++ developer will encounter when programming with the control is that all of the methods use a data type called a variant. Most developers aren't familiar with what a variant is or how it should be used unless they have experience with COM programming, so this is a frequent point of confusion. The simplest definition is that a variant is a structure which contains type information and a union of intrinsic data types such as characters, integers and so on. The variant essentially serves as a generic data type, and the function being called has the responsibility of using or converting that data as necessary. In addition to the VARIANT structure itself, there are several classes which encapsulate variants, such as _variant_t, COleVariant and CComVariant. These classes make it easier for C++ programmers to use variants, and for the most part allows them to be used just as if the variant was an intrinsic type.

Another data type that may be unfamiliar is the BSTR, which is used for string data. Similar to C strings, the BSTR is a pointer to a null terminated array of characters which make up a string. However, there are some significant differences between the two. First, a BSTR always uses the Unicode character set, even if the program itself does not use Unicode. That means that each character in the BSTR is actually 16 bits, so special care must be taken to not assume that a character in the string is equivalent to a single byte. Second, although BSTR strings are null terminated, they may actually contain embedded nulls. This is because the BSTR also has information about the length of the string, so standard string functions (even the Unicode versions of them) should not be used if there is a chance that the string contains embedded nulls. Part of the Automation API is a collection of functions which manage BSTR strings, such as SysAllocString and SysStringLen. However, most programmers prefer to use one of the classes which encapsulate BSTRs, such as _bstr_t and CComBSTR.

In addition to the COM data types, another aspect of using COM objects is that most COM related functions return HRESULT values. The HRESULT is a 32-bit unsigned integer which contains status information about an error or warning returned by a function. Two macros which are commonly used are FAILED and SUCCEEDED which are used to determine whether or not the HRESULT value indicates that the function failed or was successful. All COM object methods and property accessor functions return HRESULT values which must be checked by the caller to ensure that the function was called correctly.