.. module:: firebird.driver.interfaces
    :synopsis: Interface wrappers for Firebird new API

==========================
firebird.driver.interfaces
==========================

This module contains interface wrappers for Firebird new API.

.. important::

   1. Firebird OO API interfaces use inheritance, i.e. they could be inherited from other
      interface. In fact, all interfaces returned by Firebird are inherited from `IVersioned`
      interface.

   2. Firebird OO API interfaces are versioned. Any addition to particular interface
      increases its version number. Application developers are responsible to check the
      version of returned interface to verify that it supports methods they want to use.

   If you want to use Firebird OO API interfaces directly in you application, read next
   section very carefuly.

In Python driver, interfaces are represented as instances of interface wrapper classes
that expose the methods provided by particular Firebird interface version. The wrapper
class hierarchy thus represent not only inheritabce between Firebird interfaces, but also
between versions of particular Firebird interface.

Because all interfaces returned by Firebird are inherited from `IVersioned` interface,
all wrapper classes have `VERSION` class attribute that contain version number of wrapped
interface.

Each Firebird interface has it's "canonical" Python wrapper with coresponding name. For
example interface `IService` has wrapper class `.iService`. However, if there are multiple
public versions of Firebird interface, there are multiple wrapper classes for each published
interface version (interim, non-public versions used during Firebird development are skipped).
These wrapper classes have names based on their canonical name with suffix that represent
the interface version they wrap. It means that canonical wrapper **always** represents
the highest interface version.

Whenever Firebird interface is returned from Firebird OO API call, it's wrapped to its
Python wrapper class according to interface type and version. The Python driver ensures
that correct wrapper class is used according to returned interface version.

However, this architecture has several important consequences:

1. The interface wrapper classes may change between driver releases as new interface versions
   are introduced. For example, driver versions up to 1.5.2 had only canonical `.iService`
   (version 3), but in version 1.6.0 it was renamed to `.iService_v3`, new wrappers
   `.iService_v4` and (new canonical) `.iService` (version 5) were added.
2. Instead using `isinstance` to check interface versions, you should always use
   `VERSION` attribute on wrapper class instance.


Metaclasses
===========

.. autoclass:: iVersionedMeta

Firebird API Interface wrappers
===============================

Base interfaces
---------------
.. autoclass:: iVersioned
.. autoclass:: iReferenceCounted
.. autoclass:: iDisposable
.. autoclass:: iStatus
.. autoclass:: iPluginBase
.. autoclass:: iMaster

Configuration
-------------
.. autoclass:: iConfigEntry
.. autoclass:: iConfig
.. autoclass:: iFirebirdConf_v3
.. autoclass:: iFirebirdConf
.. autoclass:: iConfigManager_v2
.. autoclass:: iConfigManager

Database and service attachments
--------------------------------
.. autoclass:: iProvider
.. autoclass:: iAttachment_v3
.. autoclass:: iAttachment_v4
.. autoclass:: iAttachment
.. autoclass:: iService_v3
.. autoclass:: iService_v4
.. autoclass:: iService
.. autoclass:: iXpbBuilder

Blobs
-----
.. autoclass:: iBlob_v3
.. autoclass:: iBlob

Transactions
------------
.. autoclass:: iTransaction_v3
.. autoclass:: iTransaction
.. autoclass:: iDtcStart
.. autoclass:: iDtc

Metadata
--------
.. autoclass:: iMessageMetadata_v3
.. autoclass:: iMessageMetadata
.. autoclass:: iMetadataBuilder_v3
.. autoclass:: iMetadataBuilder

SQL execution
-------------
.. autoclass:: iStatement_v3
.. autoclass:: iStatement_v4
.. autoclass:: iStatement
.. autoclass:: iResultSet_v3
.. autoclass:: iResultSet
.. autoclass:: iBatch_v3
.. autoclass:: iBatch
.. autoclass:: iBatchCompletionState

Events
------
.. autoclass:: iEvents_v3
.. autoclass:: iEvents

Utilities
---------
.. autoclass:: iTimerControl
.. autoclass:: iUtil_v2
.. autoclass:: iUtil
.. autoclass:: iDecFloat16
.. autoclass:: iDecFloat34
.. autoclass:: iInt128

Other
-----
.. autoclass:: iPluginManager
.. autoclass:: iRequest_v3
.. autoclass:: iRequest

Interface implementations
=========================

.. autoclass:: iVersionedImpl
.. autoclass:: iReferenceCountedImpl
.. autoclass:: iDisposableImpl
.. autoclass:: iVersionCallbackImpl
.. autoclass:: iCryptKeyCallbackImpl
.. autoclass:: iOffsetsCallbackImp
.. autoclass:: iEventCallbackImpl
.. autoclass:: iTimerImpl