Connector/ODBC 5 commit: r97 - MYODBCIns/include

[pharvey]

Modified:
   MYODBCIns/include/MYODBCIns.h
Log:


Modified: MYODBCIns/include/MYODBCIns.h
===================================================================
--- MYODBCIns/include/MYODBCIns.h	2006-04-21 23:54:34 UTC (rev 96)
+++ MYODBCIns/include/MYODBCIns.h	2006-04-22 00:31:57 UTC (rev 97)
@@ -50,8 +50,8 @@
 public:
 
     /*!
-        \internal
         \brief      Delimiter type used for an attribute string.
+        \note       See internal doc for pit-falls of using DELIM_BOTH
     
     */  
     typedef enum tDELIM
@@ -63,7 +63,6 @@
     } DELIM;
 
     /*!
-        \internal
         \brief      Parse state.
     
                     These are the different states we can be in while parsing 
@@ -79,17 +78,100 @@
     
     } PARSE_STATE;
 
+    /*!
+        \brief  Posts an installer error.
+
+                Posts an installer error such that it can be returned later, along with
+                any other errors posted, using getError().
+
+                This uses SQLPostInstallerError().
+    */
     static bool setError( const QString &stringMessage, DWORD nErrorCode =
ODBC_ERROR_GENERAL_ERR );
 
+    /*! 
+        \brief  Gets a list of registered drivers.
+
+                The 'friendly' driver names are returned.
+
+                This uses SQLGetInstalledDrivers().
+    */
     static QStringList getDriverNames();
+
+    /*!
+        \brief  Gets a list of data source names (DSN's).
+
+                The results can be restricted in scope using nScope.
+
+                This uses SQLDataSources().
+    */
     static QStringList getDataSourceNames( MYODBCInsDataSource::DATASOURCE_SCOPE nScope
);
+
+    /*!
+        \brief  Gets the default location for driver and setup libraries.
+
+                This uses SQLInstallDriverEx() with ODBC_INSTALL_INQUIRY.
+    */
     static QString getDefaultInstallLocation();
+
+    /*!
+        \brief  Parses a keyword/value string - placing results in phashKeywordValues.
+
+                Keyword/value strings are used in several places in ODBC and each use
+                has its own special rules. Most notably; some use a ';' to delimit
+                each key/value pair while others use '\0'.
+
+                This method will parse the keyword/value string using the specified 
+                nDelim and does only the validation that is common to all uses.
+
+                This method is mostly for use by other MYODBCIns classes.
+
+        \param  phashKeywordValues This is where the results will go. It is assumed to
+                be empty at start and will have 0 or more entries if the parse succeeds.
+        \param  stringKeywordValues This is the keyword/value string.
+        \param  nDelim This is the delimiter used in stringKeywordValues. Using
DELIM_BOTH
+                has limitations and should be avoided where ever possible.
+        \return bool
+        \retval true The parse succeeded
+        \retval false The parse failed. The reason can be found using getError().
+    */
     static bool MYODBCIns::getKeywordValues( QHash<QString,QString>
*phashKeywordValues, const QString &stringKeywordValues, DELIM nDelim = DELIM_BOTH );
+
+    /*!
+        \brief  Get the error stored at location nError.
+
+                This uses SQLInstallerError().
+    */
     static RETCODE getError( WORD nError, DWORD *pnErrorCode, QString &stringMessage
);
+
+    /*!
+        \brief  Get the error stored at location nError.
+    */
     static QString getError( WORD nError );
+
+    /*!
+        \brief  Get all/any installer errors.
+    */
     static QStringList getErrors();
 
+    /*!
+        \brief  Registers a driver.
+
+                This registers a driver in the ODBC system information such that it
+                can be used but - it does not copy any files. The files should be
+                copied to the default location (\sa getDefaultInstallLocation())
+                before the driver is registered.
+
+                The usage count is incremented during this process.
+
+                This uses SQLInstallDriverEx().
+    */
     static bool doRegisterDriver( const QString &stringName, const QString
&stringAttributes, DWORD *pnUsageCount = NULL );
+
+    /*!
+        \brief  Deregisters a driver.
+
+                This deregisters
+    */
     static bool doDeregisterDriver( const QString &stringName, bool bRemoveDSNs =
false, DWORD *pnUsageCount = NULL );
     static bool doInsertDataSource( const QString &stringName, const QString
&stringAttributes, MYODBCInsDataSource::DATASOURCE_SCOPE nScope );
     static bool doUpdateDataSource( const QString &stringName, const QString
&stringAttributes, MYODBCInsDataSource::DATASOURCE_SCOPE nScope );