feat(format): add AdbcConnectionSetWarningHandler

Closes apache#1243.

Author: lidavidm

c/include/arrow-adbc/adbc.h

@@ -989,8 +989,6 @@ struct AdbcPartitions {
 
 /// @}
 
-/// @}
-
 /// \defgroup adbc-statement-multi Multiple Result Set Execution
 /// Some databases support executing a statement that returns multiple
 /// result sets.  This section defines the API for working with such
@@ -1092,6 +1090,18 @@ AdbcStatusCode AdbcMultiResultSetNextPartitions(struct AdbcMultiResultSet* resul
                                                 struct AdbcError* error);
 /// @}
 
+/// \brief A warning handler function.
+///
+/// The handler must not block and must not call any other ADBC functions
+/// (besides releasing the warning).  The warning does not need to be released
+/// before returning.
+///
+/// \param[in] warning The warning information.  The application is
+///   responsible for releasing the warning, but the warning pointer itself
+///   may not be valid after the handler returns.
+/// \param[in] user_data The user_data pointer.
+typedef void (*AdbcWarningHandler)(const struct AdbcError* warning, void* user_data);
+
 /// \defgroup adbc-driver Driver Initialization
 ///
 /// These functions are intended to help support integration between a
@@ -1264,6 +1274,11 @@ struct ADBC_EXPORT AdbcDriver {
                                                  struct AdbcPartitions*, int64_t*,
                                                  struct AdbcError*);
   AdbcStatusCode (*MultiResultSetRelease)(struct AdbcMultiResultSet*, struct AdbcError*);
+
+  AdbcStatusCode (*ConnectionSetWarningHandler)(struct AdbcConnection*,
+                                                AdbcWarningHandler handler,
+                                                void* user_data, struct AdbcError*);
+
   AdbcStatusCode (*StatementExecuteSchemaMulti)(struct AdbcStatement*,
                                                 struct AdbcMultiResultSet*,
                                                 struct AdbcError*);
@@ -1612,6 +1627,24 @@ ADBC_EXPORT
 AdbcStatusCode AdbcConnectionRelease(struct AdbcConnection* connection,
                                      struct AdbcError* error);
 
+/// \brief Set a warning handler.
+///
+/// May be set before or after AdbcConnectionInit.
+///
+/// \since ADBC API revision 1.2.0
+/// \param[in] database The database.
+/// \param[in] handler The warning handler to use; NULL removes the handler.
+/// \param[in] user_data A user data pointer to be passed to the handler.
+///   Must live at least until the connection is released or the warning
+///   handler is replaced.
+/// \param[out] error An optional location to return an error
+///   message if necessary.
+/// \return ADBC_STATUS_NOT_IMPLEMENTED if warning handlers are not supported
+ADBC_EXPORT
+AdbcStatusCode AdbcConnectionSetWarningHandler(struct AdbcConnection* connection,
+                                               AdbcWarningHandler handler,
+                                               void* user_data, struct AdbcError* error);
+
 /// \brief Cancel the in-progress operation on a connection.
 ///
 /// This can be called during AdbcConnectionGetObjects (or similar),