Manage Administrative Functions

Helper Group classes provide common functionality, such as dialog boxes and thread creation and termination.

Manage Administrative Functions

Class Description
CDLogonDlg

The Connect:Direct® common logon dialog box enables you to write your own logon applications. The CDLogon dialog box enables you to change the node, the user ID and password to connect to the Connect:Direct node as well as enable the Remember Password check box, click the Configure button to save new server logon information and change the title.

Below are the components of the CDLogonDlg class:

Node—Specifies the Connect:Direct node to which the user wants to logon.

userid—Specifies the user ID for the Connect:Direct node.

Password—Specifies the password defined for the user ID.

Remember Password—Specifies whether the user wants the password to persist after the user logs off. If the check box is enabled, the password is retrieved to set the password field of the dialog box when the logon dialog is displayed. This prevents the user from having to re-type the password information for the session. Enabling the check box also specifies whether or not to write the password information as nonvolatile data. Nonvolatile keys persist after the user logs off. If the user does not enable the Remember Password check box, the password only persists until the user logs off.

The Connect:Direct Logon dialog box does not perform the logon. It captures the entries and returns them to the calling program.

Normally, the programmer creates a CDLogon dialog box, sets the parameters, and calls the DoModal() function to display and run the dialog box. If the user clicks the OK button, then the CDLogonDlg class returns IDOK and a logon is attempted using the supplied connection information. If the user clicks the Cancel button, the CDLogonDlg class returns IDCANCEL and the logon is cancelled.

After a user successfully logs on to the Connect:Direct node, the connection information is written to the Registry under the HKEY_CURRENT_USER key.

CDExceptionDlg Displays the exception dialog box. The dialog box displays the information in the exception object
CDThread Coordinates the clean termination of threads and provides a thread class that can unblock object
CDBeginThread Creates a worker thread for use with API objects.
Return Values A pointer to the newly created thread object.

Create A Thread Example

The following example illustrates how to create a thread:

 void SomeFunc() 
 { 
     CDThread* pThread = CDBeginThread(ThreadFunc); 
 } void ThreadFunc(LPARAM lParam) 
 { 
     CSomeCmd cmd(...); 
     CDProcess proc = cmd.Execute(...); 
     DWORD dwId = proc.GetId(); 
     SetDlgItemInt(IDC_SOMECONTROL, (int)dwId); 
 }

Terminate A Thread

In the preceding sample code, the only blocking that takes place is in the Execute() function. Execute() blocks until the Process information returns from the server. To terminate the thread without waiting, call CDThread::Exit, which signals any blocking CD objects in the thread to stop blocking and throw a thread exit exception. In the previous example, if CDThread::Exit is called, an exception is thrown, and no return object is returned from the Execute() function.
Note: It is not possible for one thread to throw an exception in another. CDThread::Exit sets flags in the CDThread object that other CD objects use.

When CDThread::Exit is called, CDThread::IsExiting returns TRUE. You can use this method in loops to determine when to exit because CD objects only throw the exception when they are blocking.

CAUTION:
Do not call the Win32 TerminateThread. TerminateThread does not give the thread a chance to shut down gracefully. Calling TerminateThread can corrupt the state of the CD objects. CD objects use critical sections and other resources that must be managed carefully.

Catch the Exception

It is not necessary to catch the CDThreadDeath exception. If not caught, the exception unwinds the stack, destroying all objects on the stack, and the CDThread object itself handles the exception. To provide clean-up for heap allocated items, the exception can be caught. Rethrowing the exception is not required.