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

odbc_api/handles/
bind.rs
