Establishing a Connection

As mentioned in a previous section, Connection Semantics, the FDO API uses a provider to connect to a data store and its underlying data source technology. These data source technologies must be installed and configured. Certain values generated during data source installation and configuration are used as arguments during the connection process. Because the FDO API does not provide any methods to automate the collection and presentation of these configuration values, either the application developer must request the user to input these configuration values during the connection process, or the application developer can provide an application configuration interface, which would populate the application with the container configuration values and thus allow the user to choose them from lists.

NoteFor more information about connecting, see The Essential FDO.

A connection can be made in either one or two steps:

One-step connection. If the user sets the required connection properties and calls the connection object’s Open() method once, the returned state is FdoConnectionState_Open, no additional information is needed.
Two-step connection. If the user sets the required connection properties and calls the connection object’s Open() method, the returned state is FdoConnectionState_Pending, additional information is needed to complete the connection. In this case, the first call to Open() has resulted in the retrieval of a list of values for a property that becomes a required property for the second call to the Open() method. After the user has selected one of the values in the list, the second call to Open() should result in FdoConnectionState_Open.

Connecting to a data store by way of the Oracle or the ArcSDE provider, for example, can be done in either one or two steps. In the first step, the data store parameter is not required. If the user does not give the data store parameter a value, the FDO will retrieve the list of data store values from the data source so that the user can choose from them during the second step. Otherwise the user can give the data store a value in the first step, and assuming that the value is valid, the connection will be completed in one step.

The following steps are preliminary to establishing a connection:

Get the display names for all of the providers in the registry.
Use the display names to create a menu list, which the user will select from when making a connection.

After the user initiates a connection attempt, do the following:

Loop through the providers in the registry until you match the display name selected by the user from the connection menu with a provider display name in the registry and retrieve the internal name for that provider.
Get an instance of the connection manager.
Call the manager’s CreateConnection() method using the provider internal name as an argument to obtain a connection object.
Obtain a connection info object by calling the connection object’s GetConnectionInfo() method.
Obtain a connection property dictionary object by calling the connection info object’s GetConnection Properties() method and use this dictionary to construct a dialog box requesting connection information from the user.
Get a list of connection property names by calling the dictionary’s GetPropertyNames() method and loop through the list constructing a data entry line in the dialog box for each name in the list.
Use the GetLocalizedName method to obtain the label for the data entry line in the dialog.
Use the IsPropertyRequired method to determine whether to mark the line as either required or optional; the dialog box handler should not permit the user to click OK in the dialog box unless a required field has a value.
Use the IsPropertyProtected method to determine whether the dialog box handler should process the field value as protected data.
Use the IsPropertyEnumerable method to determine whether to call the EnumeratePropertyValues method to get a list of valid values. Then,

If IsPropertyEnumerable returns True and EnumeratePropertyValues sets the updates count parameter to 0, then grey (make unavailable) this line in the dialog;

If the count is 1, set the line value to the value in the returned list;

If the count is greater than 1, then set up a spin box for this line containing the list of values and then call the GetProperty method;

If this method returns a value that is in the list, set the exposed spin-box value in the dialog box line to this value;

If this method returns the empty string, call the GetPropertyDefault method and if this returns a value that is in the list, and set the exposed spin-box value in the dialog box line to this value;

Otherwise, set the exposed spin-box value to some value in the returned list.

If the property is not enumerable, call the GetProperty method to determine whether you get a non-empty return value, set the value for that line in the dialog box to the return value.
If the property is not enumerable and does not yet have a value, call the GetPropertyDefault method and set the value for that line in the dialog box to the return value.
After processing each property in the dictionary, expose the dialog.
After the user has okayed the connection dialog box and the dialog box handler has determined that all of the required information has been filled in, the dialog box handler uses the dictionary’s SetProperty() method to update the dictionary with the values specified by the user.
Call the connection object’s Open() method and check the returned connection state value; if the value is FdoConnectionState_Pending, then reconstruct the connection dialog box and present it to the user for further input.
If the return value is FdoConnectionState_Open, the connection process is complete.