Add low-level access to fb_shutdown_callback API functions

libfbclient handle signals on its own, so driver will get shutdown error on SIGTERM/SIGINT/SIGBREAK and there is no other possibilities to prevent it and softly stop process except handling shutdown manually:

Example of fb_shutdown_callback usage:

@FB_SHUTDOWN_CALLBACK
def driver_shutdown_callback(reason, mask, arg):
    return 1 if reason == fb_shutrsn_signal else 0

def api_loaded_hook(api):
    status = ISC_STATUS_ARRAY(20)
    api.fb_shutdown_callback(status, driver_shutdown_callback, fb_shut_confirmation, None)
    if db_api_error(status):
        raise exception_from_status(InternalError, status, "Error while adding shutdown callback")

add_hook(APIHook.LOADED, FirebirdAPI, api_loaded_hook)

Author: artyom-smirnov

firebird/driver/fbapi.py

@@ -123,6 +123,22 @@
 blr_ex_time_tz = 30
 blr_ex_timestamp_tz = 31
 
+# Masks for fb_shutdown_callback
+fb_shut_confirmation = 1
+fb_shut_preproviders = 2
+fb_shut_postproviders = 4
+fb_shut_finish = 8
+fb_shut_exit = 16
+
+# Shutdown reasons, used by engine
+fb_shutrsn_svc_stopped = -1
+fb_shutrsn_no_connection = -2
+fb_shutrsn_app_stopped = -3
+fb_shutrsn_signal = -5
+fb_shutrsn_services = -6
+fb_shutrsn_exit_called = -7
+fb_shutrsn_emergency = -8
+
 if platform.architecture() == ('64bit', 'WindowsPE'):  # pragma: no cover
     intptr_t = c_longlong
     uintptr_t = c_ulonglong
@@ -238,6 +254,7 @@ class ISC_QUAD(Structure):
 
 RESULT_VECTOR = ISC_ULONG * 15
 ISC_EVENT_CALLBACK = CFUNCTYPE(None, POINTER(ISC_UCHAR), c_ushort, POINTER(ISC_UCHAR))
+FB_SHUTDOWN_CALLBACK = CFUNCTYPE(c_int, c_int, c_int, c_void_p)
 
 # >>> Firebird 4
 class ISC_TIME_TZ(Structure):
@@ -1951,6 +1968,13 @@ def __init__(self, filename: Path = None):
         self.fb_sqlstate.restype = None
         self.fb_sqlstate.argtypes = [STRING, ISC_STATUS_PTR]
         #
+        self.fb_shutdown_callback = self.client_library.fb_shutdown_callback
+        self.fb_shutdown_callback.restype = ISC_STATUS
+        self.fb_shutdown_callback.argtypes = [ISC_STATUS_PTR,
+                                              FB_SHUTDOWN_CALLBACK,
+                                              c_int,
+                                              c_void_p]
+        #
         self.isc_sqlcode = self.client_library.isc_sqlcode
         self.isc_sqlcode.restype = ISC_LONG
         self.isc_sqlcode.argtypes = [ISC_STATUS_PTR]