IConnection Class Reference

This class exposes an interface to interact with the customer DSII for connection details. More...

Inherits Simba::DSI::IWarningSource.

Inherited by DSIConnection.

List of all members.

Public Types

typedef DSIConnPropertyKey PropertyKeyType
 Typedef for a common name for the Enum for property keys in DSI interface classes.

Public Member Functions

virtual void BeginTransaction ()=0
 Begins a transaction.
virtual void ClearCancel ()=0
 Clear any previous cancel notification requested by the application.
virtual void ClonePropertyMap (DSIConnPropertyKeyValueMap &io_propertyMap)=0
 Retrieves a clone of the property map for the connection.
virtual void Commit ()=0
 This method commits all transactions within this connection.
virtual void Connect (const DSIConnSettingRequestMap &in_connectionSettings)=0
 Attempts to connect to the data source, using connection settings generated by a call to UpdateConnectionSettings().
virtual Simba::DSI::IStatementCreateStatement ()=0
 Creates and returns a new IStatement instance.
virtual void Disconnect ()=0
 Disconnect the connection.
virtual const
ConnectionSettingInfoMap
GetConnectionSettingInfo ()=0
 Gets information about connection settings that are accepted by the UpdateConnectionSettings and Connect functions.
virtual AttributeDataGetCustomProperty (simba_int32 in_key)=0
 Retrieves a custom property value.
virtual AttributeType GetCustomPropertyType (simba_int32 in_key)=0
 Retrieves the type associated with the custom property with the given ODBC attribute key.
virtual const simba_wstringGetDataSourceName ()=0
 Retrieves the name of the data source.
virtual const simba_string & GetLocale ()=0
 Retrieves the connection-wide locale.
virtual ILoggerGetLog ()=0
 Gets the ILogger for the connection.
virtual SharedPtr< IMessageSourceGetMessageSource ()=0
 Retrieves the message source.
virtual const
Simba::DSI::IMetadataFilterFactory
GetMetadataFilterFactory ()=0
 Gets the IMetadataFilterFactory to create filters.
virtual Simba::DSI::IEnvironmentGetParentEnvironment ()=0
 Gets the parent environment for this connection.
virtual const AttributeDataGetProperty (Simba::DSI::DSIConnPropertyKey in_key)=0
 Returns a connection property corresponding to the in_key.
virtual SqlCDataPoolGetSqlCDataPool ()=0
 Gets the SqlCDataTypeUtilities for this connection.
virtual SqlCDataTypeUtilitiesGetSqlCDataTypeUtilities ()=0
 Creates a SqlCDataTypeUtilities.
virtual SqlConverterFactoryGetSqlConverterFactory ()=0
 Creates a SqlConverterFactory.
virtual SqlCTypeMetadataFactoryGetSqlCTypeMetadataFactory ()=0
 Creates a SqlCTypeMetadataFactory.
virtual SqlDataFactoryGetSqlDataFactory ()=0
 Creates a SqlDataFactory.
virtual SqlDataTypeUtilitiesGetSqlDataTypeUtilities ()=0
 Creates a SqlDataTypeUtilities.
virtual const
ISqlToCBulkConverterFactory
GetSqlToCBulkConverterFactory ()=0
 Returns a reference to this connection's SQL -> C bulk converter factory.
virtual SqlTypeMetadataFactoryGetSqlTypeMetadataFactory ()=0
 Creates a SqlTypeMetadataFactory.
virtual TypeConversionInfoGetTypeConversionInfo ()=0
 Gets the TypeConversionInfo for this connection.
virtual bool IsCustomProperty (simba_int32 in_key)=0
 Determine if the property associated with the key is custom.
virtual bool IsSensitiveAttribute (const simba_wstring &in_attribute)=0
 Determine if a connection attribute is sensitive to Log.
virtual void OnCancel ()=0
 Notify that a cancel of the current operation was requested by the application.
