Add support for warnings / notices

[CurtHagenlocher]

A number of databases can return warnings or notices from the evaluation of a submitted SQL statement. In JDBC, these are returned via a getWarnings API on Connections, Statements and ResultSets. libpq allows the application to set a callback function for a connection object by using PQsetNoticeReceiver. ADBC should support some kind of mechanism to allow an application to get the equivalent information -- either by using a JDBC-style pull or a libpq-style push. My feeling is that this is only needed on AdbcConnection and that a callback is preferable to having to do buffering, but this is based on personal experience and not an exhaustive survey of existing driver capabilities. Perhaps the following?

typedef AdbcStatusCode (*ConnectionNotice)(struct AdbcConnection*, struct AdbcError*);

ADBC_EXPORT AdbcStatusCode AdbcConnectionSetNoticeReceiver(
    struct AdbcConnection* connection,
    ConnectionNotice receiver,
    struct AdbcError* error);

ADBC_EXPORT AdbcStatusCode AdbcConnectionGetNoticeReceiver(
    struct AdbcConnection* connection,
    ConnectionNotice* receiver,
    struct AdbcError* error);

Error details could be available for a notice.

This functionality is implicitly referenced by #81.

[lidavidm]

For JDBC-style, we could easily define a new option for that today; a whole new API method would take more time.

What does ODBC do?

I agree it only needs to go on the connection

[CurtHagenlocher]

ODBC notifies you that these are available via the result code SQL_SUCCESS_WITH_INFO. The application then needs to call SqlGetDiagRec in order to get the information. Any API call is free to return SQL_SUCCESS_WITH_INFO, which I've found somewhat annoying in practice but could obviously work as well.

[lidavidm]

Hmm, I'd like to avoid that too 😬

I suppose the handler would be my preferred option, with the caveat that it'd be potentially annoying to support if the underlying database API is pull-based (have to use a background thread or poll at certain points), and that adding a new API method with our backwards compatibility approach is a bit annoying, so I'd like to roll it up with other new methods at the same time

[CurtHagenlocher]

I definitely don't think it's worth versioning the API just for this, but it is a need we'll have eventually (and one demonstrated by the existence of similar functionality in other APIs) so I thought it important to add now for tracking purposes.