Instantiating CWnd Based Controls

To create an instance of the control in an MFC application without using a dialog, add the control to the project using the same method described previously. However, instead of placing the control on a dialog using the resource editor, declare an instance of the class that will be using the control. Then, call the Create function to create an instance of the control for that class. For example:

CRect rcNull;
BSTR bstrLicKey;
BOOL bCreated;
USES_CONVERSION;

bstrLicKey = SysAllocString(T2OLE(CSTOOLS11_LICENSE_KEY));
bCreated = m_ctlFtpClient.Create(NULL,         // window name
                                 0,            // window style
                                 rcNull,       // window rect
                                 this,         // parent window
                                 IDC_CONTROL,  // control ID
                                 NULL,         // persistent storage
                                 FALSE,        // IStorage
                                 bstrLicKey);  // license key

if (bCreated == FALSE)
{
    AfxMessageBox(_T("Control creation failed"), MB_ICONEXCLAMATION);
    EndDialog(0);
}

Because the control is not part of the program's resources as in the previous example, an instance of the control must be explicitly created by calling the Create method. Because the File Transfer control is not visible at runtime, most of the window arguments are null. However, it is still required that a parent window be specified; in this case, the this pointer is used. If the class that is using the control is not derived from CWnd, a hidden window can be created and specified as the parent instead.

Another issue is that to create an instance of the control, the application must pass it a runtime license key. This is a BSTR string which is used by the control to determine if it can be used in an application. If this string is NULL, then the control will only load if the current system has a valid development license. If it is not NULL, then the license key is validated and an instance of the control is created. The license key for SocketTools is defined in the cstools11.h header file, found in the Include folder where the product was installed. Note that the key value will be NULL for evaluation versions of the control, which means that the application cannot be redistributed until a license has been purchased.

The SysAllocString function is used to create the license key BSTR and this requires that the license key be converted to Unicode. In afxpriv.h there are several string conversion macros that are useful for converting between ANSI and Unicode. One is OLE2T which converts a Unicode string to an LPTSTR, and the other is T2OLE which converts an LPTSTR to a Unicode string. The afxpriv.h header file is not usually included in MFC applications, so it will need to be added to StdAfx.h manually.

The USES_CONVERSION macro is required and must be included in the function prior to using any of the conversion macros. In this case, T2OLE is used to convert the ANSI license key string to Unicode, and then that is passed to SysAllocString to create a BSTR. It should be noted that OLE2T and T2OLE allocate memory from the stack to do the conversion, so they should not be used with very large amounts of data.