odbc_api/handles/
bind.rs

1//! Implementation and types required to bind arguments to ODBC parameters.
2
3use odbc_sys::CDataType;
4use std::ffi::c_void;
5
6use crate::DataType;
7
8/// Provides description of C type layout and pointers to it. Used to bind and buffers to ODBC
9/// statements.
10///
11/// # Safety
12///
13/// In case of variable sized types [`Self::indicator_ptr`] must not exceed the value pointed to by
14/// [`Self::value_ptr`]. This requirement is a bit tricky since, if the same indicator buffer is
15/// used in an output paramater the indicator value may be larger in case of truncation.
16///
17/// The values pointed to must be valid for the lifetime of the [`CData`] instance.
18pub unsafe trait CData {
19    /// The identifier of the C data type of the value buffer. When it is retrieving data from the
20    /// data source with `fetch`, the driver converts the data to this type. When it sends data to
21    /// the source, the driver converts the data from this type.
22    fn cdata_type(&self) -> CDataType;
23
24    /// Indicates the length of variable sized types. May be zero for fixed sized types. Used to
25    /// determine the size or existence of input parameters.
26    fn indicator_ptr(&self) -> *const isize;
27
28    /// Pointer to a value corresponding to the one described by `cdata_type`.
29    fn value_ptr(&self) -> *const c_void;
30
31    /// Maximum length of the type in bytes (not characters). It is required to index values in
32    /// bound buffers, if more than one parameter is bound. Can be set to zero for types not bound
33    /// as parameter arrays, i.e. `CStr`.
34    fn buffer_length(&self) -> isize;
35}
36
37/// A type which can be bound mutably to ODBC.
38///
39/// # Safety
40///
41/// Care must be taken to only implement this for types which can maintain their invariants then
42/// ODBC writes into them.
43pub unsafe trait CDataMut: CData {
44    /// Indicates the length of variable sized types. May be zero for fixed sized types.
45    fn mut_indicator_ptr(&mut self) -> *mut isize;
46
47    /// Pointer to a value corresponding to the one described by `cdata_type`.
48    fn mut_value_ptr(&mut self) -> *mut c_void;
49}
50
51/// Stream which can be bound as in input parameter to a statement in order to provide the actual
52/// data at statement execution time, rather than preallocated buffers.
53///
54/// # Safety
55///
56/// [`Self::stream_ptr`] must return a valid pointer to a reference of a dynamic Blob trait object
57/// `(*mut &mut dyn Blob)` which must at least be valid for the lifetime of the instance. The
58/// indicator pointer and C data type must describe that instance truthfully.
59pub unsafe trait DelayedInput: Send {
60    /// Then streaming data to the "data source" the driver converts the data from this type.
61    fn cdata_type(&self) -> CDataType;
62
63    /// Either [`odbc_sys::DATA_AT_EXEC`] in case of streaming from a stream of unknown length (e.g.
64    /// stdin) or the result of [`odbc_sys::len_data_at_exec`] if the length of the stream is known
65    /// in advance (e.g. a File).
66    fn indicator_ptr(&self) -> *const isize;
67
68    /// Pointer to reference of [`crate::parameter::Blob`] the stream or an application defined
69    /// value identifying the stream.
70    fn stream_ptr(&mut self) -> *mut c_void;
71}
72
73/// Can be bound to a single placeholder in an SQL statement.
74///
75/// Users usually will not utilize this trait directly.
76pub trait HasDataType {
77    /// The SQL data as which the parameter is bound to ODBC.
78    fn data_type(&self) -> DataType;
79}
odbc_api/handles/bind.rs

odbc_api/handles/
bind.rs