virtual bool PromptDialog (DSIConnSettingResponseMap &io_connResponseMap, DSIConnSettingRequestMap &io_connectionSettings, HWND in_parentWindow, PromptType in_promptType)=0
 Displays a dialog box that prompts the user for settings for this connection.
virtual void RegisterTransactionStateListener (Simba::DSI::ITransactionStateListener *in_transactionStateListener)=0
 Registers an ITransactionStateListener* with this connection.
virtual void RegisterWarningListener (IWarningListener *in_warningListener)=0
 Registers an IWarningListener* with this connection.
virtual void Reset ()=0
 Reset this connection to a clean state (w.r.t. connection properties).
virtual void Rollback ()=0
 Roll back all transactions within this connection.
virtual void SetAppDialogInfo (bool in_isAllowed, SQLHWND in_windowHandle=0)=0
 Indicate if the driver may display a dialog during connection based on what is defined by the application.
virtual void SetCustomProperty (simba_int32 in_key, AttributeData *in_value)=0
 Sets the custom connection property with the given ODBC attribute key to the given value.
virtual void SetProperty (Simba::DSI::DSIConnPropertyKey in_key, AttributeData *in_value)=0
 Sets the connection property with the given key to the given value.
virtual void ToNativeSQL (const simba_wstring &in_string, simba_wstring &out_string)=0
 Takes in an ODBC-formatted SQL query and returns it customized and optimized for the data source.
virtual void UpdateConnectionSettings (const DSIConnSettingRequestMap &in_connectionSettings, DSIConnSettingResponseMap &out_connectionSettings)=0
 Updates the connection settings by checking if required settings are present.
virtual ~IConnection ()
 Destructor.

Protected Member Functions

 IConnection ()
 Constructor.

Detailed Description

This class exposes an interface to interact with the customer DSII for connection details.


Member Typedef Documentation

Typedef for a common name for the Enum for property keys in DSI interface classes.


Constructor & Destructor Documentation

virtual ~IConnection (  )  [inline, virtual]

Destructor.

IConnection (  )  [inline, protected]

Constructor.


Member Function Documentation

virtual void BeginTransaction (  )  [pure virtual]

Begins a transaction.

Implemented in DSIConnection.

virtual void ClearCancel (  )  [pure virtual]

Clear any previous cancel notification requested by the application.

The SimbaLib calls this function at the beginning of each cancelable function. It allows the DSI to clear any pending cancel notification and avoid that the next operation is immediately canceled if the last cancel notification was too late to be processed.

Implemented in DSIConnection.

virtual void ClonePropertyMap ( DSIConnPropertyKeyValueMap io_propertyMap  )  [pure virtual]

Retrieves a clone of the property map for the connection.

Parameters:
io_propertyMap Property map to clone all properties into. Any properties already in the map will be deleted. (OWN)

Implemented in DSIConnection.

virtual void Commit (  )  [pure virtual]

This method commits all transactions within this connection.

Implemented in DSIConnection.

virtual void Connect ( const DSIConnSettingRequestMap in_connectionSettings  )  [pure virtual]

Attempts to connect to the data source, using connection settings generated by a call to UpdateConnectionSettings().

A call to Connect() occurs when the ODBC connection is formed, not when the connection handle is allocated. If a Disconnect() call occurs, Connect() may be called again if a new connection is made against the same handle.

Parameters:
in_connectionSettings Connection settings generated by a call to UpdateConnectionSettings()
Exceptions:
ErrorException if there is a problem making a connection.
ErrorException with key DIAG_INVALID_AUTH_SPEC if there is a problem with authorization.

Implemented in DSIConnection.

virtual Simba::DSI::IStatement* CreateStatement (  )  [pure virtual]

Creates and returns a new IStatement instance.

Returns:
New IStatement instance. (OWN)

Implemented in DSIConnection.

virtual void Disconnect (  )  [pure virtual]

Disconnect the connection.

This method is called during SQLDisconnect and is not equivalent to closing the handle. The connection can be re-used by a call to SetConnectionSettings().

This call is a request to the DSII layer to free up all memory that it has allocated for the database, and to close any tables that are currently open for the database.

Implemented in DSIConnection.

virtual const ConnectionSettingInfoMap& GetConnectionSettingInfo (  )  [pure virtual]

Gets information about connection settings that are accepted by the UpdateConnectionSettings and Connect functions.

This is currently only used by OLEDB providers.

How the map keys are interpreted is dependent on if this is an ODBC or OLEDB connection.

In OLEDB Mode, the following values are used to map initialization properties to connection settings:

OLEDB ID | OLEDB Description | Variant Type --------------------------|-----------------------------|------------------------------ DBPROP_AUTH_USERID | User ID | WString DBPROP_AUTH_PASSWORD | Password | WString DBPROP_AUTH_INTEGRATED | Integrated Security | WString DBPROP_INIT_DATASOURCE | Data Source | WString DBPROP_INIT_LOCATION | Location | WString DBPROP_INIT_CATALOG | Initial Catalog | WString DBPRPO_INIT_LCID | Locale Identifier | WString (See Note)

Notes on specific properties: DBPROP_AUTH_INTEGRATED

  • This property is a WString which OLEDB describes as being the name of the security service to use.
  • Many windows applications will pass a value of "SSPI" to this property.
  • A value of "" means to use integrated security with the default service.
  • In many applications, when a user selects this option, the application will disable entry fields for USERID and PASSWORD and will not pass values for them. If you would like to receive those values along with a similar one for integrated security, you must not use this and should define a custom ID.

DBPROP_INIT_CATALOG

  • If you don't describe this property, or describe an empty key, it will still be supported if your DSII supports Catalogs. It will instead be passed to IConnection::SetProperty(DSI_CONN_CURRENT_CATALOG) before connecting.
  • If you describe a non-empty key for this in your info map, DBPROP_INIT_CATALOG will be passed to your UpdateConnectionSettings and Connect functions.

DBPROP_INIT_LCID

  • This property always maps to key "LOCALE"
  • It defaults to optional but may be reported as required.
  • The type WString is what will be passed to the connection settings map, however, OLEDB defines this as an int32 locale identifier. We look up this identifier value and pass its string representation.

Other properties (initialization or otherwise) are not mapped.

Custom properties may be present but must not conflict with existing property IDs and only be used within the range 0x80000000 to 0xFFFFFFFF.

In ODBC Mode, the map keys currently have no defined relationship with the setting info.

The DSII must remain prepared to deal with entries in the DSIConnSettingRequestMap passed to UpdateConnectionSettings or Connect that were not described by this function.

Returns:
Reference to map to filled in with settings accepted.

Implemented in DSIConnection.

virtual AttributeData* GetCustomProperty ( simba_int32  in_key  )  [pure virtual]

Retrieves a custom property value.

Parameters:
in_key ODBC attribute key.
Returns:
Custom property value. (NOT OWN)

Implemented in DSIConnection.

virtual AttributeType GetCustomPropertyType ( simba_int32  in_key  )  [pure virtual]

Retrieves the type associated with the custom property with the given ODBC attribute key.

Must throw an ErrorException if the given key does not correspond to a custom property. A value does not have to be available for this property in order to be able to retrieve the corresponding type.

Parameters:
in_key ODBC attribute key.
Returns:
Type associated with the custom property.

Implemented in DSIConnection.

virtual const simba_wstring& GetDataSourceName (  )  [pure virtual]

Retrieves the name of the data source.

The data source name is set by setting the "DSN" connection key to a valid value.

Returns:
Data source name.

Implemented in DSIConnection.

virtual const simba_string& GetLocale (  )  [pure virtual]

Retrieves the connection-wide locale.

The locale is set by setting the "LOCALE" connection key to a valid value. See LocaleDefns.h for possible values.

Returns:
The connection-wide locale.

Implemented in DSIConnection.

virtual ILogger* GetLog (  )  [pure virtual]

Gets the ILogger for the connection.

Returns:
ILogger instance. (NOT OWN)

Implemented in DSIConnection.

virtual SharedPtr<IMessageSource> GetMessageSource (  )  [pure virtual]

Retrieves the message source.

Returns:
Message source.

Implements IWarningSource.

Implemented in DSIConnection.

virtual const Simba::DSI::IMetadataFilterFactory& GetMetadataFilterFactory (  )  [pure virtual]

Gets the IMetadataFilterFactory to create filters.

Returns:
MetadataFilterFactory

Implemented in DSIConnection.

virtual Simba::DSI::IEnvironment* GetParentEnvironment (  )  [pure virtual]

Gets the parent environment for this connection.

Returns:
The parent environment instance. (NOT OWN)

Implemented in DSIConnection.

virtual const AttributeData* GetProperty ( Simba::DSI::DSIConnPropertyKey  in_key  )  [pure virtual]

Returns a connection property corresponding to the in_key.

Please refer to the DSI Design and Implementation Guide for detailed information on the supported properties.

Parameters:
in_key Connection property key supported by DSI.
Returns:
The connection property corresponding to the in_key. (NOT OWN)

Implemented in DSIConnection.

virtual SqlCDataPool& GetSqlCDataPool (  )  [pure virtual]

Gets the SqlCDataTypeUtilities for this connection.

Override this function if you have implemented your own subclass of SqlCDataTypeUtilities. Return your subclass of SqlCDataTypeUtilities.

Returns:
A SqlCDataTypeUtilities.

Implemented in DSIConnection.

virtual SqlCDataTypeUtilities& GetSqlCDataTypeUtilities (  )  [pure virtual]

Creates a SqlCDataTypeUtilities.

Override this function if you have implemented your own subclass of SqlCDataTypeUtilities. Return your subclass of SqlCDataTypeUtilities.

Returns:
A SqlCDataTypeUtilities.

Implemented in DSIConnection.

virtual SqlConverterFactory& GetSqlConverterFactory (  )  [pure virtual]

Creates a SqlConverterFactory.

Override this function if you have implemented your own subclass of SqlConverterFactory. Return your subclass of SqlConverterFactory.

Returns:
A SqlConverterFactory.

Implemented in DSIConnection.

virtual SqlCTypeMetadataFactory& GetSqlCTypeMetadataFactory (  )  [pure virtual]

Creates a SqlCTypeMetadataFactory.

Override this function if you have implemented your own subclass of SqlCTypeMetadataFactory. Return your subclass of SqlCTypeMetadataFactory.

Returns:
A SqlCTypeMetadataFactory.

Implemented in DSIConnection.

virtual SqlDataFactory& GetSqlDataFactory (  )  [pure virtual]

Creates a SqlDataFactory.

Override this function if you have implemented your own subclass of SqlDataFactory. Return your subclass of SqlDataFactory.

Returns:
A SqlDataFactory.

Implemented in DSIConnection.

virtual SqlDataTypeUtilities& GetSqlDataTypeUtilities (  )  [pure virtual]

Creates a SqlDataTypeUtilities.

Override this function if you have implemented your own subclass of SqlDataTypeUtilities. Return your subclass of SqlDataTypeUtilities.

Returns:
A SqlDataTypeUtilities.

Implemented in DSIConnection.

virtual const ISqlToCBulkConverterFactory& GetSqlToCBulkConverterFactory (  )  [pure virtual]

Returns a reference to this connection's SQL -> C bulk converter factory.

Returns:
A reference to this connection's SQL -> C bulk converter factory.
Exceptions:
If Bulk-Fetch is not supported on this connection.

Implemented in DSIConnection.

virtual SqlTypeMetadataFactory& GetSqlTypeMetadataFactory (  )  [pure virtual]

Creates a SqlTypeMetadataFactory.

Override this function if you have implemented your own subclass of SqlTypeMetadataFactory. Return your subclass of SqlTypeMetadataFactory.

Returns:
A SqlTypeMetadataFactory.

Implemented in DSIConnection.

virtual TypeConversionInfo& GetTypeConversionInfo (  )  [pure virtual]

Gets the TypeConversionInfo for this connection.

Override this function if you have implemented your own subclass of SqlCTypeMetadataFactory. Return your subclass of SqlCTypeMetadataFactory.

Returns:
A TypeConversionInfo

Implemented in DSIConnection.

virtual bool IsCustomProperty ( simba_int32  in_key  )  [pure virtual]

Determine if the property associated with the key is custom.

Returns:
True if in_key is associated with a custom connection property recognized by the DSII; false otherwise.

Implemented in DSIConnection.

virtual bool IsSensitiveAttribute ( const simba_wstring in_attribute  )  [pure virtual]

Determine if a connection attribute is sensitive to Log.

Parameters:
in_attribute Connection attribute to Log.
Returns:
True if in_attribute should not be logged in plain text recognized by the DSII; default value is false.

Implemented in DSIConnection.

virtual void OnCancel (  )  [pure virtual]

Notify that a cancel of the current operation was requested by the application.

The SimbaLib calls this function when the SQLCancelHandle ODBC function is called on a connection handle corresponding to this connection object. The objective for the DSII is then to set flags or any other mean to notify the operation that it was canceled.

Implemented in DSIConnection.

virtual bool PromptDialog ( DSIConnSettingResponseMap io_connResponseMap,
DSIConnSettingRequestMap io_connectionSettings,
HWND  in_parentWindow,
PromptType  in_promptType 
) [pure virtual]

Displays a dialog box that prompts the user for settings for this connection.

The connection settings from io_connectionSettings are presented as key-value string pairs. The input connection settings map is the initial state of the dialog box. The input connection settings map will be modified to reflect the user's input to the dialog box. All the key-value pairs returned in io_connectionSettings will be put into the output connection string (when the called connection function was either SQLDriverConnect or SQLBrowseConnect)

io_connResponseMap contains values that are still needed and were not supplied by the user. This map is returned from DSII layer of the driver when UpdateConnectionSettings function of an IConnection object is called. The driver may use this map, for example, to indicate that some setting is missing or optional.

The return value for this method indicates if the user completed the process by clicking OK on the dialog box (return true), or if the user aborts the process by clicking CANCEL on the dialog box (return false).

The function will be called multiple times if the user clicked OK button but the setting user input are incomplete. Before each time the function is called, UpdateConnectionSettings function mentioned above will be called to check whether there are still required settings not being set, and the response map will be updated accordingly to reflect such information.

Parameters:
io_connResponseMap The connection settings map updated with settings that are still needed and were not supplied.
io_connectionSettings The connection settings map updated to reflect the user's input.
in_parentWindow Handle to the parent window to which this dialog belongs
in_promptType Indicates what type of connection settings to request - either both required and optional settings or just required settings.
Returns:
True if the user clicks OK on the dialog box; false if the user clicks CANCEL.

Implemented in DSIConnection.

virtual void RegisterTransactionStateListener ( Simba::DSI::ITransactionStateListener in_transactionStateListener  )  [pure virtual]

Registers an ITransactionStateListener* with this connection.

Will be called right after construction of the IConnection.

Parameters:
in_transactionStateListener A listener which may be used to transaction state changes. (NOT OWN)

Implemented in DSIConnection.

virtual void RegisterWarningListener ( IWarningListener in_warningListener  )  [pure virtual]

Registers an IWarningListener* with this connection.

Will be called right after construction of the IConnection.

Parameters:
in_warningListener A listener which may be used to post warnings. (NOT OWN)

Implements IWarningSource.

Implemented in DSIConnection.

virtual void Reset (  )  [pure virtual]

Reset this connection to a clean state (w.r.t. connection properties).

Reset this connection's connection properties to their default state. If the connection was currently connected, it stays that way.

Implemented in DSIConnection.

virtual void Rollback (  )  [pure virtual]

Roll back all transactions within this connection.

Implemented in DSIConnection.

virtual void SetAppDialogInfo ( bool  in_isAllowed,
SQLHWND  in_windowHandle = 0 
) [pure virtual]

Indicate if the driver may display a dialog during connection based on what is defined by the application.

A dialog can for example be useful if a driver would like to request a refresh of the password in case the one provided in the connection string has expired.

Allowing the opening of a dialog depends on the application API (e.g. in ODBC a dialog can be opened only if the DriverCompletion parameter of SQLDriverConnect() is different from SQL_DRIVER_NOPROMPT).

Parameters:
in_isAllowed true if opening a dialog is allowed, else false.
in_windowHandle The handle of the parent window in which to open a dialog or 0 if the parent window is unknown.

Implemented in DSIConnection.

virtual void SetCustomProperty ( simba_int32  in_key,
AttributeData in_value 
) [pure virtual]

Sets the custom connection property with the given ODBC attribute key to the given value.

If the value is modified before saving it, an OPT_VAL_CHANGED warning should be posted. This method should post an OPT_VAL_CHANGE warning if a value is substituted with another value before storage (like substituting a timeout value for the maximum if it's too high). For properties which accept more than just a discrete set of values, this method should throw an INVALID_ATTR_VAL error if an illegal value is given which can't be substituted with another value.

Parameters:
in_key ODBC attribute key.
in_value The value to be set. (OWN)

Implemented in DSIConnection.

virtual void SetProperty ( Simba::DSI::DSIConnPropertyKey  in_key,
AttributeData in_value 
) [pure virtual]

Sets the connection property with the given key to the given value.

If the value is modified before saving it, an OPT_VAL_CHANGED warning should be posted. Please refer to the DSI Design and Implementation Guide for detailed information on the supported properties.

This method should post an OPT_VAL_CHANGE warning if a value is substituted with another value before storage (like substituting a timeout value for the maximum if it's too high). For properties which accept more than just a discrete set of values, this method should throw an INVALID_ATTR_VAL error if an illegal value is given which can't be substituted with another value.

Parameters:
in_key Connection property key supported by DSI.
in_value Connection property value to be set for in_key. (OWN)
Exceptions:
InvalidCatalogException if in_key is DSI_CONN_CURRENT_CATALOG and in_value is an invalid catalog.

Implemented in DSIConnection.

virtual void ToNativeSQL ( const simba_wstring in_string,
simba_wstring out_string 
) [pure virtual]

Takes in an ODBC-formatted SQL query and returns it customized and optimized for the data source.

Parameters:
in_string ODBC-formatted SQL query.
out_string Gets filled in with return value.

Implemented in DSIConnection.

virtual void UpdateConnectionSettings ( const DSIConnSettingRequestMap in_connectionSettings,
DSIConnSettingResponseMap out_connectionSettings 
) [pure virtual]

Updates the connection settings by checking if required settings are present.

When connecting to a data source, SimbaLib calls this function to check and update settings for the connection. The in_connectionSettings parameter includes the settings specified in the connection string presented as key-value string pairs. This method should return any modified and additional requested connection settings in out_connectionSettings.

If any connection settings have been modified, then an OPT_VAL_CHANGED warning must be posted. If a key in the map is unrecognized or does not belong in this stage of connection, then an INVALID_CONN_STR_ATTR warning must be posted in this method.

Parameters:
in_connectionSettings The Connection Settings map containing the connection settings that were passed into the connection string.
out_connectionSettings Gets filled in with connection settings that are still needed and were not supplied in the connection string.

Implemented in DSIConnection.


The documentation for this class was generated from the following file:

Generated on Wed May 17 14:21:15 2017 for SimbaEngine 10.1.3.1011 by simba