diff --git a/microhttpd/0.9.55/AIX-00FB437F4C00/include/microhttpd.h b/microhttpd/0.9.55/AIX-00FB437F4C00/include/microhttpd.h new file mode 100755 index 0000000000000000000000000000000000000000..40a723d6b5c3e0355b41575f27edbb76675a0c7a --- /dev/null +++ b/microhttpd/0.9.55/AIX-00FB437F4C00/include/microhttpd.h @@ -0,0 +1,3456 @@ +/* + This file is part of libmicrohttpd + Copyright (C) 2006-2017 Christian Grothoff (and other contributing authors) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA +*/ + +/** + * @file microhttpd.h + * @brief public interface to libmicrohttpd + * @author Christian Grothoff + * @author Karlson2k (Evgeny Grin) + * @author Chris GauthierDickey + * + * All symbols defined in this header start with MHD. MHD is a small + * HTTP daemon library. As such, it does not have any API for logging + * errors (you can only enable or disable logging to stderr). Also, + * it may not support all of the HTTP features directly, where + * applicable, portions of HTTP may have to be handled by clients of + * the library. + * + * The library is supposed to handle everything that it must handle + * (because the API would not allow clients to do this), such as basic + * connection management; however, detailed interpretations of headers + * -- such as range requests -- and HTTP methods are left to clients. + * The library does understand HEAD and will only send the headers of + * the response and not the body, even if the client supplied a body. + * The library also understands headers that control connection + * management (specifically, "Connection: close" and "Expect: 100 + * continue" are understood and handled automatically). + * + * MHD understands POST data and is able to decode certain formats + * (at the moment only "application/x-www-form-urlencoded" and + * "mulitpart/formdata"). Unsupported encodings and large POST + * submissions may require the application to manually process + * the stream, which is provided to the main application (and thus can be + * processed, just not conveniently by MHD). + * + * The header file defines various constants used by the HTTP protocol. + * This does not mean that MHD actually interprets all of these + * values. The provided constants are exported as a convenience + * for users of the library. MHD does not verify that transmitted + * HTTP headers are part of the standard specification; users of the + * library are free to define their own extensions of the HTTP + * standard and use those with MHD. + * + * All functions are guaranteed to be completely reentrant and + * thread-safe (with the exception of #MHD_set_connection_value, + * which must only be used in a particular context). + * + * + * @defgroup event event-loop control + * MHD API to start and stop the HTTP server and manage the event loop. + * @defgroup response generation of responses + * MHD API used to generate responses. + * @defgroup request handling of requests + * MHD API used to access information about requests. + * @defgroup authentication HTTP authentication + * MHD API related to basic and digest HTTP authentication. + * @defgroup logging logging + * MHD API to mange logging and error handling + * @defgroup specialized misc. specialized functions + * This group includes functions that do not fit into any particular + * category and that are rarely used. + */ + +#ifndef MHD_MICROHTTPD_H +#define MHD_MICROHTTPD_H + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +/* While we generally would like users to use a configure-driven + build process which detects which headers are present and + hence works on any platform, we use "standard" includes here + to build out-of-the-box for beginning users on common systems. + + If generic headers don't work on your platform, include headers + which define 'va_list', 'size_t', 'ssize_t', 'intptr_t', + 'uint16_t', 'uint32_t', 'uint64_t', 'off_t', 'struct sockaddr', + 'socklen_t', 'fd_set' and "#define MHD_PLATFORM_H" before + including "microhttpd.h". Then the following "standard" + includes won't be used (which might be a good idea, especially + on platforms where they do not exist). + */ +#ifndef MHD_PLATFORM_H +#include +#include +#include +#if defined(_WIN32) && !defined(__CYGWIN__) +#include +#if defined(_MSC_FULL_VER) && !defined (_SSIZE_T_DEFINED) +#define _SSIZE_T_DEFINED +typedef intptr_t ssize_t; +#endif /* !_SSIZE_T_DEFINED */ +#else +#include +#include +#include +#endif +#endif + +#if defined(__CYGWIN__) && !defined(_SYS_TYPES_FD_SET) +/* Do not define __USE_W32_SOCKETS under Cygwin! */ +#error Cygwin with winsock fd_set is not supported +#endif + +/** + * Current version of the library. + * 0x01093001 = 1.9.30-1. + */ +#define MHD_VERSION 0x00095500 + +/** + * MHD-internal return code for "YES". + */ +#define MHD_YES 1 + +/** + * MHD-internal return code for "NO". + */ +#define MHD_NO 0 + +/** + * MHD digest auth internal code for an invalid nonce. + */ +#define MHD_INVALID_NONCE -1 + +/** + * Constant used to indicate unknown size (use when + * creating a response). + */ +#ifdef UINT64_MAX +#define MHD_SIZE_UNKNOWN UINT64_MAX +#else +#define MHD_SIZE_UNKNOWN ((uint64_t) -1LL) +#endif + +#ifdef SIZE_MAX +#define MHD_CONTENT_READER_END_OF_STREAM SIZE_MAX +#define MHD_CONTENT_READER_END_WITH_ERROR (SIZE_MAX - 1) +#else +#define MHD_CONTENT_READER_END_OF_STREAM ((size_t) -1LL) +#define MHD_CONTENT_READER_END_WITH_ERROR (((size_t) -1LL) - 1) +#endif + +#ifndef _MHD_EXTERN +#if defined(_WIN32) && defined(MHD_W32LIB) +#define _MHD_EXTERN extern +#elif defined (_WIN32) && defined(MHD_W32DLL) +/* Define MHD_W32DLL when using MHD as W32 .DLL to speed up linker a little */ +#define _MHD_EXTERN __declspec(dllimport) +#else +#define _MHD_EXTERN extern +#endif +#endif + +#ifndef MHD_SOCKET_DEFINED +/** + * MHD_socket is type for socket FDs + */ +#if !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) +#define MHD_POSIX_SOCKETS 1 +typedef int MHD_socket; +#define MHD_INVALID_SOCKET (-1) +#else /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ +#define MHD_WINSOCK_SOCKETS 1 +#include +typedef SOCKET MHD_socket; +#define MHD_INVALID_SOCKET (INVALID_SOCKET) +#endif /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ +#define MHD_SOCKET_DEFINED 1 +#endif /* MHD_SOCKET_DEFINED */ + +/** + * Define MHD_NO_DEPRECATION before including "microhttpd.h" to disable deprecation messages + */ +#ifdef MHD_NO_DEPRECATION +#define _MHD_DEPR_MACRO(msg) +#define _MHD_NO_DEPR_IN_MACRO 1 +#define _MHD_DEPR_IN_MACRO(msg) +#define _MHD_NO_DEPR_FUNC 1 +#define _MHD_DEPR_FUNC(msg) +#endif /* MHD_NO_DEPRECATION */ + +#ifndef _MHD_DEPR_MACRO +#if defined(_MSC_FULL_VER) && _MSC_VER+0 >= 1500 +/* VS 2008 or later */ +/* Stringify macros */ +#define _MHD_INSTRMACRO(a) #a +#define _MHD_STRMACRO(a) _MHD_INSTRMACRO(a) +/* deprecation message */ +#define _MHD_DEPR_MACRO(msg) __pragma(message(__FILE__ "(" _MHD_STRMACRO(__LINE__)"): warning: " msg)) +#define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO(msg) +#elif defined(__clang__) || defined (__GNUC_PATCHLEVEL__) +/* clang or GCC since 3.0 */ +#define _MHD_GCC_PRAG(x) _Pragma (#x) +#if __clang_major__+0 >= 5 || \ + (!defined(__apple_build_version__) && (__clang_major__+0 > 3 || (__clang_major__+0 == 3 && __clang_minor__ >= 3))) || \ + __GNUC__+0 > 4 || (__GNUC__+0 == 4 && __GNUC_MINOR__+0 >= 8) +/* clang >= 3.3 (or XCode's clang >= 5.0) or + GCC >= 4.8 */ +#define _MHD_DEPR_MACRO(msg) _MHD_GCC_PRAG(GCC warning msg) +#define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO(msg) +#else /* older clang or GCC */ +/* clang < 3.3, XCode's clang < 5.0, 3.0 <= GCC < 4.8 */ +#define _MHD_DEPR_MACRO(msg) _MHD_GCC_PRAG(message msg) +#if (__clang_major__+0 > 2 || (__clang_major__+0 == 2 && __clang_minor__ >= 9)) /* FIXME: clang >= 2.9, earlier versions not tested */ +/* clang handles inline pragmas better than GCC */ +#define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO(msg) +#endif /* clang >= 2.9 */ +#endif /* older clang or GCC */ +/* #elif defined(SOMEMACRO) */ /* add compiler-specific macros here if required */ +#endif /* clang || GCC >= 3.0 */ +#endif /* !_MHD_DEPR_MACRO */ + +#ifndef _MHD_DEPR_MACRO +#define _MHD_DEPR_MACRO(msg) +#endif /* !_MHD_DEPR_MACRO */ + +#ifndef _MHD_DEPR_IN_MACRO +#define _MHD_NO_DEPR_IN_MACRO 1 +#define _MHD_DEPR_IN_MACRO(msg) +#endif /* !_MHD_DEPR_IN_MACRO */ + +#ifndef _MHD_DEPR_FUNC +#if defined(_MSC_FULL_VER) && _MSC_VER+0 >= 1400 +/* VS 2005 or later */ +#define _MHD_DEPR_FUNC(msg) __declspec(deprecated(msg)) +#elif defined(_MSC_FULL_VER) && _MSC_VER+0 >= 1310 +/* VS .NET 2003 deprecation do not support custom messages */ +#define _MHD_DEPR_FUNC(msg) __declspec(deprecated) +#elif (__GNUC__+0 >= 5) || (defined (__clang__) && \ + (__clang_major__+0 > 2 || (__clang_major__+0 == 2 && __clang_minor__ >= 9))) /* FIXME: earlier versions not tested */ +/* GCC >= 5.0 or clang >= 2.9 */ +#define _MHD_DEPR_FUNC(msg) __attribute__((deprecated(msg))) +#elif defined (__clang__) || __GNUC__+0 > 3 || (__GNUC__+0 == 3 && __GNUC_MINOR__+0 >= 1) +/* 3.1 <= GCC < 5.0 or clang < 2.9 */ +/* old GCC-style deprecation do not support custom messages */ +#define _MHD_DEPR_FUNC(msg) __attribute__((__deprecated__)) +/* #elif defined(SOMEMACRO) */ /* add compiler-specific macros here if required */ +#endif /* clang < 2.9 || GCC >= 3.1 */ +#endif /* !_MHD_DEPR_FUNC */ + +#ifndef _MHD_DEPR_FUNC +#define _MHD_NO_DEPR_FUNC 1 +#define _MHD_DEPR_FUNC(msg) +#endif /* !_MHD_DEPR_FUNC */ + +/** + * Not all architectures and `printf()`'s support the `long long` type. + * This gives the ability to replace `long long` with just a `long`, + * standard `int` or a `short`. + */ +#ifndef MHD_LONG_LONG +/** + * @deprecated use #MHD_UNSIGNED_LONG_LONG instead! + */ +#define MHD_LONG_LONG long long +#define MHD_UNSIGNED_LONG_LONG unsigned long long +#else /* MHD_LONG_LONG */ +_MHD_DEPR_MACRO("Macro MHD_LONG_LONG is deprecated, use MHD_UNSIGNED_LONG_LONG") +#endif +/** + * Format string for printing a variable of type #MHD_LONG_LONG. + * You should only redefine this if you also define #MHD_LONG_LONG. + */ +#ifndef MHD_LONG_LONG_PRINTF +/** + * @deprecated use #MHD_UNSIGNED_LONG_LONG_PRINTF instead! + */ +#define MHD_LONG_LONG_PRINTF "ll" +#define MHD_UNSIGNED_LONG_LONG_PRINTF "%llu" +#else /* MHD_LONG_LONG_PRINTF */ +_MHD_DEPR_MACRO("Macro MHD_LONG_LONG_PRINTF is deprecated, use MHD_UNSIGNED_LONG_LONG_PRINTF") +#endif + + +/** + * @defgroup httpcode HTTP response codes. + * These are the status codes defined for HTTP responses. + * @{ + */ +/* See http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml */ + +#define MHD_HTTP_CONTINUE 100 +#define MHD_HTTP_SWITCHING_PROTOCOLS 101 +#define MHD_HTTP_PROCESSING 102 + +#define MHD_HTTP_OK 200 +#define MHD_HTTP_CREATED 201 +#define MHD_HTTP_ACCEPTED 202 +#define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION 203 +#define MHD_HTTP_NO_CONTENT 204 +#define MHD_HTTP_RESET_CONTENT 205 +#define MHD_HTTP_PARTIAL_CONTENT 206 +#define MHD_HTTP_MULTI_STATUS 207 +#define MHD_HTTP_ALREADY_REPORTED 208 + +#define MHD_HTTP_IM_USED 226 + +#define MHD_HTTP_MULTIPLE_CHOICES 300 +#define MHD_HTTP_MOVED_PERMANENTLY 301 +#define MHD_HTTP_FOUND 302 +#define MHD_HTTP_SEE_OTHER 303 +#define MHD_HTTP_NOT_MODIFIED 304 +#define MHD_HTTP_USE_PROXY 305 +#define MHD_HTTP_SWITCH_PROXY 306 +#define MHD_HTTP_TEMPORARY_REDIRECT 307 +#define MHD_HTTP_PERMANENT_REDIRECT 308 + +#define MHD_HTTP_BAD_REQUEST 400 +#define MHD_HTTP_UNAUTHORIZED 401 +#define MHD_HTTP_PAYMENT_REQUIRED 402 +#define MHD_HTTP_FORBIDDEN 403 +#define MHD_HTTP_NOT_FOUND 404 +#define MHD_HTTP_METHOD_NOT_ALLOWED 405 +#define MHD_HTTP_NOT_ACCEPTABLE 406 +/** @deprecated */ +#define MHD_HTTP_METHOD_NOT_ACCEPTABLE \ + _MHD_DEPR_IN_MACRO("Value MHD_HTTP_METHOD_NOT_ACCEPTABLE is deprecated, use MHD_HTTP_NOT_ACCEPTABLE") 406 +#define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED 407 +#define MHD_HTTP_REQUEST_TIMEOUT 408 +#define MHD_HTTP_CONFLICT 409 +#define MHD_HTTP_GONE 410 +#define MHD_HTTP_LENGTH_REQUIRED 411 +#define MHD_HTTP_PRECONDITION_FAILED 412 +#define MHD_HTTP_PAYLOAD_TOO_LARGE 413 +/** @deprecated */ +#define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE \ + _MHD_DEPR_IN_MACRO("Value MHD_HTTP_REQUEST_ENTITY_TOO_LARGE is deprecated, use MHD_HTTP_PAYLOAD_TOO_LARGE") 413 +#define MHD_HTTP_URI_TOO_LONG 414 +/** @deprecated */ +#define MHD_HTTP_REQUEST_URI_TOO_LONG \ + _MHD_DEPR_IN_MACRO("Value MHD_HTTP_REQUEST_URI_TOO_LONG is deprecated, use MHD_HTTP_URI_TOO_LONG") 414 +#define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE 415 +#define MHD_HTTP_RANGE_NOT_SATISFIABLE 416 +/** @deprecated */ +#define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE \ + _MHD_DEPR_IN_MACRO("Value MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE is deprecated, use MHD_HTTP_RANGE_NOT_SATISFIABLE") 416 +#define MHD_HTTP_EXPECTATION_FAILED 417 + +#define MHD_HTTP_MISDIRECTED_REQUEST 421 +#define MHD_HTTP_UNPROCESSABLE_ENTITY 422 +#define MHD_HTTP_LOCKED 423 +#define MHD_HTTP_FAILED_DEPENDENCY 424 +#define MHD_HTTP_UNORDERED_COLLECTION 425 +#define MHD_HTTP_UPGRADE_REQUIRED 426 + +#define MHD_HTTP_PRECONDITION_REQUIRED 428 +#define MHD_HTTP_TOO_MANY_REQUESTS 429 +#define MHD_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE 431 + +#define MHD_HTTP_NO_RESPONSE 444 + +#define MHD_HTTP_RETRY_WITH 449 +#define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450 +#define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451 + +#define MHD_HTTP_INTERNAL_SERVER_ERROR 500 +#define MHD_HTTP_NOT_IMPLEMENTED 501 +#define MHD_HTTP_BAD_GATEWAY 502 +#define MHD_HTTP_SERVICE_UNAVAILABLE 503 +#define MHD_HTTP_GATEWAY_TIMEOUT 504 +#define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED 505 +#define MHD_HTTP_VARIANT_ALSO_NEGOTIATES 506 +#define MHD_HTTP_INSUFFICIENT_STORAGE 507 +#define MHD_HTTP_LOOP_DETECTED 508 +#define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509 +#define MHD_HTTP_NOT_EXTENDED 510 +#define MHD_HTTP_NETWORK_AUTHENTICATION_REQUIRED 511 + +/** @} */ /* end of group httpcode */ + +/** + * Returns the string reason phrase for a response code. + * + * If we don't have a string for a status code, we give the first + * message in that status code class. + */ +_MHD_EXTERN const char * +MHD_get_reason_phrase_for (unsigned int code); + + +/** + * Flag to be or-ed with MHD_HTTP status code for + * SHOUTcast. This will cause the response to begin + * with the SHOUTcast "ICY" line instad of "HTTP". + * @ingroup specialized + */ +#define MHD_ICY_FLAG ((uint32_t)(((uint32_t)1) << 31)) + +/** + * @defgroup headers HTTP headers + * These are the standard headers found in HTTP requests and responses. + * See: http://www.iana.org/assignments/message-headers/message-headers.xml + * Registry Version 2017-01-27 + * @{ + */ + +/* Main HTTP headers. */ +/* Standard. RFC7231, Section 5.3.2 */ +#define MHD_HTTP_HEADER_ACCEPT "Accept" +/* Standard. RFC7231, Section 5.3.3 */ +#define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset" +/* Standard. RFC7231, Section 5.3.4; RFC7694, Section 3 */ +#define MHD_HTTP_HEADER_ACCEPT_ENCODING "Accept-Encoding" +/* Standard. RFC7231, Section 5.3.5 */ +#define MHD_HTTP_HEADER_ACCEPT_LANGUAGE "Accept-Language" +/* Standard. RFC7233, Section 2.3 */ +#define MHD_HTTP_HEADER_ACCEPT_RANGES "Accept-Ranges" +/* Standard. RFC7234, Section 5.1 */ +#define MHD_HTTP_HEADER_AGE "Age" +/* Standard. RFC7231, Section 7.4.1 */ +#define MHD_HTTP_HEADER_ALLOW "Allow" +/* Standard. RFC7235, Section 4.2 */ +#define MHD_HTTP_HEADER_AUTHORIZATION "Authorization" +/* Standard. RFC7234, Section 5.2 */ +#define MHD_HTTP_HEADER_CACHE_CONTROL "Cache-Control" +/* Reserved. RFC7230, Section 8.1 */ +#define MHD_HTTP_HEADER_CLOSE "Close" +/* Standard. RFC7230, Section 6.1 */ +#define MHD_HTTP_HEADER_CONNECTION "Connection" +/* Standard. RFC7231, Section 3.1.2.2 */ +#define MHD_HTTP_HEADER_CONTENT_ENCODING "Content-Encoding" +/* Standard. RFC7231, Section 3.1.3.2 */ +#define MHD_HTTP_HEADER_CONTENT_LANGUAGE "Content-Language" +/* Standard. RFC7230, Section 3.3.2 */ +#define MHD_HTTP_HEADER_CONTENT_LENGTH "Content-Length" +/* Standard. RFC7231, Section 3.1.4.2 */ +#define MHD_HTTP_HEADER_CONTENT_LOCATION "Content-Location" +/* Standard. RFC7233, Section 4.2 */ +#define MHD_HTTP_HEADER_CONTENT_RANGE "Content-Range" +/* Standard. RFC7231, Section 3.1.1.5 */ +#define MHD_HTTP_HEADER_CONTENT_TYPE "Content-Type" +/* Standard. RFC7231, Section 7.1.1.2 */ +#define MHD_HTTP_HEADER_DATE "Date" +/* Standard. RFC7232, Section 2.3 */ +#define MHD_HTTP_HEADER_ETAG "ETag" +/* Standard. RFC7231, Section 5.1.1 */ +#define MHD_HTTP_HEADER_EXPECT "Expect" +/* Standard. RFC7234, Section 5.3 */ +#define MHD_HTTP_HEADER_EXPIRES "Expires" +/* Standard. RFC7231, Section 5.5.1 */ +#define MHD_HTTP_HEADER_FROM "From" +/* Standard. RFC7230, Section 5.4 */ +#define MHD_HTTP_HEADER_HOST "Host" +/* Standard. RFC7232, Section 3.1 */ +#define MHD_HTTP_HEADER_IF_MATCH "If-Match" +/* Standard. RFC7232, Section 3.3 */ +#define MHD_HTTP_HEADER_IF_MODIFIED_SINCE "If-Modified-Since" +/* Standard. RFC7232, Section 3.2 */ +#define MHD_HTTP_HEADER_IF_NONE_MATCH "If-None-Match" +/* Standard. RFC7233, Section 3.2 */ +#define MHD_HTTP_HEADER_IF_RANGE "If-Range" +/* Standard. RFC7232, Section 3.4 */ +#define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE "If-Unmodified-Since" +/* Standard. RFC7232, Section 2.2 */ +#define MHD_HTTP_HEADER_LAST_MODIFIED "Last-Modified" +/* Standard. RFC7231, Section 7.1.2 */ +#define MHD_HTTP_HEADER_LOCATION "Location" +/* Standard. RFC7231, Section 5.1.2 */ +#define MHD_HTTP_HEADER_MAX_FORWARDS "Max-Forwards" +/* Standard. RFC7231, Appendix A.1 */ +#define MHD_HTTP_HEADER_MIME_VERSION "MIME-Version" +/* Standard. RFC7234, Section 5.4 */ +#define MHD_HTTP_HEADER_PRAGMA "Pragma" +/* Standard. RFC7235, Section 4.3 */ +#define MHD_HTTP_HEADER_PROXY_AUTHENTICATE "Proxy-Authenticate" +/* Standard. RFC7235, Section 4.4 */ +#define MHD_HTTP_HEADER_PROXY_AUTHORIZATION "Proxy-Authorization" +/* Standard. RFC7233, Section 3.1 */ +#define MHD_HTTP_HEADER_RANGE "Range" +/* Standard. RFC7231, Section 5.5.2 */ +#define MHD_HTTP_HEADER_REFERER "Referer" +/* Standard. RFC7231, Section 7.1.3 */ +#define MHD_HTTP_HEADER_RETRY_AFTER "Retry-After" +/* Standard. RFC7231, Section 7.4.2 */ +#define MHD_HTTP_HEADER_SERVER "Server" +/* Standard. RFC7230, Section 4.3 */ +#define MHD_HTTP_HEADER_TE "TE" +/* Standard. RFC7230, Section 4.4 */ +#define MHD_HTTP_HEADER_TRAILER "Trailer" +/* Standard. RFC7230, Section 3.3.1 */ +#define MHD_HTTP_HEADER_TRANSFER_ENCODING "Transfer-Encoding" +/* Standard. RFC7230, Section 6.7 */ +#define MHD_HTTP_HEADER_UPGRADE "Upgrade" +/* Standard. RFC7231, Section 5.5.3 */ +#define MHD_HTTP_HEADER_USER_AGENT "User-Agent" +/* Standard. RFC7231, Section 7.1.4 */ +#define MHD_HTTP_HEADER_VARY "Vary" +/* Standard. RFC7230, Section 5.7.1 */ +#define MHD_HTTP_HEADER_VIA "Via" +/* Standard. RFC7235, Section 4.1 */ +#define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate" +/* Standard. RFC7234, Section 5.5 */ +#define MHD_HTTP_HEADER_WARNING "Warning" + +/* Additional HTTP headers. */ +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_A_IM "A-IM" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_ACCEPT_ADDITIONS "Accept-Additions" +/* Informational. RFC7089 */ +#define MHD_HTTP_HEADER_ACCEPT_DATETIME "Accept-Datetime" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_ACCEPT_FEATURES "Accept-Features" +/* No category. RFC5789 */ +#define MHD_HTTP_HEADER_ACCEPT_PATCH "Accept-Patch" +/* Standard. RFC7639, Section 2 */ +#define MHD_HTTP_HEADER_ALPN "ALPN" +/* Standard. RFC7838 */ +#define MHD_HTTP_HEADER_ALT_SVC "Alt-Svc" +/* Standard. RFC7838 */ +#define MHD_HTTP_HEADER_ALT_USED "Alt-Used" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_ALTERNATES "Alternates" +/* No category. RFC4437 */ +#define MHD_HTTP_HEADER_APPLY_TO_REDIRECT_REF "Apply-To-Redirect-Ref" +/* Experimental. RFC8053, Section 4 */ +#define MHD_HTTP_HEADER_AUTHENTICATION_CONTROL "Authentication-Control" +/* Standard. RFC7615, Section 3 */ +#define MHD_HTTP_HEADER_AUTHENTICATION_INFO "Authentication-Info" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_EXT "C-Ext" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_MAN "C-Man" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_OPT "C-Opt" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_PEP "C-PEP" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_PEP_INFO "C-PEP-Info" +/* Standard. RFC7809, Section 7.1 */ +#define MHD_HTTP_HEADER_CALDAV_TIMEZONES "CalDAV-Timezones" +/* Obsoleted. RFC2068; RFC2616 */ +#define MHD_HTTP_HEADER_CONTENT_BASE "Content-Base" +/* Standard. RFC6266 */ +#define MHD_HTTP_HEADER_CONTENT_DISPOSITION "Content-Disposition" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_ID "Content-ID" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_MD5 "Content-MD5" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_SCRIPT_TYPE "Content-Script-Type" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_STYLE_TYPE "Content-Style-Type" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_VERSION "Content-Version" +/* Standard. RFC6265 */ +#define MHD_HTTP_HEADER_COOKIE "Cookie" +/* Obsoleted. RFC2965; RFC6265 */ +#define MHD_HTTP_HEADER_COOKIE2 "Cookie2" +/* Standard. RFC5323 */ +#define MHD_HTTP_HEADER_DASL "DASL" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_DAV "DAV" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DEFAULT_STYLE "Default-Style" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DELTA_BASE "Delta-Base" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_DEPTH "Depth" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DERIVED_FROM "Derived-From" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_DESTINATION "Destination" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DIFFERENTIAL_ID "Differential-ID" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DIGEST "Digest" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_EXT "Ext" +/* Standard. RFC7239 */ +#define MHD_HTTP_HEADER_FORWARDED "Forwarded" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_GETPROFILE "GetProfile" +/* Experimental. RFC7486, Section 6.1.1 */ +#define MHD_HTTP_HEADER_HOBAREG "Hobareg" +/* Standard. RFC7540, Section 3.2.1 */ +#define MHD_HTTP_HEADER_HTTP2_SETTINGS "HTTP2-Settings" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_IM "IM" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_IF "If" +/* Standard. RFC6638 */ +#define MHD_HTTP_HEADER_IF_SCHEDULE_TAG_MATCH "If-Schedule-Tag-Match" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_KEEP_ALIVE "Keep-Alive" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_LABEL "Label" +/* No category. RFC5988 */ +#define MHD_HTTP_HEADER_LINK "Link" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_LOCK_TOKEN "Lock-Token" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_MAN "Man" +/* Informational. RFC7089 */ +#define MHD_HTTP_HEADER_MEMENTO_DATETIME "Memento-Datetime" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_METER "Meter" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_NEGOTIATE "Negotiate" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_OPT "Opt" +/* Experimental. RFC8053, Section 3 */ +#define MHD_HTTP_HEADER_OPTIONAL_WWW_AUTHENTICATE "Optional-WWW-Authenticate" +/* Standard. RFC4229 */ +#define MHD_HTTP_HEADER_ORDERING_TYPE "Ordering-Type" +/* Standard. RFC6454 */ +#define MHD_HTTP_HEADER_ORIGIN "Origin" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_OVERWRITE "Overwrite" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_P3P "P3P" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PEP "PEP" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PICS_LABEL "PICS-Label" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PEP_INFO "Pep-Info" +/* Standard. RFC4229 */ +#define MHD_HTTP_HEADER_POSITION "Position" +/* Standard. RFC7240 */ +#define MHD_HTTP_HEADER_PREFER "Prefer" +/* Standard. RFC7240 */ +#define MHD_HTTP_HEADER_PREFERENCE_APPLIED "Preference-Applied" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROFILEOBJECT "ProfileObject" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROTOCOL "Protocol" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROTOCOL_INFO "Protocol-Info" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROTOCOL_QUERY "Protocol-Query" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROTOCOL_REQUEST "Protocol-Request" +/* Standard. RFC7615, Section 4 */ +#define MHD_HTTP_HEADER_PROXY_AUTHENTICATION_INFO "Proxy-Authentication-Info" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROXY_FEATURES "Proxy-Features" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROXY_INSTRUCTION "Proxy-Instruction" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PUBLIC "Public" +/* Standard. RFC7469 */ +#define MHD_HTTP_HEADER_PUBLIC_KEY_PINS "Public-Key-Pins" +/* Standard. RFC7469 */ +#define MHD_HTTP_HEADER_PUBLIC_KEY_PINS_REPORT_ONLY "Public-Key-Pins-Report-Only" +/* No category. RFC4437 */ +#define MHD_HTTP_HEADER_REDIRECT_REF "Redirect-Ref" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SAFE "Safe" +/* Standard. RFC6638 */ +#define MHD_HTTP_HEADER_SCHEDULE_REPLY "Schedule-Reply" +/* Standard. RFC6638 */ +#define MHD_HTTP_HEADER_SCHEDULE_TAG "Schedule-Tag" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT "Sec-WebSocket-Accept" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_EXTENSIONS "Sec-WebSocket-Extensions" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY "Sec-WebSocket-Key" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_PROTOCOL "Sec-WebSocket-Protocol" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION "Sec-WebSocket-Version" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SECURITY_SCHEME "Security-Scheme" +/* Standard. RFC6265 */ +#define MHD_HTTP_HEADER_SET_COOKIE "Set-Cookie" +/* Obsoleted. RFC2965; RFC6265 */ +#define MHD_HTTP_HEADER_SET_COOKIE2 "Set-Cookie2" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SETPROFILE "SetProfile" +/* Standard. RFC5023 */ +#define MHD_HTTP_HEADER_SLUG "SLUG" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SOAPACTION "SoapAction" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_STATUS_URI "Status-URI" +/* Standard. RFC6797 */ +#define MHD_HTTP_HEADER_STRICT_TRANSPORT_SECURITY "Strict-Transport-Security" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SURROGATE_CAPABILITY "Surrogate-Capability" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SURROGATE_CONTROL "Surrogate-Control" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_TCN "TCN" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_TIMEOUT "Timeout" +/* Standard. RFC8030, Section 5.4 */ +#define MHD_HTTP_HEADER_TOPIC "Topic" +/* Standard. RFC8030, Section 5.2 */ +#define MHD_HTTP_HEADER_TTL "TTL" +/* Standard. RFC8030, Section 5.3 */ +#define MHD_HTTP_HEADER_URGENCY "Urgency" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_URI "URI" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_VARIANT_VARY "Variant-Vary" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_WANT_DIGEST "Want-Digest" +/* Informational. RFC7034 */ +#define MHD_HTTP_HEADER_X_FRAME_OPTIONS "X-Frame-Options" + +/* Some provisional headers. */ +#define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN "Access-Control-Allow-Origin" +/** @} */ /* end of group headers */ + +/** + * @defgroup versions HTTP versions + * These strings should be used to match against the first line of the + * HTTP header. + * @{ + */ +#define MHD_HTTP_VERSION_1_0 "HTTP/1.0" +#define MHD_HTTP_VERSION_1_1 "HTTP/1.1" + +/** @} */ /* end of group versions */ + +/** + * @defgroup methods HTTP methods + * HTTP methods (as strings). + * See: http://www.iana.org/assignments/http-methods/http-methods.xml + * Registry Version 2015-05-19 + * @{ + */ +/* Main HTTP methods. */ +/* Not safe. Not idempotent. RFC7231, Section 4.3.6. */ +#define MHD_HTTP_METHOD_CONNECT "CONNECT" +/* Not safe. Idempotent. RFC7231, Section 4.3.5. */ +#define MHD_HTTP_METHOD_DELETE "DELETE" +/* Safe. Idempotent. RFC7231, Section 4.3.1. */ +#define MHD_HTTP_METHOD_GET "GET" +/* Safe. Idempotent. RFC7231, Section 4.3.2. */ +#define MHD_HTTP_METHOD_HEAD "HEAD" +/* Safe. Idempotent. RFC7231, Section 4.3.7. */ +#define MHD_HTTP_METHOD_OPTIONS "OPTIONS" +/* Not safe. Not idempotent. RFC7231, Section 4.3.3. */ +#define MHD_HTTP_METHOD_POST "POST" +/* Not safe. Idempotent. RFC7231, Section 4.3.4. */ +#define MHD_HTTP_METHOD_PUT "PUT" +/* Safe. Idempotent. RFC7231, Section 4.3.8. */ +#define MHD_HTTP_METHOD_TRACE "TRACE" + +/* Additional HTTP methods. */ +/* Not safe. Idempotent. RFC3744, Section 8.1. */ +#define MHD_HTTP_METHOD_ACL "ACL" +/* Not safe. Idempotent. RFC3253, Section 12.6. */ +#define MHD_HTTP_METHOD_BASELINE_CONTROL "BASELINE-CONTROL" +/* Not safe. Idempotent. RFC5842, Section 4. */ +#define MHD_HTTP_METHOD_BIND "BIND" +/* Not safe. Idempotent. RFC3253, Section 4.4, Section 9.4. */ +#define MHD_HTTP_METHOD_CHECKIN "CHECKIN" +/* Not safe. Idempotent. RFC3253, Section 4.3, Section 8.8. */ +#define MHD_HTTP_METHOD_CHECKOUT "CHECKOUT" +/* Not safe. Idempotent. RFC4918, Section 9.8. */ +#define MHD_HTTP_METHOD_COPY "COPY" +/* Not safe. Idempotent. RFC3253, Section 8.2. */ +#define MHD_HTTP_METHOD_LABEL "LABEL" +/* Not safe. Idempotent. RFC2068, Section 19.6.1.2. */ +#define MHD_HTTP_METHOD_LINK "LINK" +/* Not safe. Not idempotent. RFC4918, Section 9.10. */ +#define MHD_HTTP_METHOD_LOCK "LOCK" +/* Not safe. Idempotent. RFC3253, Section 11.2. */ +#define MHD_HTTP_METHOD_MERGE "MERGE" +/* Not safe. Idempotent. RFC3253, Section 13.5. */ +#define MHD_HTTP_METHOD_MKACTIVITY "MKACTIVITY" +/* Not safe. Idempotent. RFC4791, Section 5.3.1. */ +#define MHD_HTTP_METHOD_MKCALENDAR "MKCALENDAR" +/* Not safe. Idempotent. RFC4918, Section 9.3. */ +#define MHD_HTTP_METHOD_MKCOL "MKCOL" +/* Not safe. Idempotent. RFC4437, Section 6. */ +#define MHD_HTTP_METHOD_MKREDIRECTREF "MKREDIRECTREF" +/* Not safe. Idempotent. RFC3253, Section 6.3. */ +#define MHD_HTTP_METHOD_MKWORKSPACE "MKWORKSPACE" +/* Not safe. Idempotent. RFC4918, Section 9.9. */ +#define MHD_HTTP_METHOD_MOVE "MOVE" +/* Not safe. Idempotent. RFC3648, Section 7. */ +#define MHD_HTTP_METHOD_ORDERPATCH "ORDERPATCH" +/* Not safe. Not idempotent. RFC5789, Section 2. */ +#define MHD_HTTP_METHOD_PATCH "PATCH" +/* Safe. Idempotent. RFC7540, Section 3.5. */ +#define MHD_HTTP_METHOD_PRI "PRI" +/* Safe. Idempotent. RFC4918, Section 9.1. */ +#define MHD_HTTP_METHOD_PROPFIND "PROPFIND" +/* Not safe. Idempotent. RFC4918, Section 9.2. */ +#define MHD_HTTP_METHOD_PROPPATCH "PROPPATCH" +/* Not safe. Idempotent. RFC5842, Section 6. */ +#define MHD_HTTP_METHOD_REBIND "REBIND" +/* Safe. Idempotent. RFC3253, Section 3.6. */ +#define MHD_HTTP_METHOD_REPORT "REPORT" +/* Safe. Idempotent. RFC5323, Section 2. */ +#define MHD_HTTP_METHOD_SEARCH "SEARCH" +/* Not safe. Idempotent. RFC5842, Section 5. */ +#define MHD_HTTP_METHOD_UNBIND "UNBIND" +/* Not safe. Idempotent. RFC3253, Section 4.5. */ +#define MHD_HTTP_METHOD_UNCHECKOUT "UNCHECKOUT" +/* Not safe. Idempotent. RFC2068, Section 19.6.1.3. */ +#define MHD_HTTP_METHOD_UNLINK "UNLINK" +/* Not safe. Idempotent. RFC4918, Section 9.11. */ +#define MHD_HTTP_METHOD_UNLOCK "UNLOCK" +/* Not safe. Idempotent. RFC3253, Section 7.1. */ +#define MHD_HTTP_METHOD_UPDATE "UPDATE" +/* Not safe. Idempotent. RFC4437, Section 7. */ +#define MHD_HTTP_METHOD_UPDATEREDIRECTREF "UPDATEREDIRECTREF" +/* Not safe. Idempotent. RFC3253, Section 3.5. */ +#define MHD_HTTP_METHOD_VERSION_CONTROL "VERSION-CONTROL" + +/** @} */ /* end of group methods */ + +/** + * @defgroup postenc HTTP POST encodings + * See also: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4 + * @{ + */ +#define MHD_HTTP_POST_ENCODING_FORM_URLENCODED "application/x-www-form-urlencoded" +#define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data" + +/** @} */ /* end of group postenc */ + + +/** + * @brief Handle for the daemon (listening on a socket for HTTP traffic). + * @ingroup event + */ +struct MHD_Daemon; + +/** + * @brief Handle for a connection / HTTP request. + * + * With HTTP/1.1, multiple requests can be run over the same + * connection. However, MHD will only show one request per TCP + * connection to the client at any given time. + * @ingroup request + */ +struct MHD_Connection; + +/** + * @brief Handle for a response. + * @ingroup response + */ +struct MHD_Response; + +/** + * @brief Handle for POST processing. + * @ingroup response + */ +struct MHD_PostProcessor; + + +/** + * @brief Flags for the `struct MHD_Daemon`. + * + * Note that MHD will run automatically in background thread(s) only + * if #MHD_USE_INTERNAL_POLLING_THREAD is used. Otherwise caller (application) + * must use #MHD_run() or #MHD_run_from_select() to have MHD processed + * network connections and data. + * + * Starting the daemon may also fail if a particular option is not + * implemented or not supported on the target platform (i.e. no + * support for TLS, epoll or IPv6). + */ +enum MHD_FLAG +{ + /** + * No options selected. + */ + MHD_NO_FLAG = 0, + + /** + * Print errors messages to custom error logger or to `stderr` if + * custom error logger is not set. + * @sa ::MHD_OPTION_EXTERNAL_LOGGER + */ + MHD_USE_ERROR_LOG = 1, + + /** + * Run in debug mode. If this flag is used, the library should + * print error messages and warnings to `stderr`. + */ + MHD_USE_DEBUG = 1, + + /** + * Run in HTTPS mode. The modern protocol is called TLS. + */ + MHD_USE_TLS = 2, + + /** @deprecated */ + MHD_USE_SSL = 2, +#if 0 + /* let's do this later once versions that define MHD_USE_TLS a more widely deployed. */ +#define MHD_USE_SSL \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_SSL is deprecated, use MHD_USE_TLS") \ + MHD_USE_TLS +#endif + + /** + * Run using one thread per connection. + * Must be used only with #MHD_USE_INTERNAL_POLLING_THREAD. + */ + MHD_USE_THREAD_PER_CONNECTION = 4, + + /** + * Run using an internal thread (or thread pool) for sockets sending + * and receiving and data processing. Without this flag MHD will not + * run automatically in background thread(s). + * If this flag is set, #MHD_run() and #MHD_run_from_select() couldn't + * be used. + * This flag is set explicitly by #MHD_USE_POLL_INTERNAL_THREAD and + * by #MHD_USE_EPOLL_INTERNAL_THREAD. + */ + MHD_USE_INTERNAL_POLLING_THREAD = 8, + + /** @deprecated */ + MHD_USE_SELECT_INTERNALLY = 8, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_SELECT_INTERNALLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_SELECT_INTERNALLY is deprecated, use MHD_USE_INTERNAL_POLLING_THREAD instead") \ + MHD_USE_INTERNAL_POLLING_THREAD +#endif /* 0 */ + + /** + * Run using the IPv6 protocol (otherwise, MHD will just support + * IPv4). If you want MHD to support IPv4 and IPv6 using a single + * socket, pass #MHD_USE_DUAL_STACK, otherwise, if you only pass + * this option, MHD will try to bind to IPv6-only (resulting in + * no IPv4 support). + */ + MHD_USE_IPv6 = 16, + + /** + * Be pedantic about the protocol (as opposed to as tolerant as + * possible). Specifically, at the moment, this flag causes MHD to + * reject HTTP 1.1 connections without a "Host" header. This is + * required by the standard, but of course in violation of the "be + * as liberal as possible in what you accept" norm. It is + * recommended to turn this ON if you are testing clients against + * MHD, and OFF in production. + */ + MHD_USE_PEDANTIC_CHECKS = 32, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_PEDANTIC_CHECKS \ + _MHD_DEPR_IN_MACRO("Flag MHD_USE_PEDANTIC_CHECKS is deprecated, use option MHD_OPTION_STRICT_FOR_CLIENT instead") \ + 32 +#endif /* 0 */ + + /** + * Use `poll()` instead of `select()`. This allows sockets with `fd >= + * FD_SETSIZE`. This option is not compatible with using an + * 'external' polling mode (as there is no API to get the file + * descriptors for the external poll() from MHD) and must also not + * be used in combination with #MHD_USE_EPOLL. + * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL_INTERNAL_THREAD + */ + MHD_USE_POLL = 64, + + /** + * Run using an internal thread (or thread pool) doing `poll()`. + * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL, #MHD_USE_INTERNAL_POLLING_THREAD + */ + MHD_USE_POLL_INTERNAL_THREAD = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, + + /** @deprecated */ + MHD_USE_POLL_INTERNALLY = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_POLL_INTERNALLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_POLL_INTERNALLY is deprecated, use MHD_USE_POLL_INTERNAL_THREAD instead") \ + MHD_USE_POLL_INTERNAL_THREAD +#endif /* 0 */ + + /** + * Suppress (automatically) adding the 'Date:' header to HTTP responses. + * This option should ONLY be used on systems that do not have a clock + * and that DO provide other mechanisms for cache control. See also + * RFC 2616, section 14.18 (exception 3). + */ + MHD_USE_SUPPRESS_DATE_NO_CLOCK = 128, + + /** @deprecated */ + MHD_SUPPRESS_DATE_NO_CLOCK = 128, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_SUPPRESS_DATE_NO_CLOCK \ + _MHD_DEPR_IN_MACRO("Value MHD_SUPPRESS_DATE_NO_CLOCK is deprecated, use MHD_USE_SUPPRESS_DATE_NO_CLOCK instead") \ + MHD_USE_SUPPRESS_DATE_NO_CLOCK +#endif /* 0 */ + + /** + * Run without a listen socket. This option only makes sense if + * #MHD_add_connection is to be used exclusively to connect HTTP + * clients to the HTTP server. This option is incompatible with + * using a thread pool; if it is used, #MHD_OPTION_THREAD_POOL_SIZE + * is ignored. + */ + MHD_USE_NO_LISTEN_SOCKET = 256, + + /** + * Use `epoll()` instead of `select()` or `poll()` for the event loop. + * This option is only available on some systems; using the option on + * systems without epoll will cause #MHD_start_daemon to fail. Using + * this option is not supported with #MHD_USE_THREAD_PER_CONNECTION. + * @sa ::MHD_FEATURE_EPOLL + */ + MHD_USE_EPOLL = 512, + + /** @deprecated */ + MHD_USE_EPOLL_LINUX_ONLY = 512, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_EPOLL_LINUX_ONLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_EPOLL_LINUX_ONLY is deprecated, use MHD_USE_EPOLL") \ + MHD_USE_EPOLL +#endif /* 0 */ + + /** + * Run using an internal thread (or thread pool) doing `epoll()`. + * This option is only available on certain platforms; using the option on + * platform without `epoll` support will cause #MHD_start_daemon to fail. + * @sa ::MHD_FEATURE_EPOLL, #MHD_USE_EPOLL, #MHD_USE_INTERNAL_POLLING_THREAD + */ + MHD_USE_EPOLL_INTERNAL_THREAD = MHD_USE_EPOLL | MHD_USE_INTERNAL_POLLING_THREAD, + + /** @deprecated */ + MHD_USE_EPOLL_INTERNALLY = MHD_USE_EPOLL | MHD_USE_INTERNAL_POLLING_THREAD, + /** @deprecated */ + MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_EPOLL | MHD_USE_INTERNAL_POLLING_THREAD, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_EPOLL_INTERNALLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_EPOLL_INTERNALLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ + MHD_USE_EPOLL_INTERNAL_THREAD + /** @deprecated */ +#define MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ + MHD_USE_EPOLL_INTERNAL_THREAD +#endif /* 0 */ + + /** + * Use inter-thread communication channel. + * #MHD_USE_ITC can be used with #MHD_USE_INTERNAL_POLLING_THREAD + * and is ignored with any "external" mode. + * It's required for use of #MHD_quiesce_daemon + * or #MHD_add_connection. + * This option is enforced by #MHD_ALLOW_SUSPEND_RESUME or + * #MHD_USE_NO_LISTEN_SOCKET. + * #MHD_USE_ITC is always used automatically on platforms + * where select()/poll()/other ignore shutdown of listen + * socket. + */ + MHD_USE_ITC = 1024, + + /** @deprecated */ + MHD_USE_PIPE_FOR_SHUTDOWN = 1024, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_PIPE_FOR_SHUTDOWN \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_PIPE_FOR_SHUTDOWN is deprecated, use MHD_USE_ITC") \ + MHD_USE_ITC +#endif /* 0 */ + + /** + * Use a single socket for IPv4 and IPv6. + */ + MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048, + + /** + * Enable `turbo`. Disables certain calls to `shutdown()`, + * enables aggressive non-blocking optimistic reads and + * other potentially unsafe optimizations. + * Most effects only happen with #MHD_USE_EPOLL. + */ + MHD_USE_TURBO = 4096, + + /** @deprecated */ + MHD_USE_EPOLL_TURBO = 4096, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_EPOLL_TURBO \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_EPOLL_TURBO is deprecated, use MHD_USE_TURBO") \ + MHD_USE_TURBO +#endif /* 0 */ + + /** + * Enable suspend/resume functions, which also implies setting up + * ITC to signal resume. + */ + MHD_ALLOW_SUSPEND_RESUME = 8192 | MHD_USE_ITC, + + /** @deprecated */ + MHD_USE_SUSPEND_RESUME = 8192 | MHD_USE_ITC, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_SUSPEND_RESUME \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_SUSPEND_RESUME is deprecated, use MHD_ALLOW_SUSPEND_RESUME instead") \ + MHD_ALLOW_SUSPEND_RESUME +#endif /* 0 */ + + /** + * Enable TCP_FASTOPEN option. This option is only available on Linux with a + * kernel >= 3.6. On other systems, using this option cases #MHD_start_daemon + * to fail. + */ + MHD_USE_TCP_FASTOPEN = 16384, + + /** + * You need to set this option if you want to use HTTP "Upgrade". + * "Upgrade" may require usage of additional internal resources, + * which we do not want to use unless necessary. + */ + MHD_ALLOW_UPGRADE = 32768, + + /** + * Automatically use best available polling function. + * Choice of polling function is also depend on other daemon options. + * If #MHD_USE_INTERNAL_POLLING_THREAD is specified then epoll, poll() or + * select() will be used (listed in decreasing preference order, first + * function available on system will be used). + * If #MHD_USE_THREAD_PER_CONNECTION is specified then poll() or select() + * will be used. + * If those flags are not specified then epoll or select() will be + * used (as the only suitable for MHD_get_fdset()) + */ + MHD_USE_AUTO = 65536, + + /** + * Run using an internal thread (or thread pool) with best available on + * system polling function. + * This is combination of #MHD_USE_AUTO and #MHD_USE_INTERNAL_POLLING_THREAD + * flags. + */ + MHD_USE_AUTO_INTERNAL_THREAD = MHD_USE_AUTO | MHD_USE_INTERNAL_POLLING_THREAD + +}; + + +/** + * Type of a callback function used for logging by MHD. + * + * @param cls closure + * @param fm format string (`printf()`-style) + * @param ap arguments to @a fm + * @ingroup logging + */ +typedef void +(*MHD_LogCallback)(void *cls, + const char *fm, + va_list ap); + + +/** + * @brief MHD options. + * + * Passed in the varargs portion of #MHD_start_daemon. + */ +enum MHD_OPTION +{ + + /** + * No more options / last option. This is used + * to terminate the VARARGs list. + */ + MHD_OPTION_END = 0, + + /** + * Maximum memory size per connection (followed by a `size_t`). + * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT). + * Values above 128k are unlikely to result in much benefit, as half + * of the memory will be typically used for IO, and TCP buffers are + * unlikely to support window sizes above 64k on most systems. + */ + MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1, + + /** + * Maximum number of concurrent connections to + * accept (followed by an `unsigned int`). + */ + MHD_OPTION_CONNECTION_LIMIT = 2, + + /** + * After how many seconds of inactivity should a + * connection automatically be timed out? (followed + * by an `unsigned int`; use zero for no timeout). + */ + MHD_OPTION_CONNECTION_TIMEOUT = 3, + + /** + * Register a function that should be called whenever a request has + * been completed (this can be used for application-specific clean + * up). Requests that have never been presented to the application + * (via #MHD_AccessHandlerCallback) will not result in + * notifications. + * + * This option should be followed by TWO pointers. First a pointer + * to a function of type #MHD_RequestCompletedCallback and second a + * pointer to a closure to pass to the request completed callback. + * The second pointer maybe NULL. + */ + MHD_OPTION_NOTIFY_COMPLETED = 4, + + /** + * Limit on the number of (concurrent) connections made to the + * server from the same IP address. Can be used to prevent one + * IP from taking over all of the allowed connections. If the + * same IP tries to establish more than the specified number of + * connections, they will be immediately rejected. The option + * should be followed by an `unsigned int`. The default is + * zero, which means no limit on the number of connections + * from the same IP address. + */ + MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5, + + /** + * Bind daemon to the supplied `struct sockaddr`. This option should + * be followed by a `struct sockaddr *`. If #MHD_USE_IPv6 is + * specified, the `struct sockaddr*` should point to a `struct + * sockaddr_in6`, otherwise to a `struct sockaddr_in`. + */ + MHD_OPTION_SOCK_ADDR = 6, + + /** + * Specify a function that should be called before parsing the URI from + * the client. The specified callback function can be used for processing + * the URI (including the options) before it is parsed. The URI after + * parsing will no longer contain the options, which maybe inconvenient for + * logging. This option should be followed by two arguments, the first + * one must be of the form + * + * void * my_logger(void *cls, const char *uri, struct MHD_Connection *con) + * + * where the return value will be passed as + * (`* con_cls`) in calls to the #MHD_AccessHandlerCallback + * when this request is processed later; returning a + * value of NULL has no special significance (however, + * note that if you return non-NULL, you can no longer + * rely on the first call to the access handler having + * `NULL == *con_cls` on entry;) + * "cls" will be set to the second argument following + * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will + * be the 0-terminated URI of the request. + * + * Note that during the time of this call, most of the connection's + * state is not initialized (as we have not yet parsed the headers). + * However, information about the connecting client (IP, socket) + * is available. + * + * The specified function is called only once per request, therefore some + * programmers may use it to instantiate their own request objects, freeing + * them in the notifier #MHD_OPTION_NOTIFY_COMPLETED. + */ + MHD_OPTION_URI_LOG_CALLBACK = 7, + + /** + * Memory pointer for the private key (key.pem) to be used by the + * HTTPS daemon. This option should be followed by a + * `const char *` argument. + * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT. + */ + MHD_OPTION_HTTPS_MEM_KEY = 8, + + /** + * Memory pointer for the certificate (cert.pem) to be used by the + * HTTPS daemon. This option should be followed by a + * `const char *` argument. + * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. + */ + MHD_OPTION_HTTPS_MEM_CERT = 9, + + /** + * Daemon credentials type. + * Followed by an argument of type + * `gnutls_credentials_type_t`. + */ + MHD_OPTION_HTTPS_CRED_TYPE = 10, + + /** + * Memory pointer to a `const char *` specifying the + * cipher algorithm (default: "NORMAL"). + */ + MHD_OPTION_HTTPS_PRIORITIES = 11, + + /** + * Pass a listen socket for MHD to use (systemd-style). If this + * option is used, MHD will not open its own listen socket(s). The + * argument passed must be of type `MHD_socket` and refer to an + * existing socket that has been bound to a port and is listening. + */ + MHD_OPTION_LISTEN_SOCKET = 12, + + /** + * Use the given function for logging error messages. This option + * must be followed by two arguments; the first must be a pointer to + * a function of type #MHD_LogCallback and the second a pointer + * `void *` which will be passed as the first argument to the log + * callback. + * + * Note that MHD will not generate any log messages + * if it was compiled without the "--enable-messages" + * flag being set. + */ + MHD_OPTION_EXTERNAL_LOGGER = 13, + + /** + * Number (`unsigned int`) of threads in thread pool. Enable + * thread pooling by setting this value to to something + * greater than 1. Currently, thread model must be + * #MHD_USE_INTERNAL_POLLING_THREAD if thread pooling is enabled + * (#MHD_start_daemon returns NULL for an unsupported thread + * model). + */ + MHD_OPTION_THREAD_POOL_SIZE = 14, + + /** + * Additional options given in an array of `struct MHD_OptionItem`. + * The array must be terminated with an entry `{MHD_OPTION_END, 0, NULL}`. + * An example for code using #MHD_OPTION_ARRAY is: + * + * struct MHD_OptionItem ops[] = { + * { MHD_OPTION_CONNECTION_LIMIT, 100, NULL }, + * { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL }, + * { MHD_OPTION_END, 0, NULL } + * }; + * d = MHD_start_daemon (0, 8080, NULL, NULL, dh, NULL, + * MHD_OPTION_ARRAY, ops, + * MHD_OPTION_END); + * + * For options that expect a single pointer argument, the + * second member of the `struct MHD_OptionItem` is ignored. + * For options that expect two pointer arguments, the first + * argument must be cast to `intptr_t`. + */ + MHD_OPTION_ARRAY = 15, + + /** + * Specify a function that should be called for unescaping escape + * sequences in URIs and URI arguments. Note that this function + * will NOT be used by the `struct MHD_PostProcessor`. If this + * option is not specified, the default method will be used which + * decodes escape sequences of the form "%HH". This option should + * be followed by two arguments, the first one must be of the form + * + * size_t my_unescaper(void *cls, + * struct MHD_Connection *c, + * char *s) + * + * where the return value must be "strlen(s)" and "s" should be + * updated. Note that the unescape function must not lengthen "s" + * (the result must be shorter than the input and still be + * 0-terminated). "cls" will be set to the second argument + * following #MHD_OPTION_UNESCAPE_CALLBACK. + */ + MHD_OPTION_UNESCAPE_CALLBACK = 16, + + /** + * Memory pointer for the random values to be used by the Digest + * Auth module. This option should be followed by two arguments. + * First an integer of type `size_t` which specifies the size + * of the buffer pointed to by the second argument in bytes. + * Note that the application must ensure that the buffer of the + * second argument remains allocated and unmodified while the + * deamon is running. + */ + MHD_OPTION_DIGEST_AUTH_RANDOM = 17, + + /** + * Size of the internal array holding the map of the nonce and + * the nonce counter. This option should be followed by an `unsigend int` + * argument. + */ + MHD_OPTION_NONCE_NC_SIZE = 18, + + /** + * Desired size of the stack for threads created by MHD. Followed + * by an argument of type `size_t`. Use 0 for system default. + */ + MHD_OPTION_THREAD_STACK_SIZE = 19, + + /** + * Memory pointer for the certificate (ca.pem) to be used by the + * HTTPS daemon for client authentification. + * This option should be followed by a `const char *` argument. + */ + MHD_OPTION_HTTPS_MEM_TRUST = 20, + + /** + * Increment to use for growing the read buffer (followed by a + * `size_t`). Must fit within #MHD_OPTION_CONNECTION_MEMORY_LIMIT. + */ + MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21, + + /** + * Use a callback to determine which X.509 certificate should be + * used for a given HTTPS connection. This option should be + * followed by a argument of type `gnutls_certificate_retrieve_function2 *`. + * This option provides an + * alternative to #MHD_OPTION_HTTPS_MEM_KEY, + * #MHD_OPTION_HTTPS_MEM_CERT. You must use this version if + * multiple domains are to be hosted at the same IP address using + * TLS's Server Name Indication (SNI) extension. In this case, + * the callback is expected to select the correct certificate + * based on the SNI information provided. The callback is expected + * to access the SNI data using `gnutls_server_name_get()`. + * Using this option requires GnuTLS 3.0 or higher. + */ + MHD_OPTION_HTTPS_CERT_CALLBACK = 22, + + /** + * When using #MHD_USE_TCP_FASTOPEN, this option changes the default TCP + * fastopen queue length of 50. Note that having a larger queue size can + * cause resource exhaustion attack as the TCP stack has to now allocate + * resources for the SYN packet along with its DATA. This option should be + * followed by an `unsigned int` argument. + */ + MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE = 23, + + /** + * Memory pointer for the Diffie-Hellman parameters (dh.pem) to be used by the + * HTTPS daemon for key exchange. + * This option must be followed by a `const char *` argument. + */ + MHD_OPTION_HTTPS_MEM_DHPARAMS = 24, + + /** + * If present and set to true, allow reusing address:port socket + * (by using SO_REUSEPORT on most platform, or platform-specific ways). + * If present and set to false, disallow reusing address:port socket + * (does nothing on most plaform, but uses SO_EXCLUSIVEADDRUSE on Windows). + * This option must be followed by a `unsigned int` argument. + */ + MHD_OPTION_LISTENING_ADDRESS_REUSE = 25, + + /** + * Memory pointer for a password that decrypts the private key (key.pem) + * to be used by the HTTPS daemon. This option should be followed by a + * `const char *` argument. + * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. + * @sa ::MHD_FEATURE_HTTPS_KEY_PASSWORD + */ + MHD_OPTION_HTTPS_KEY_PASSWORD = 26, + + /** + * Register a function that should be called whenever a connection is + * started or closed. + * + * This option should be followed by TWO pointers. First a pointer + * to a function of type #MHD_NotifyConnectionCallback and second a + * pointer to a closure to pass to the request completed callback. + * The second pointer maybe NULL. + */ + MHD_OPTION_NOTIFY_CONNECTION = 27, + + /** + * Allow to change maximum length of the queue of pending connections on + * listen socket. If not present than default platform-specific SOMAXCONN + * value is used. This option should be followed by an `unsigned int` + * argument. + */ + MHD_OPTION_LISTEN_BACKLOG_SIZE = 28, + + /** + * If set to 1 - be strict about the protocol (as opposed to as + * tolerant as possible). Specifically, at the moment, this flag + * causes MHD to reject HTTP 1.1 connections without a "Host" header. + * This is required by the standard, but of course in violation of + * the "be as liberal as possible in what you accept" norm. It is + * recommended to set this to 1 if you are testing clients against + * MHD, and 0 in production. + * if set to -1 - be opposite to strict and be permissive about the + * protocol, allowing slight deviations that are technically not + * allowed by the RFC. Specifically, at the moment, this flag + * causes MHD to allow spaces in header field names. This is + * disallowed by the standard. + * It is not recommended to set it to -1 on publicly available + * servers as it may potentially lower level of protection. + * This option should be followed by an `int` argument. + */ + MHD_OPTION_STRICT_FOR_CLIENT = 29 +}; + + +/** + * Entry in an #MHD_OPTION_ARRAY. + */ +struct MHD_OptionItem +{ + /** + * Which option is being given. Use #MHD_OPTION_END + * to terminate the array. + */ + enum MHD_OPTION option; + + /** + * Option value (for integer arguments, and for options requiring + * two pointer arguments); should be 0 for options that take no + * arguments or only a single pointer argument. + */ + intptr_t value; + + /** + * Pointer option value (use NULL for options taking no arguments + * or only an integer option). + */ + void *ptr_value; + +}; + + +/** + * The `enum MHD_ValueKind` specifies the source of + * the key-value pairs in the HTTP protocol. + */ +enum MHD_ValueKind +{ + + /** + * Response header + * @deprecated + */ + MHD_RESPONSE_HEADER_KIND = 0, +#define MHD_RESPONSE_HEADER_KIND \ + _MHD_DEPR_IN_MACRO("Value MHD_RESPONSE_HEADER_KIND is deprecated and not used") \ + MHD_RESPONSE_HEADER_KIND + + /** + * HTTP header (request/response). + */ + MHD_HEADER_KIND = 1, + + /** + * Cookies. Note that the original HTTP header containing + * the cookie(s) will still be available and intact. + */ + MHD_COOKIE_KIND = 2, + + /** + * POST data. This is available only if a content encoding + * supported by MHD is used (currently only URL encoding), + * and only if the posted content fits within the available + * memory pool. Note that in that case, the upload data + * given to the #MHD_AccessHandlerCallback will be + * empty (since it has already been processed). + */ + MHD_POSTDATA_KIND = 4, + + /** + * GET (URI) arguments. + */ + MHD_GET_ARGUMENT_KIND = 8, + + /** + * HTTP footer (only for HTTP 1.1 chunked encodings). + */ + MHD_FOOTER_KIND = 16 +}; + + +/** + * The `enum MHD_RequestTerminationCode` specifies reasons + * why a request has been terminated (or completed). + * @ingroup request + */ +enum MHD_RequestTerminationCode +{ + + /** + * We finished sending the response. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_COMPLETED_OK = 0, + + /** + * Error handling the connection (resources + * exhausted, other side closed connection, + * application error accepting request, etc.) + * @ingroup request + */ + MHD_REQUEST_TERMINATED_WITH_ERROR = 1, + + /** + * No activity on the connection for the number + * of seconds specified using + * #MHD_OPTION_CONNECTION_TIMEOUT. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2, + + /** + * We had to close the session since MHD was being + * shut down. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3, + + /** + * We tried to read additional data, but the other side closed the + * connection. This error is similar to + * #MHD_REQUEST_TERMINATED_WITH_ERROR, but specific to the case where + * the connection died because the other side did not send expected + * data. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_READ_ERROR = 4, + + /** + * The client terminated the connection by closing the socket + * for writing (TCP half-closed); MHD aborted sending the + * response according to RFC 2616, section 8.1.4. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_CLIENT_ABORT = 5 + +}; + + +/** + * The `enum MHD_ConnectionNotificationCode` specifies types + * of connection notifications. + * @ingroup request + */ +enum MHD_ConnectionNotificationCode +{ + + /** + * A new connection has been started. + * @ingroup request + */ + MHD_CONNECTION_NOTIFY_STARTED = 0, + + /** + * A connection is closed. + * @ingroup request + */ + MHD_CONNECTION_NOTIFY_CLOSED = 1 + +}; + + +/** + * Information about a connection. + */ +union MHD_ConnectionInfo +{ + + /** + * Cipher algorithm used, of type "enum gnutls_cipher_algorithm". + */ + int /* enum gnutls_cipher_algorithm */ cipher_algorithm; + + /** + * Protocol used, of type "enum gnutls_protocol". + */ + int /* enum gnutls_protocol */ protocol; + + /** + * The suspended status of a connection. + */ + int /* MHD_YES or MHD_NO */ suspended; + + /** + * Amount of second that connection could spend in idle state + * before automatically disconnected. + * Zero for no timeout (unlimited idle time). + */ + unsigned int connection_timeout; + + /** + * Connect socket + */ + MHD_socket connect_fd; + + /** + * Size of the client's HTTP header. + */ + size_t header_size; + + /** + * GNUtls session handle, of type "gnutls_session_t". + */ + void * /* gnutls_session_t */ tls_session; + + /** + * GNUtls client certificate handle, of type "gnutls_x509_crt_t". + */ + void * /* gnutls_x509_crt_t */ client_cert; + + /** + * Address information for the client. + */ + struct sockaddr *client_addr; + + /** + * Which daemon manages this connection (useful in case there are many + * daemons running). + */ + struct MHD_Daemon *daemon; + + /** + * Socket-specific client context. Points to the same address as + * the "socket_context" of the #MHD_NotifyConnectionCallback. + */ + void *socket_context; +}; + + +/** + * Values of this enum are used to specify what + * information about a connection is desired. + * @ingroup request + */ +enum MHD_ConnectionInfoType +{ + /** + * What cipher algorithm is being used. + * Takes no extra arguments. + * @ingroup request + */ + MHD_CONNECTION_INFO_CIPHER_ALGO, + + /** + * + * Takes no extra arguments. + * @ingroup request + */ + MHD_CONNECTION_INFO_PROTOCOL, + + /** + * Obtain IP address of the client. Takes no extra arguments. + * Returns essentially a `struct sockaddr **` (since the API returns + * a `union MHD_ConnectionInfo *` and that union contains a `struct + * sockaddr *`). + * @ingroup request + */ + MHD_CONNECTION_INFO_CLIENT_ADDRESS, + + /** + * Get the gnuTLS session handle. + * @ingroup request + */ + MHD_CONNECTION_INFO_GNUTLS_SESSION, + + /** + * Get the gnuTLS client certificate handle. Dysfunctional (never + * implemented, deprecated). Use #MHD_CONNECTION_INFO_GNUTLS_SESSION + * to get the `gnutls_session_t` and then call + * gnutls_certificate_get_peers(). + */ + MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT, + + /** + * Get the `struct MHD_Daemon *` responsible for managing this connection. + * @ingroup request + */ + MHD_CONNECTION_INFO_DAEMON, + + /** + * Request the file descriptor for the connection socket. + * No extra arguments should be passed. + * @ingroup request + */ + MHD_CONNECTION_INFO_CONNECTION_FD, + + /** + * Returns the client-specific pointer to a `void *` that was (possibly) + * set during a #MHD_NotifyConnectionCallback when the socket was + * first accepted. Note that this is NOT the same as the "con_cls" + * argument of the #MHD_AccessHandlerCallback. The "con_cls" is + * fresh for each HTTP request, while the "socket_context" is fresh + * for each socket. + */ + MHD_CONNECTION_INFO_SOCKET_CONTEXT, + + /** + * Check whether the connection is suspended. + * @ingroup request + */ + MHD_CONNECTION_INFO_CONNECTION_SUSPENDED, + + /** + * Get connection timeout + * @ingroup request + */ + MHD_CONNECTION_INFO_CONNECTION_TIMEOUT, + + /** + * Return length of the client's HTTP request header. + * @ingroup request + */ + MHD_CONNECTION_INFO_REQUEST_HEADER_SIZE +}; + + +/** + * Values of this enum are used to specify what + * information about a deamon is desired. + */ +enum MHD_DaemonInfoType +{ + /** + * No longer supported (will return NULL). + */ + MHD_DAEMON_INFO_KEY_SIZE, + + /** + * No longer supported (will return NULL). + */ + MHD_DAEMON_INFO_MAC_KEY_SIZE, + + /** + * Request the file descriptor for the listening socket. + * No extra arguments should be passed. + */ + MHD_DAEMON_INFO_LISTEN_FD, + + /** + * Request the file descriptor for the external epoll. + * No extra arguments should be passed. + */ + MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, + MHD_DAEMON_INFO_EPOLL_FD = MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, + + /** + * Request the number of current connections handled by the daemon. + * No extra arguments should be passed. + * Note: when using MHD in external polling mode, this type of request + * could be used only when #MHD_run()/#MHD_run_from_select is not + * working in other thread at the same time. + */ + MHD_DAEMON_INFO_CURRENT_CONNECTIONS, + + /** + * Request the daemon flags. + * No extra arguments should be passed. + * Note: flags may differ from original 'flags' specified for + * daemon, especially if #MHD_USE_AUTO was set. + */ + MHD_DAEMON_INFO_FLAGS +}; + + +/** + * Callback for serious error condition. The default action is to print + * an error message and `abort()`. + * + * @param cls user specified value + * @param file where the error occured + * @param line where the error occured + * @param reason error detail, may be NULL + * @ingroup logging + */ +typedef void +(*MHD_PanicCallback) (void *cls, + const char *file, + unsigned int line, + const char *reason); + +/** + * Allow or deny a client to connect. + * + * @param cls closure + * @param addr address information from the client + * @param addrlen length of @a addr + * @return #MHD_YES if connection is allowed, #MHD_NO if not + */ +typedef int +(*MHD_AcceptPolicyCallback) (void *cls, + const struct sockaddr *addr, + socklen_t addrlen); + + +/** + * A client has requested the given url using the given method + * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT, + * #MHD_HTTP_METHOD_DELETE, #MHD_HTTP_METHOD_POST, etc). The callback + * must call MHD callbacks to provide content to give back to the + * client and return an HTTP status code (i.e. #MHD_HTTP_OK, + * #MHD_HTTP_NOT_FOUND, etc.). + * + * @param cls argument given together with the function + * pointer when the handler was registered with MHD + * @param url the requested url + * @param method the HTTP method used (#MHD_HTTP_METHOD_GET, + * #MHD_HTTP_METHOD_PUT, etc.) + * @param version the HTTP version string (i.e. + * #MHD_HTTP_VERSION_1_1) + * @param upload_data the data being uploaded (excluding HEADERS, + * for a POST that fits into memory and that is encoded + * with a supported encoding, the POST data will NOT be + * given in upload_data and is instead available as + * part of #MHD_get_connection_values; very large POST + * data *will* be made available incrementally in + * @a upload_data) + * @param upload_data_size set initially to the size of the + * @a upload_data provided; the method must update this + * value to the number of bytes NOT processed; + * @param con_cls pointer that the callback can set to some + * address and that will be preserved by MHD for future + * calls for this request; since the access handler may + * be called many times (i.e., for a PUT/POST operation + * with plenty of upload data) this allows the application + * to easily associate some request-specific state. + * If necessary, this state can be cleaned up in the + * global #MHD_RequestCompletedCallback (which + * can be set with the #MHD_OPTION_NOTIFY_COMPLETED). + * Initially, `*con_cls` will be NULL. + * @return #MHD_YES if the connection was handled successfully, + * #MHD_NO if the socket must be closed due to a serios + * error while handling the request + */ +typedef int +(*MHD_AccessHandlerCallback) (void *cls, + struct MHD_Connection *connection, + const char *url, + const char *method, + const char *version, + const char *upload_data, + size_t *upload_data_size, + void **con_cls); + + +/** + * Signature of the callback used by MHD to notify the + * application about completed requests. + * + * @param cls client-defined closure + * @param connection connection handle + * @param con_cls value as set by the last call to + * the #MHD_AccessHandlerCallback + * @param toe reason for request termination + * @see #MHD_OPTION_NOTIFY_COMPLETED + * @ingroup request + */ +typedef void +(*MHD_RequestCompletedCallback) (void *cls, + struct MHD_Connection *connection, + void **con_cls, + enum MHD_RequestTerminationCode toe); + +/** + * Signature of the callback used by MHD to notify the + * application about started/stopped connections + * + * @param cls client-defined closure + * @param connection connection handle + * @param socket_context socket-specific pointer where the + * client can associate some state specific + * to the TCP connection; note that this is + * different from the "con_cls" which is per + * HTTP request. The client can initialize + * during #MHD_CONNECTION_NOTIFY_STARTED and + * cleanup during #MHD_CONNECTION_NOTIFY_CLOSED + * and access in the meantime using + * #MHD_CONNECTION_INFO_SOCKET_CONTEXT. + * @param toe reason for connection notification + * @see #MHD_OPTION_NOTIFY_CONNECTION + * @ingroup request + */ +typedef void +(*MHD_NotifyConnectionCallback) (void *cls, + struct MHD_Connection *connection, + void **socket_context, + enum MHD_ConnectionNotificationCode toe); + + +/** + * Iterator over key-value pairs. This iterator + * can be used to iterate over all of the cookies, + * headers, or POST-data fields of a request, and + * also to iterate over the headers that have been + * added to a response. + * + * @param cls closure + * @param kind kind of the header we are looking at + * @param key key for the value, can be an empty string + * @param value corresponding value, can be NULL + * @return #MHD_YES to continue iterating, + * #MHD_NO to abort the iteration + * @ingroup request + */ +typedef int +(*MHD_KeyValueIterator) (void *cls, + enum MHD_ValueKind kind, + const char *key, + const char *value); + + +/** + * Callback used by libmicrohttpd in order to obtain content. The + * callback is to copy at most @a max bytes of content into @a buf. The + * total number of bytes that has been placed into @a buf should be + * returned. + * + * Note that returning zero will cause libmicrohttpd to try again. + * Thus, returning zero should only be used in conjunction + * with MHD_suspend_connection() to avoid busy waiting. + * + * @param cls extra argument to the callback + * @param pos position in the datastream to access; + * note that if a `struct MHD_Response` object is re-used, + * it is possible for the same content reader to + * be queried multiple times for the same data; + * however, if a `struct MHD_Response` is not re-used, + * libmicrohttpd guarantees that "pos" will be + * the sum of all non-negative return values + * obtained from the content reader so far. + * @param buf where to copy the data + * @param max maximum number of bytes to copy to @a buf (size of @a buf) + * @return number of bytes written to @a buf; + * 0 is legal unless we are running in internal select mode (since + * this would cause busy-waiting); 0 in external select mode + * will cause this function to be called again once the external + * select calls MHD again; + * #MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular + * end of transmission (with chunked encoding, MHD will then + * terminate the chunk and send any HTTP footers that might be + * present; without chunked encoding and given an unknown + * response size, MHD will simply close the connection; note + * that while returning #MHD_CONTENT_READER_END_OF_STREAM is not technically + * legal if a response size was specified, MHD accepts this + * and treats it just as #MHD_CONTENT_READER_END_WITH_ERROR; + * #MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server + * error generating the response; this will cause MHD to simply + * close the connection immediately. If a response size was + * given or if chunked encoding is in use, this will indicate + * an error to the client. Note, however, that if the client + * does not know a response size and chunked encoding is not in + * use, then clients will not be able to tell the difference between + * #MHD_CONTENT_READER_END_WITH_ERROR and #MHD_CONTENT_READER_END_OF_STREAM. + * This is not a limitation of MHD but rather of the HTTP protocol. + */ +typedef ssize_t +(*MHD_ContentReaderCallback) (void *cls, + uint64_t pos, + char *buf, + size_t max); + + +/** + * This method is called by libmicrohttpd if we + * are done with a content reader. It should + * be used to free resources associated with the + * content reader. + * + * @param cls closure + * @ingroup response + */ +typedef void +(*MHD_ContentReaderFreeCallback) (void *cls); + + +/** + * Iterator over key-value pairs where the value + * maybe made available in increments and/or may + * not be zero-terminated. Used for processing + * POST data. + * + * @param cls user-specified closure + * @param kind type of the value, always #MHD_POSTDATA_KIND when called from MHD + * @param key 0-terminated key for the value + * @param filename name of the uploaded file, NULL if not known + * @param content_type mime-type of the data, NULL if not known + * @param transfer_encoding encoding of the data, NULL if not known + * @param data pointer to @a size bytes of data at the + * specified offset + * @param off offset of data in the overall value + * @param size number of bytes in @a data available + * @return #MHD_YES to continue iterating, + * #MHD_NO to abort the iteration + */ +typedef int +(*MHD_PostDataIterator) (void *cls, + enum MHD_ValueKind kind, + const char *key, + const char *filename, + const char *content_type, + const char *transfer_encoding, + const char *data, + uint64_t off, + size_t size); + +/* **************** Daemon handling functions ***************** */ + +/** + * Start a webserver on the given port. + * + * @param flags combination of `enum MHD_FLAG` values + * @param port port to bind to (in host byte order) + * @param apc callback to call to check which clients + * will be allowed to connect; you can pass NULL + * in which case connections from any IP will be + * accepted + * @param apc_cls extra argument to apc + * @param dh handler called for all requests (repeatedly) + * @param dh_cls extra argument to @a dh + * @param ap list of options (type-value pairs, + * terminated with #MHD_OPTION_END). + * @return NULL on error, handle to daemon on success + * @ingroup event + */ +_MHD_EXTERN struct MHD_Daemon * +MHD_start_daemon_va (unsigned int flags, + uint16_t port, + MHD_AcceptPolicyCallback apc, void *apc_cls, + MHD_AccessHandlerCallback dh, void *dh_cls, + va_list ap); + + +/** + * Start a webserver on the given port. Variadic version of + * #MHD_start_daemon_va. + * + * @param flags combination of `enum MHD_FLAG` values + * @param port port to bind to + * @param apc callback to call to check which clients + * will be allowed to connect; you can pass NULL + * in which case connections from any IP will be + * accepted + * @param apc_cls extra argument to apc + * @param dh handler called for all requests (repeatedly) + * @param dh_cls extra argument to @a dh + * @return NULL on error, handle to daemon on success + * @ingroup event + */ +_MHD_EXTERN struct MHD_Daemon * +MHD_start_daemon (unsigned int flags, + uint16_t port, + MHD_AcceptPolicyCallback apc, void *apc_cls, + MHD_AccessHandlerCallback dh, void *dh_cls, + ...); + + +/** + * Stop accepting connections from the listening socket. Allows + * clients to continue processing, but stops accepting new + * connections. Note that the caller is responsible for closing the + * returned socket; however, if MHD is run using threads (anything but + * external select mode), it must not be closed until AFTER + * #MHD_stop_daemon has been called (as it is theoretically possible + * that an existing thread is still using it). + * + * Note that some thread modes require the caller to have passed + * #MHD_USE_ITC when using this API. If this daemon is + * in one of those modes and this option was not given to + * #MHD_start_daemon, this function will return #MHD_INVALID_SOCKET. + * + * @param daemon daemon to stop accepting new connections for + * @return old listen socket on success, #MHD_INVALID_SOCKET if + * the daemon was already not listening anymore + * @ingroup specialized + */ +_MHD_EXTERN MHD_socket +MHD_quiesce_daemon (struct MHD_Daemon *daemon); + + +/** + * Shutdown an HTTP daemon. + * + * @param daemon daemon to stop + * @ingroup event + */ +_MHD_EXTERN void +MHD_stop_daemon (struct MHD_Daemon *daemon); + + +/** + * Add another client connection to the set of connections managed by + * MHD. This API is usually not needed (since MHD will accept inbound + * connections on the server socket). Use this API in special cases, + * for example if your HTTP server is behind NAT and needs to connect + * out to the HTTP client, or if you are building a proxy. + * + * If you use this API in conjunction with a internal select or a + * thread pool, you must set the option + * #MHD_USE_ITC to ensure that the freshly added + * connection is immediately processed by MHD. + * + * The given client socket will be managed (and closed!) by MHD after + * this call and must no longer be used directly by the application + * afterwards. + * + * Per-IP connection limits are ignored when using this API. + * + * @param daemon daemon that manages the connection + * @param client_socket socket to manage (MHD will expect + * to receive an HTTP request from this socket next). + * @param addr IP address of the client + * @param addrlen number of bytes in @a addr + * @return #MHD_YES on success, #MHD_NO if this daemon could + * not handle the connection (i.e. `malloc()` failed, etc). + * The socket will be closed in any case; `errno` is + * set to indicate further details about the error. + * @ingroup specialized + */ +_MHD_EXTERN int +MHD_add_connection (struct MHD_Daemon *daemon, + MHD_socket client_socket, + const struct sockaddr *addr, + socklen_t addrlen); + + +/** + * Obtain the `select()` sets for this daemon. + * Daemon's FDs will be added to fd_sets. To get only + * daemon FDs in fd_sets, call FD_ZERO for each fd_set + * before calling this function. FD_SETSIZE is assumed + * to be platform's default. + * + * This function should only be called in when MHD is configured to + * use external select with @code{select()} or with @code{epoll()}. + * In the latter case, it will only add the single @code{epoll()} file + * descriptor used by MHD to the sets. + * + * This function must be called only for daemon started + * without #MHD_USE_INTERNAL_POLLING_THREAD flag. + * + * @param daemon daemon to get sets from + * @param read_fd_set read set + * @param write_fd_set write set + * @param except_fd_set except set + * @param max_fd increased to largest FD added (if larger + * than existing value); can be NULL + * @return #MHD_YES on success, #MHD_NO if this + * daemon was not started with the right + * options for this call or any FD didn't + * fit fd_set. + * @ingroup event + */ +_MHD_EXTERN int +MHD_get_fdset (struct MHD_Daemon *daemon, + fd_set *read_fd_set, + fd_set *write_fd_set, + fd_set *except_fd_set, + MHD_socket *max_fd); + + +/** + * Obtain the `select()` sets for this daemon. + * Daemon's FDs will be added to fd_sets. To get only + * daemon FDs in fd_sets, call FD_ZERO for each fd_set + * before calling this function. + * + * Passing custom FD_SETSIZE as @a fd_setsize allow usage of + * larger/smaller than platform's default fd_sets. + * + * This function should only be called in when MHD is configured to + * use external select with @code{select()} or with @code{epoll()}. + * In the latter case, it will only add the single @code{epoll()} file + * descriptor used by MHD to the sets. + * + * This function must be called only for daemon started + * without #MHD_USE_INTERNAL_POLLING_THREAD flag. + * + * @param daemon daemon to get sets from + * @param read_fd_set read set + * @param write_fd_set write set + * @param except_fd_set except set + * @param max_fd increased to largest FD added (if larger + * than existing value); can be NULL + * @param fd_setsize value of FD_SETSIZE + * @return #MHD_YES on success, #MHD_NO if this + * daemon was not started with the right + * options for this call or any FD didn't + * fit fd_set. + * @ingroup event + */ +_MHD_EXTERN int +MHD_get_fdset2 (struct MHD_Daemon *daemon, + fd_set *read_fd_set, + fd_set *write_fd_set, + fd_set *except_fd_set, + MHD_socket *max_fd, + unsigned int fd_setsize); + + +/** + * Obtain the `select()` sets for this daemon. + * Daemon's FDs will be added to fd_sets. To get only + * daemon FDs in fd_sets, call FD_ZERO for each fd_set + * before calling this function. Size of fd_set is + * determined by current value of FD_SETSIZE. + * + * This function could be called only for daemon started + * without #MHD_USE_INTERNAL_POLLING_THREAD flag. + * + * @param daemon daemon to get sets from + * @param read_fd_set read set + * @param write_fd_set write set + * @param except_fd_set except set + * @param max_fd increased to largest FD added (if larger + * than existing value); can be NULL + * @return #MHD_YES on success, #MHD_NO if this + * daemon was not started with the right + * options for this call or any FD didn't + * fit fd_set. + * @ingroup event + */ +#define MHD_get_fdset(daemon,read_fd_set,write_fd_set,except_fd_set,max_fd) \ + MHD_get_fdset2((daemon),(read_fd_set),(write_fd_set),(except_fd_set),(max_fd),FD_SETSIZE) + + +/** + * Obtain timeout value for `select()` for this daemon (only needed if + * connection timeout is used). The returned value is how many milliseconds + * `select()` or `poll()` should at most block, not the timeout value set for + * connections. This function MUST NOT be called if MHD is running with + * #MHD_USE_THREAD_PER_CONNECTION. + * + * @param daemon daemon to query for timeout + * @param timeout set to the timeout (in milliseconds) + * @return #MHD_YES on success, #MHD_NO if timeouts are + * not used (or no connections exist that would + * necessiate the use of a timeout right now). + * @ingroup event + */ +_MHD_EXTERN int +MHD_get_timeout (struct MHD_Daemon *daemon, + MHD_UNSIGNED_LONG_LONG *timeout); + + +/** + * Run webserver operations (without blocking unless in client + * callbacks). This method should be called by clients in combination + * with #MHD_get_fdset if the client-controlled select method is used. + * + * This function is a convenience method, which is useful if the + * fd_sets from #MHD_get_fdset were not directly passed to `select()`; + * with this function, MHD will internally do the appropriate `select()` + * call itself again. While it is always safe to call #MHD_run (if + * #MHD_USE_INTERNAL_POLLING_THREAD is not set), you should call + * #MHD_run_from_select if performance is important (as it saves an + * expensive call to `select()`). + * + * @param daemon daemon to run + * @return #MHD_YES on success, #MHD_NO if this + * daemon was not started with the right + * options for this call. + * @ingroup event + */ +_MHD_EXTERN int +MHD_run (struct MHD_Daemon *daemon); + + +/** + * Run webserver operations. This method should be called by clients + * in combination with #MHD_get_fdset if the client-controlled select + * method is used. + * + * You can use this function instead of #MHD_run if you called + * `select()` on the result from #MHD_get_fdset. File descriptors in + * the sets that are not controlled by MHD will be ignored. Calling + * this function instead of #MHD_run is more efficient as MHD will + * not have to call `select()` again to determine which operations are + * ready. + * + * This function cannot be used with daemon started with + * #MHD_USE_INTERNAL_POLLING_THREAD flag. + * + * @param daemon daemon to run select loop for + * @param read_fd_set read set + * @param write_fd_set write set + * @param except_fd_set except set + * @return #MHD_NO on serious errors, #MHD_YES on success + * @ingroup event + */ +_MHD_EXTERN int +MHD_run_from_select (struct MHD_Daemon *daemon, + const fd_set *read_fd_set, + const fd_set *write_fd_set, + const fd_set *except_fd_set); + + + + +/* **************** Connection handling functions ***************** */ + +/** + * Get all of the headers from the request. + * + * @param connection connection to get values from + * @param kind types of values to iterate over, can be a bitmask + * @param iterator callback to call on each header; + * maybe NULL (then just count headers) + * @param iterator_cls extra argument to @a iterator + * @return number of entries iterated over + * @ingroup request + */ +_MHD_EXTERN int +MHD_get_connection_values (struct MHD_Connection *connection, + enum MHD_ValueKind kind, + MHD_KeyValueIterator iterator, + void *iterator_cls); + + +/** + * This function can be used to add an entry to the HTTP headers of a + * connection (so that the #MHD_get_connection_values function will + * return them -- and the `struct MHD_PostProcessor` will also see + * them). This maybe required in certain situations (see Mantis + * #1399) where (broken) HTTP implementations fail to supply values + + * needed by the post processor (or other parts of the application). + * + * This function MUST only be called from within the + * #MHD_AccessHandlerCallback (otherwise, access maybe improperly + * synchronized). Furthermore, the client must guarantee that the key + * and value arguments are 0-terminated strings that are NOT freed + * until the connection is closed. (The easiest way to do this is by + * passing only arguments to permanently allocated strings.). + * + * @param connection the connection for which a + * value should be set + * @param kind kind of the value + * @param key key for the value + * @param value the value itself + * @return #MHD_NO if the operation could not be + * performed due to insufficient memory; + * #MHD_YES on success + * @ingroup request + */ +_MHD_EXTERN int +MHD_set_connection_value (struct MHD_Connection *connection, + enum MHD_ValueKind kind, + const char *key, + const char *value); + + +/** + * Sets the global error handler to a different implementation. @a cb + * will only be called in the case of typically fatal, serious + * internal consistency issues. These issues should only arise in the + * case of serious memory corruption or similar problems with the + * architecture. While @a cb is allowed to return and MHD will then + * try to continue, this is never safe. + * + * The default implementation that is used if no panic function is set + * simply prints an error message and calls `abort()`. Alternative + * implementations might call `exit()` or other similar functions. + * + * @param cb new error handler + * @param cls passed to @a cb + * @ingroup logging + */ +_MHD_EXTERN void +MHD_set_panic_func (MHD_PanicCallback cb, void *cls); + + +/** + * Process escape sequences ('%HH') Updates val in place; the + * result should be UTF-8 encoded and cannot be larger than the input. + * The result must also still be 0-terminated. + * + * @param val value to unescape (modified in the process) + * @return length of the resulting val (`strlen(val)` may be + * shorter afterwards due to elimination of escape sequences) + */ +_MHD_EXTERN size_t +MHD_http_unescape (char *val); + + +/** + * Get a particular header value. If multiple + * values match the kind, return any one of them. + * + * @param connection connection to get values from + * @param kind what kind of value are we looking for + * @param key the header to look for, NULL to lookup 'trailing' value without a key + * @return NULL if no such item was found + * @ingroup request + */ +_MHD_EXTERN const char * +MHD_lookup_connection_value (struct MHD_Connection *connection, + enum MHD_ValueKind kind, + const char *key); + + +/** + * Queue a response to be transmitted to the client (as soon as + * possible but after #MHD_AccessHandlerCallback returns). + * + * @param connection the connection identifying the client + * @param status_code HTTP status code (i.e. #MHD_HTTP_OK) + * @param response response to transmit + * @return #MHD_NO on error (i.e. reply already sent), + * #MHD_YES on success or if message has been queued + * @ingroup response + */ +_MHD_EXTERN int +MHD_queue_response (struct MHD_Connection *connection, + unsigned int status_code, + struct MHD_Response *response); + + +/** + * Suspend handling of network data for a given connection. This can + * be used to dequeue a connection from MHD's event loop for a while. + * + * If you use this API in conjunction with a internal select or a + * thread pool, you must set the option #MHD_USE_ITC to + * ensure that a resumed connection is immediately processed by MHD. + * + * Suspended connections continue to count against the total number of + * connections allowed (per daemon, as well as per IP, if such limits + * are set). Suspended connections will NOT time out; timeouts will + * restart when the connection handling is resumed. While a + * connection is suspended, MHD will not detect disconnects by the + * client. + * + * The only safe time to suspend a connection is from the + * #MHD_AccessHandlerCallback. + * + * Finally, it is an API violation to call #MHD_stop_daemon while + * having suspended connections (this will at least create memory and + * socket leaks or lead to undefined behavior). You must explicitly + * resume all connections before stopping the daemon. + * + * @param connection the connection to suspend + */ +_MHD_EXTERN void +MHD_suspend_connection (struct MHD_Connection *connection); + + +/** + * Resume handling of network data for suspended connection. It is + * safe to resume a suspended connection at any time. Calling this + * function on a connection that was not previously suspended will + * result in undefined behavior. + * + * If you are using this function in ``external'' select mode, you must + * make sure to run #MHD_run() afterwards (before again calling + * #MHD_get_fdset(), as otherwise the change may not be reflected in + * the set returned by #MHD_get_fdset() and you may end up with a + * connection that is stuck until the next network activity. + * + * @param connection the connection to resume + */ +_MHD_EXTERN void +MHD_resume_connection (struct MHD_Connection *connection); + + +/* **************** Response manipulation functions ***************** */ + + +/** + * Flags for special handling of responses. + */ +enum MHD_ResponseFlags +{ + /** + * Default: no special flags. + */ + MHD_RF_NONE = 0, + + /** + * Only respond in conservative HTTP 1.0-mode. In particular, + * do not (automatically) sent "Connection" headers and always + * close the connection after generating the response. + */ + MHD_RF_HTTP_VERSION_1_0_ONLY = 1 + +}; + + +/** + * MHD options (for future extensions). + */ +enum MHD_ResponseOptions +{ + /** + * End of the list of options. + */ + MHD_RO_END = 0 +}; + + +/** + * Set special flags and options for a response. + * + * @param response the response to modify + * @param flags to set for the response + * @param ... #MHD_RO_END terminated list of options + * @return #MHD_YES on success, #MHD_NO on error + */ +_MHD_EXTERN int +MHD_set_response_options (struct MHD_Response *response, + enum MHD_ResponseFlags flags, + ...); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response, #MHD_SIZE_UNKNOWN for unknown + * @param block_size preferred block size for querying crc (advisory only, + * MHD may still call @a crc using smaller chunks); this + * is essentially the buffer size used for IO, clients + * should pick a value that is appropriate for IO and + * memory performance requirements + * @param crc callback to use to obtain response data + * @param crc_cls extra argument to @a crc + * @param crfc callback to call to free @a crc_cls resources + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_callback (uint64_t size, + size_t block_size, + MHD_ContentReaderCallback crc, void *crc_cls, + MHD_ContentReaderFreeCallback crfc); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the @a data portion of the response + * @param data the data itself + * @param must_free libmicrohttpd should free data when done + * @param must_copy libmicrohttpd must make a copy of @a data + * right away, the data maybe released anytime after + * this call returns + * @return NULL on error (i.e. invalid arguments, out of memory) + * @deprecated use #MHD_create_response_from_buffer instead + * @ingroup response + */ +_MHD_DEPR_FUNC("MHD_create_response_from_data() is deprecated, use MHD_create_response_from_buffer()") \ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_data (size_t size, + void *data, + int must_free, + int must_copy); + + +/** + * Specification for how MHD should treat the memory buffer + * given for the response. + * @ingroup response + */ +enum MHD_ResponseMemoryMode +{ + + /** + * Buffer is a persistent (static/global) buffer that won't change + * for at least the lifetime of the response, MHD should just use + * it, not free it, not copy it, just keep an alias to it. + * @ingroup response + */ + MHD_RESPMEM_PERSISTENT, + + /** + * Buffer is heap-allocated with `malloc()` (or equivalent) and + * should be freed by MHD after processing the response has + * concluded (response reference counter reaches zero). + * @ingroup response + */ + MHD_RESPMEM_MUST_FREE, + + /** + * Buffer is in transient memory, but not on the heap (for example, + * on the stack or non-`malloc()` allocated) and only valid during the + * call to #MHD_create_response_from_buffer. MHD must make its + * own private copy of the data for processing. + * @ingroup response + */ + MHD_RESPMEM_MUST_COPY + +}; + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response + * @param buffer size bytes containing the response's data portion + * @param mode flags for buffer management + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_buffer (size_t size, + void *buffer, + enum MHD_ResponseMemoryMode mode); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response + * @param fd file descriptor referring to a file on disk with the + * data; will be closed when response is destroyed; + * fd should be in 'blocking' mode + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_fd (size_t size, + int fd); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response; + * sizes larger than 2 GiB may be not supported by OS or + * MHD build; see ::MHD_FEATURE_LARGE_FILE + * @param fd file descriptor referring to a file on disk with the + * data; will be closed when response is destroyed; + * fd should be in 'blocking' mode + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_fd64 (uint64_t size, + int fd); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response + * @param fd file descriptor referring to a file on disk with the + * data; will be closed when response is destroyed; + * fd should be in 'blocking' mode + * @param offset offset to start reading from in the file; + * Be careful! `off_t` may have been compiled to be a + * 64-bit variable for MHD, in which case your application + * also has to be compiled using the same options! Read + * the MHD manual for more details. + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_DEPR_FUNC("Function MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()") \ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_fd_at_offset (size_t size, + int fd, + off_t offset); + +#if !defined(_MHD_NO_DEPR_IN_MACRO) || defined(_MHD_NO_DEPR_FUNC) +/* Substitute MHD_create_response_from_fd_at_offset64() instead of MHD_create_response_from_fd_at_offset() + to minimize potential problems with different off_t sizes */ +#define MHD_create_response_from_fd_at_offset(size,fd,offset) \ + _MHD_DEPR_IN_MACRO("Usage of MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()") \ + MHD_create_response_from_fd_at_offset64((size),(fd),(offset)) +#endif /* !_MHD_NO_DEPR_IN_MACRO || _MHD_NO_DEPR_FUNC */ + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response; + * sizes larger than 2 GiB may be not supported by OS or + * MHD build; see ::MHD_FEATURE_LARGE_FILE + * @param fd file descriptor referring to a file on disk with the + * data; will be closed when response is destroyed; + * fd should be in 'blocking' mode + * @param offset offset to start reading from in the file; + * reading file beyond 2 GiB may be not supported by OS or + * MHD build; see ::MHD_FEATURE_LARGE_FILE + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_fd_at_offset64 (uint64_t size, + int fd, + uint64_t offset); + + +/** + * Enumeration for actions MHD should perform on the underlying socket + * of the upgrade. This API is not finalized, and in particular + * the final set of actions is yet to be decided. This is just an + * idea for what we might want. + */ +enum MHD_UpgradeAction +{ + + /** + * Close the socket, the application is done with it. + * + * Takes no extra arguments. + */ + MHD_UPGRADE_ACTION_CLOSE = 0 + +}; + + +/** + * Handle given to the application to manage special + * actions relating to MHD responses that "upgrade" + * the HTTP protocol (i.e. to WebSockets). + */ +struct MHD_UpgradeResponseHandle; + + +/** + * This connection-specific callback is provided by MHD to + * applications (unusual) during the #MHD_UpgradeHandler. + * It allows applications to perform 'special' actions on + * the underlying socket from the upgrade. + * + * @param urh the handle identifying the connection to perform + * the upgrade @a action on. + * @param action which action should be performed + * @param ... arguments to the action (depends on the action) + * @return #MHD_NO on error, #MHD_YES on success + */ +_MHD_EXTERN int +MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh, + enum MHD_UpgradeAction action, + ...); + + +/** + * Function called after a protocol "upgrade" response was sent + * successfully and the socket should now be controlled by some + * protocol other than HTTP. + * + * Any data already received on the socket will be made available in + * @e extra_in. This can happen if the application sent extra data + * before MHD send the upgrade response. The application should + * treat data from @a extra_in as if it had read it from the socket. + * + * Note that the application must not close() @a sock directly, + * but instead use #MHD_upgrade_action() for special operations + * on @a sock. + * + * Data forwarding to "upgraded" @a sock will be started as soon + * as this function return. + * + * Except when in 'thread-per-connection' mode, implementations + * of this function should never block (as it will still be called + * from within the main event loop). + * + * @param cls closure, whatever was given to #MHD_create_response_for_upgrade(). + * @param connection original HTTP connection handle, + * giving the function a last chance + * to inspect the original HTTP request + * @param con_cls last value left in `con_cls` of the `MHD_AccessHandlerCallback` + * @param extra_in if we happened to have read bytes after the + * HTTP header already (because the client sent + * more than the HTTP header of the request before + * we sent the upgrade response), + * these are the extra bytes already read from @a sock + * by MHD. The application should treat these as if + * it had read them from @a sock. + * @param extra_in_size number of bytes in @a extra_in + * @param sock socket to use for bi-directional communication + * with the client. For HTTPS, this may not be a socket + * that is directly connected to the client and thus certain + * operations (TCP-specific setsockopt(), getsockopt(), etc.) + * may not work as expected (as the socket could be from a + * socketpair() or a TCP-loopback). The application is expected + * to perform read()/recv() and write()/send() calls on the socket. + * The application may also call shutdown(), but must not call + * close() directly. + * @param urh argument for #MHD_upgrade_action()s on this @a connection. + * Applications must eventually use this callback to (indirectly) + * perform the close() action on the @a sock. + */ +typedef void +(*MHD_UpgradeHandler)(void *cls, + struct MHD_Connection *connection, + void *con_cls, + const char *extra_in, + size_t extra_in_size, + MHD_socket sock, + struct MHD_UpgradeResponseHandle *urh); + + +/** + * Create a response object that can be used for 101 UPGRADE + * responses, for example to implement WebSockets. After sending the + * response, control over the data stream is given to the callback (which + * can then, for example, start some bi-directional communication). + * If the response is queued for multiple connections, the callback + * will be called for each connection. The callback + * will ONLY be called after the response header was successfully passed + * to the OS; if there are communication errors before, the usual MHD + * connection error handling code will be performed. + * + * Setting the correct HTTP code (i.e. MHD_HTTP_SWITCHING_PROTOCOLS) + * and setting correct HTTP headers for the upgrade must be done + * manually (this way, it is possible to implement most existing + * WebSocket versions using this API; in fact, this API might be useful + * for any protocol switch, not just WebSockets). Note that + * draft-ietf-hybi-thewebsocketprotocol-00 cannot be implemented this + * way as the header "HTTP/1.1 101 WebSocket Protocol Handshake" + * cannot be generated; instead, MHD will always produce "HTTP/1.1 101 + * Switching Protocols" (if the response code 101 is used). + * + * As usual, the response object can be extended with header + * information and then be used any number of times (as long as the + * header information is not connection-specific). + * + * @param upgrade_handler function to call with the "upgraded" socket + * @param upgrade_handler_cls closure for @a upgrade_handler + * @return NULL on error (i.e. invalid arguments, out of memory) + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler, + void *upgrade_handler_cls); + + +/** + * Destroy a response object and associated resources. Note that + * libmicrohttpd may keep some of the resources around if the response + * is still in the queue for some clients, so the memory may not + * necessarily be freed immediatley. + * + * @param response response to destroy + * @ingroup response + */ +_MHD_EXTERN void +MHD_destroy_response (struct MHD_Response *response); + + +/** + * Add a header line to the response. + * + * @param response response to add a header to + * @param header the header to add + * @param content value to add + * @return #MHD_NO on error (i.e. invalid header or content format), + * or out of memory + * @ingroup response + */ +_MHD_EXTERN int +MHD_add_response_header (struct MHD_Response *response, + const char *header, + const char *content); + + +/** + * Add a footer line to the response. + * + * @param response response to remove a header from + * @param footer the footer to delete + * @param content value to delete + * @return #MHD_NO on error (i.e. invalid footer or content format). + * @ingroup response + */ +_MHD_EXTERN int +MHD_add_response_footer (struct MHD_Response *response, + const char *footer, + const char *content); + + +/** + * Delete a header (or footer) line from the response. + * + * @param response response to remove a header from + * @param header the header to delete + * @param content value to delete + * @return #MHD_NO on error (no such header known) + * @ingroup response + */ +_MHD_EXTERN int +MHD_del_response_header (struct MHD_Response *response, + const char *header, + const char *content); + + +/** + * Get all of the headers (and footers) added to a response. + * + * @param response response to query + * @param iterator callback to call on each header; + * maybe NULL (then just count headers) + * @param iterator_cls extra argument to @a iterator + * @return number of entries iterated over + * @ingroup response + */ +_MHD_EXTERN int +MHD_get_response_headers (struct MHD_Response *response, + MHD_KeyValueIterator iterator, void *iterator_cls); + + +/** + * Get a particular header (or footer) from the response. + * + * @param response response to query + * @param key which header to get + * @return NULL if header does not exist + * @ingroup response + */ +_MHD_EXTERN const char * +MHD_get_response_header (struct MHD_Response *response, + const char *key); + + +/* ********************** PostProcessor functions ********************** */ + +/** + * Create a `struct MHD_PostProcessor`. + * + * A `struct MHD_PostProcessor` can be used to (incrementally) parse + * the data portion of a POST request. Note that some buggy browsers + * fail to set the encoding type. If you want to support those, you + * may have to call #MHD_set_connection_value with the proper encoding + * type before creating a post processor (if no supported encoding + * type is set, this function will fail). + * + * @param connection the connection on which the POST is + * happening (used to determine the POST format) + * @param buffer_size maximum number of bytes to use for + * internal buffering (used only for the parsing, + * specifically the parsing of the keys). A + * tiny value (256-1024) should be sufficient. + * Do NOT use a value smaller than 256. For good + * performance, use 32 or 64k (i.e. 65536). + * @param iter iterator to be called with the parsed data, + * Must NOT be NULL. + * @param iter_cls first argument to @a iter + * @return NULL on error (out of memory, unsupported encoding), + * otherwise a PP handle + * @ingroup request + */ +_MHD_EXTERN struct MHD_PostProcessor * +MHD_create_post_processor (struct MHD_Connection *connection, + size_t buffer_size, + MHD_PostDataIterator iter, void *iter_cls); + + +/** + * Parse and process POST data. Call this function when POST data is + * available (usually during an #MHD_AccessHandlerCallback) with the + * "upload_data" and "upload_data_size". Whenever possible, this will + * then cause calls to the #MHD_PostDataIterator. + * + * @param pp the post processor + * @param post_data @a post_data_len bytes of POST data + * @param post_data_len length of @a post_data + * @return #MHD_YES on success, #MHD_NO on error + * (out-of-memory, iterator aborted, parse error) + * @ingroup request + */ +_MHD_EXTERN int +MHD_post_process (struct MHD_PostProcessor *pp, + const char *post_data, size_t post_data_len); + + +/** + * Release PostProcessor resources. + * + * @param pp the PostProcessor to destroy + * @return #MHD_YES if processing completed nicely, + * #MHD_NO if there were spurious characters / formatting + * problems; it is common to ignore the return + * value of this function + * @ingroup request + */ +_MHD_EXTERN int +MHD_destroy_post_processor (struct MHD_PostProcessor *pp); + + +/* ********************* Digest Authentication functions *************** */ + + +/** + * Constant to indicate that the nonce of the provided + * authentication code was wrong. + * @ingroup authentication + */ +#define MHD_INVALID_NONCE -1 + + +/** + * Get the username from the authorization header sent by the client + * + * @param connection The MHD connection structure + * @return NULL if no username could be found, a pointer + * to the username if found + * @ingroup authentication + */ +_MHD_EXTERN char * +MHD_digest_auth_get_username (struct MHD_Connection *connection); + + +/** + * Authenticates the authorization header sent by the client + * + * @param connection The MHD connection structure + * @param realm The realm presented to the client + * @param username The username needs to be authenticated + * @param password The password used in the authentication + * @param nonce_timeout The amount of time for a nonce to be + * invalid in seconds + * @return #MHD_YES if authenticated, #MHD_NO if not, + * #MHD_INVALID_NONCE if nonce is invalid + * @ingroup authentication + */ +_MHD_EXTERN int +MHD_digest_auth_check (struct MHD_Connection *connection, + const char *realm, + const char *username, + const char *password, + unsigned int nonce_timeout); + + +/** + * Queues a response to request authentication from the client + * + * @param connection The MHD connection structure + * @param realm The realm presented to the client + * @param opaque string to user for opaque value + * @param response reply to send; should contain the "access denied" + * body; note that this function will set the "WWW Authenticate" + * header and that the caller should not do this + * @param signal_stale #MHD_YES if the nonce is invalid to add + * 'stale=true' to the authentication header + * @return #MHD_YES on success, #MHD_NO otherwise + * @ingroup authentication + */ +_MHD_EXTERN int +MHD_queue_auth_fail_response (struct MHD_Connection *connection, + const char *realm, + const char *opaque, + struct MHD_Response *response, + int signal_stale); + + +/** + * Get the username and password from the basic authorization header sent by the client + * + * @param connection The MHD connection structure + * @param password a pointer for the password + * @return NULL if no username could be found, a pointer + * to the username if found + * @ingroup authentication + */ +_MHD_EXTERN char * +MHD_basic_auth_get_username_password (struct MHD_Connection *connection, + char** password); + + +/** + * Queues a response to request basic authentication from the client + * The given response object is expected to include the payload for + * the response; the "WWW-Authenticate" header will be added and the + * response queued with the 'UNAUTHORIZED' status code. + * + * @param connection The MHD connection structure + * @param realm the realm presented to the client + * @param response response object to modify and queue + * @return #MHD_YES on success, #MHD_NO otherwise + * @ingroup authentication + */ +_MHD_EXTERN int +MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, + const char *realm, + struct MHD_Response *response); + +/* ********************** generic query functions ********************** */ + + +/** + * Obtain information about the given connection. + * + * @param connection what connection to get information about + * @param info_type what information is desired? + * @param ... depends on @a info_type + * @return NULL if this information is not available + * (or if the @a info_type is unknown) + * @ingroup specialized + */ +_MHD_EXTERN const union MHD_ConnectionInfo * +MHD_get_connection_info (struct MHD_Connection *connection, + enum MHD_ConnectionInfoType info_type, + ...); + + +/** + * MHD connection options. Given to #MHD_set_connection_option to + * set custom options for a particular connection. + */ +enum MHD_CONNECTION_OPTION +{ + + /** + * Set a custom timeout for the given connection. Specified + * as the number of seconds, given as an `unsigned int`. Use + * zero for no timeout. + * If timeout was set to zero (or unset) before, setup of new value by + * MHD_set_connection_option() will reset timeout timer. + */ + MHD_CONNECTION_OPTION_TIMEOUT + +}; + + +/** + * Set a custom option for the given connection, overriding defaults. + * + * @param connection connection to modify + * @param option option to set + * @param ... arguments to the option, depending on the option type + * @return #MHD_YES on success, #MHD_NO if setting the option failed + * @ingroup specialized + */ +_MHD_EXTERN int +MHD_set_connection_option (struct MHD_Connection *connection, + enum MHD_CONNECTION_OPTION option, + ...); + + +/** + * Information about an MHD daemon. + */ +union MHD_DaemonInfo +{ + /** + * Size of the key, no longer supported. + * @deprecated + */ + size_t key_size; + + /** + * Size of the mac key, no longer supported. + * @deprecated + */ + size_t mac_key_size; + + /** + * Socket, returned for #MHD_DAEMON_INFO_LISTEN_FD. + */ + MHD_socket listen_fd; + + /** + * epoll FD, returned for #MHD_DAEMON_INFO_EPOLL_FD. + */ + int epoll_fd; + + /** + * Number of active connections, for #MHD_DAEMON_INFO_CURRENT_CONNECTIONS. + */ + unsigned int num_connections; + + /** + * Combination of #MHD_FLAG values, for #MHD_DAEMON_INFO_FLAGS. + * This value is actually a bitfield. + * Note: flags may differ from original 'flags' specified for + * daemon, especially if #MHD_USE_AUTO was set. + */ + enum MHD_FLAG flags; +}; + + +/** + * Obtain information about the given daemon + * (not fully implemented!). + * + * @param daemon what daemon to get information about + * @param info_type what information is desired? + * @param ... depends on @a info_type + * @return NULL if this information is not available + * (or if the @a info_type is unknown) + * @ingroup specialized + */ +_MHD_EXTERN const union MHD_DaemonInfo * +MHD_get_daemon_info (struct MHD_Daemon *daemon, + enum MHD_DaemonInfoType info_type, + ...); + + +/** + * Obtain the version of this library + * + * @return static version string, e.g. "0.9.9" + * @ingroup specialized + */ +_MHD_EXTERN const char* +MHD_get_version (void); + + +/** + * Types of information about MHD features, + * used by #MHD_is_feature_supported(). + */ +enum MHD_FEATURE +{ + /** + * Get whether messages are supported. If supported then in debug + * mode messages can be printed to stderr or to external logger. + */ + MHD_FEATURE_MESSAGES = 1, + + /** + * Get whether HTTPS is supported. If supported then flag + * #MHD_USE_TLS and options #MHD_OPTION_HTTPS_MEM_KEY, + * #MHD_OPTION_HTTPS_MEM_CERT, #MHD_OPTION_HTTPS_MEM_TRUST, + * #MHD_OPTION_HTTPS_MEM_DHPARAMS, #MHD_OPTION_HTTPS_CRED_TYPE, + * #MHD_OPTION_HTTPS_PRIORITIES can be used. + */ + MHD_FEATURE_TLS = 2, + MHD_FEATURE_SSL = 2, + + /** + * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK is + * supported. + */ + MHD_FEATURE_HTTPS_CERT_CALLBACK = 3, + + /** + * Get whether IPv6 is supported. If supported then flag + * #MHD_USE_IPv6 can be used. + */ + MHD_FEATURE_IPv6 = 4, + + /** + * Get whether IPv6 without IPv4 is supported. If not supported + * then IPv4 is always enabled in IPv6 sockets and + * flag #MHD_USE_DUAL_STACK if always used when #MHD_USE_IPv6 is + * specified. + */ + MHD_FEATURE_IPv6_ONLY = 5, + + /** + * Get whether `poll()` is supported. If supported then flag + * #MHD_USE_POLL can be used. + */ + MHD_FEATURE_POLL = 6, + + /** + * Get whether `epoll()` is supported. If supported then Flags + * #MHD_USE_EPOLL and + * #MHD_USE_EPOLL_INTERNAL_THREAD can be used. + */ + MHD_FEATURE_EPOLL = 7, + + /** + * Get whether shutdown on listen socket to signal other + * threads is supported. If not supported flag + * #MHD_USE_ITC is automatically forced. + */ + MHD_FEATURE_SHUTDOWN_LISTEN_SOCKET = 8, + + /** + * Get whether socketpair is used internally instead of pipe to + * signal other threads. + */ + MHD_FEATURE_SOCKETPAIR = 9, + + /** + * Get whether TCP Fast Open is supported. If supported then + * flag #MHD_USE_TCP_FASTOPEN and option + * #MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE can be used. + */ + MHD_FEATURE_TCP_FASTOPEN = 10, + + /** + * Get whether HTTP Basic authorization is supported. If supported + * then functions #MHD_basic_auth_get_username_password and + * #MHD_queue_basic_auth_fail_response can be used. + */ + MHD_FEATURE_BASIC_AUTH = 11, + + /** + * Get whether HTTP Digest authorization is supported. If + * supported then options #MHD_OPTION_DIGEST_AUTH_RANDOM, + * #MHD_OPTION_NONCE_NC_SIZE and + * #MHD_digest_auth_check() can be used. + */ + MHD_FEATURE_DIGEST_AUTH = 12, + + /** + * Get whether postprocessor is supported. If supported then + * functions #MHD_create_post_processor(), #MHD_post_process() and + * #MHD_destroy_post_processor() can + * be used. + */ + MHD_FEATURE_POSTPROCESSOR = 13, + + /** + * Get whether password encrypted private key for HTTPS daemon is + * supported. If supported then option + * ::MHD_OPTION_HTTPS_KEY_PASSWORD can be used. + */ + MHD_FEATURE_HTTPS_KEY_PASSWORD = 14, + + /** + * Get whether reading files beyond 2 GiB boundary is supported. + * If supported then #MHD_create_response_from_fd(), + * #MHD_create_response_from_fd64 #MHD_create_response_from_fd_at_offset() + * and #MHD_create_response_from_fd_at_offset64() can be used with sizes and + * offsets larger than 2 GiB. If not supported value of size+offset is + * limited to 2 GiB. + */ + MHD_FEATURE_LARGE_FILE = 15, + + /** + * Get whether MHD set names on generated threads. + */ + MHD_FEATURE_THREAD_NAMES = 16, + MHD_THREAD_NAMES = 16, + + /** + * Get whether HTTP "Upgrade" is supported. + * If supported then #MHD_ALLOW_UPGRADE, #MHD_upgrade_action() and + * #MHD_create_response_for_upgrade() can be used. + */ + MHD_FEATURE_UPGRADE = 17, + + /** + * Get whether it's safe to use same FD for multiple calls of + * #MHD_create_response_from_fd() and whether it's safe to use single + * response generated by #MHD_create_response_from_fd() with multiple + * connections at same time. + * If #MHD_is_feature_supported() return #MHD_NO for this feature then + * usage of responses with same file FD in multiple parallel threads may + * results in incorrect data sent to remote client. + * It's always safe to use same file FD in multiple responses if MHD + * is run in any single thread mode. + */ + MHD_FEATURE_RESPONSES_SHARED_FD = 18 +}; + + +/** + * Get information about supported MHD features. + * Indicate that MHD was compiled with or without support for + * particular feature. Some features require additional support + * by kernel. Kernel support is not checked by this function. + * + * @param feature type of requested information + * @return #MHD_YES if feature is supported by MHD, #MHD_NO if + * feature is not supported or feature is unknown. + * @ingroup specialized + */ +_MHD_EXTERN int +MHD_is_feature_supported (enum MHD_FEATURE feature); + + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +#endif diff --git a/microhttpd/0.9.55/AIX-00FB437F4C00/libmicrohttpd.a.12 b/microhttpd/0.9.55/AIX-00FB437F4C00/libmicrohttpd.a.12 new file mode 100755 index 0000000000000000000000000000000000000000..335090c9ec4857e2bebd58e8fc35c201bcf7b027 Binary files /dev/null and b/microhttpd/0.9.55/AIX-00FB437F4C00/libmicrohttpd.a.12 differ diff --git a/microhttpd/0.9.55/Linux-x86_64/include/microhttpd.h b/microhttpd/0.9.55/Linux-x86_64/include/microhttpd.h new file mode 100755 index 0000000000000000000000000000000000000000..40a723d6b5c3e0355b41575f27edbb76675a0c7a --- /dev/null +++ b/microhttpd/0.9.55/Linux-x86_64/include/microhttpd.h @@ -0,0 +1,3456 @@ +/* + This file is part of libmicrohttpd + Copyright (C) 2006-2017 Christian Grothoff (and other contributing authors) + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public + License along with this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA +*/ + +/** + * @file microhttpd.h + * @brief public interface to libmicrohttpd + * @author Christian Grothoff + * @author Karlson2k (Evgeny Grin) + * @author Chris GauthierDickey + * + * All symbols defined in this header start with MHD. MHD is a small + * HTTP daemon library. As such, it does not have any API for logging + * errors (you can only enable or disable logging to stderr). Also, + * it may not support all of the HTTP features directly, where + * applicable, portions of HTTP may have to be handled by clients of + * the library. + * + * The library is supposed to handle everything that it must handle + * (because the API would not allow clients to do this), such as basic + * connection management; however, detailed interpretations of headers + * -- such as range requests -- and HTTP methods are left to clients. + * The library does understand HEAD and will only send the headers of + * the response and not the body, even if the client supplied a body. + * The library also understands headers that control connection + * management (specifically, "Connection: close" and "Expect: 100 + * continue" are understood and handled automatically). + * + * MHD understands POST data and is able to decode certain formats + * (at the moment only "application/x-www-form-urlencoded" and + * "mulitpart/formdata"). Unsupported encodings and large POST + * submissions may require the application to manually process + * the stream, which is provided to the main application (and thus can be + * processed, just not conveniently by MHD). + * + * The header file defines various constants used by the HTTP protocol. + * This does not mean that MHD actually interprets all of these + * values. The provided constants are exported as a convenience + * for users of the library. MHD does not verify that transmitted + * HTTP headers are part of the standard specification; users of the + * library are free to define their own extensions of the HTTP + * standard and use those with MHD. + * + * All functions are guaranteed to be completely reentrant and + * thread-safe (with the exception of #MHD_set_connection_value, + * which must only be used in a particular context). + * + * + * @defgroup event event-loop control + * MHD API to start and stop the HTTP server and manage the event loop. + * @defgroup response generation of responses + * MHD API used to generate responses. + * @defgroup request handling of requests + * MHD API used to access information about requests. + * @defgroup authentication HTTP authentication + * MHD API related to basic and digest HTTP authentication. + * @defgroup logging logging + * MHD API to mange logging and error handling + * @defgroup specialized misc. specialized functions + * This group includes functions that do not fit into any particular + * category and that are rarely used. + */ + +#ifndef MHD_MICROHTTPD_H +#define MHD_MICROHTTPD_H + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +/* While we generally would like users to use a configure-driven + build process which detects which headers are present and + hence works on any platform, we use "standard" includes here + to build out-of-the-box for beginning users on common systems. + + If generic headers don't work on your platform, include headers + which define 'va_list', 'size_t', 'ssize_t', 'intptr_t', + 'uint16_t', 'uint32_t', 'uint64_t', 'off_t', 'struct sockaddr', + 'socklen_t', 'fd_set' and "#define MHD_PLATFORM_H" before + including "microhttpd.h". Then the following "standard" + includes won't be used (which might be a good idea, especially + on platforms where they do not exist). + */ +#ifndef MHD_PLATFORM_H +#include +#include +#include +#if defined(_WIN32) && !defined(__CYGWIN__) +#include +#if defined(_MSC_FULL_VER) && !defined (_SSIZE_T_DEFINED) +#define _SSIZE_T_DEFINED +typedef intptr_t ssize_t; +#endif /* !_SSIZE_T_DEFINED */ +#else +#include +#include +#include +#endif +#endif + +#if defined(__CYGWIN__) && !defined(_SYS_TYPES_FD_SET) +/* Do not define __USE_W32_SOCKETS under Cygwin! */ +#error Cygwin with winsock fd_set is not supported +#endif + +/** + * Current version of the library. + * 0x01093001 = 1.9.30-1. + */ +#define MHD_VERSION 0x00095500 + +/** + * MHD-internal return code for "YES". + */ +#define MHD_YES 1 + +/** + * MHD-internal return code for "NO". + */ +#define MHD_NO 0 + +/** + * MHD digest auth internal code for an invalid nonce. + */ +#define MHD_INVALID_NONCE -1 + +/** + * Constant used to indicate unknown size (use when + * creating a response). + */ +#ifdef UINT64_MAX +#define MHD_SIZE_UNKNOWN UINT64_MAX +#else +#define MHD_SIZE_UNKNOWN ((uint64_t) -1LL) +#endif + +#ifdef SIZE_MAX +#define MHD_CONTENT_READER_END_OF_STREAM SIZE_MAX +#define MHD_CONTENT_READER_END_WITH_ERROR (SIZE_MAX - 1) +#else +#define MHD_CONTENT_READER_END_OF_STREAM ((size_t) -1LL) +#define MHD_CONTENT_READER_END_WITH_ERROR (((size_t) -1LL) - 1) +#endif + +#ifndef _MHD_EXTERN +#if defined(_WIN32) && defined(MHD_W32LIB) +#define _MHD_EXTERN extern +#elif defined (_WIN32) && defined(MHD_W32DLL) +/* Define MHD_W32DLL when using MHD as W32 .DLL to speed up linker a little */ +#define _MHD_EXTERN __declspec(dllimport) +#else +#define _MHD_EXTERN extern +#endif +#endif + +#ifndef MHD_SOCKET_DEFINED +/** + * MHD_socket is type for socket FDs + */ +#if !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) +#define MHD_POSIX_SOCKETS 1 +typedef int MHD_socket; +#define MHD_INVALID_SOCKET (-1) +#else /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ +#define MHD_WINSOCK_SOCKETS 1 +#include +typedef SOCKET MHD_socket; +#define MHD_INVALID_SOCKET (INVALID_SOCKET) +#endif /* !defined(_WIN32) || defined(_SYS_TYPES_FD_SET) */ +#define MHD_SOCKET_DEFINED 1 +#endif /* MHD_SOCKET_DEFINED */ + +/** + * Define MHD_NO_DEPRECATION before including "microhttpd.h" to disable deprecation messages + */ +#ifdef MHD_NO_DEPRECATION +#define _MHD_DEPR_MACRO(msg) +#define _MHD_NO_DEPR_IN_MACRO 1 +#define _MHD_DEPR_IN_MACRO(msg) +#define _MHD_NO_DEPR_FUNC 1 +#define _MHD_DEPR_FUNC(msg) +#endif /* MHD_NO_DEPRECATION */ + +#ifndef _MHD_DEPR_MACRO +#if defined(_MSC_FULL_VER) && _MSC_VER+0 >= 1500 +/* VS 2008 or later */ +/* Stringify macros */ +#define _MHD_INSTRMACRO(a) #a +#define _MHD_STRMACRO(a) _MHD_INSTRMACRO(a) +/* deprecation message */ +#define _MHD_DEPR_MACRO(msg) __pragma(message(__FILE__ "(" _MHD_STRMACRO(__LINE__)"): warning: " msg)) +#define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO(msg) +#elif defined(__clang__) || defined (__GNUC_PATCHLEVEL__) +/* clang or GCC since 3.0 */ +#define _MHD_GCC_PRAG(x) _Pragma (#x) +#if __clang_major__+0 >= 5 || \ + (!defined(__apple_build_version__) && (__clang_major__+0 > 3 || (__clang_major__+0 == 3 && __clang_minor__ >= 3))) || \ + __GNUC__+0 > 4 || (__GNUC__+0 == 4 && __GNUC_MINOR__+0 >= 8) +/* clang >= 3.3 (or XCode's clang >= 5.0) or + GCC >= 4.8 */ +#define _MHD_DEPR_MACRO(msg) _MHD_GCC_PRAG(GCC warning msg) +#define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO(msg) +#else /* older clang or GCC */ +/* clang < 3.3, XCode's clang < 5.0, 3.0 <= GCC < 4.8 */ +#define _MHD_DEPR_MACRO(msg) _MHD_GCC_PRAG(message msg) +#if (__clang_major__+0 > 2 || (__clang_major__+0 == 2 && __clang_minor__ >= 9)) /* FIXME: clang >= 2.9, earlier versions not tested */ +/* clang handles inline pragmas better than GCC */ +#define _MHD_DEPR_IN_MACRO(msg) _MHD_DEPR_MACRO(msg) +#endif /* clang >= 2.9 */ +#endif /* older clang or GCC */ +/* #elif defined(SOMEMACRO) */ /* add compiler-specific macros here if required */ +#endif /* clang || GCC >= 3.0 */ +#endif /* !_MHD_DEPR_MACRO */ + +#ifndef _MHD_DEPR_MACRO +#define _MHD_DEPR_MACRO(msg) +#endif /* !_MHD_DEPR_MACRO */ + +#ifndef _MHD_DEPR_IN_MACRO +#define _MHD_NO_DEPR_IN_MACRO 1 +#define _MHD_DEPR_IN_MACRO(msg) +#endif /* !_MHD_DEPR_IN_MACRO */ + +#ifndef _MHD_DEPR_FUNC +#if defined(_MSC_FULL_VER) && _MSC_VER+0 >= 1400 +/* VS 2005 or later */ +#define _MHD_DEPR_FUNC(msg) __declspec(deprecated(msg)) +#elif defined(_MSC_FULL_VER) && _MSC_VER+0 >= 1310 +/* VS .NET 2003 deprecation do not support custom messages */ +#define _MHD_DEPR_FUNC(msg) __declspec(deprecated) +#elif (__GNUC__+0 >= 5) || (defined (__clang__) && \ + (__clang_major__+0 > 2 || (__clang_major__+0 == 2 && __clang_minor__ >= 9))) /* FIXME: earlier versions not tested */ +/* GCC >= 5.0 or clang >= 2.9 */ +#define _MHD_DEPR_FUNC(msg) __attribute__((deprecated(msg))) +#elif defined (__clang__) || __GNUC__+0 > 3 || (__GNUC__+0 == 3 && __GNUC_MINOR__+0 >= 1) +/* 3.1 <= GCC < 5.0 or clang < 2.9 */ +/* old GCC-style deprecation do not support custom messages */ +#define _MHD_DEPR_FUNC(msg) __attribute__((__deprecated__)) +/* #elif defined(SOMEMACRO) */ /* add compiler-specific macros here if required */ +#endif /* clang < 2.9 || GCC >= 3.1 */ +#endif /* !_MHD_DEPR_FUNC */ + +#ifndef _MHD_DEPR_FUNC +#define _MHD_NO_DEPR_FUNC 1 +#define _MHD_DEPR_FUNC(msg) +#endif /* !_MHD_DEPR_FUNC */ + +/** + * Not all architectures and `printf()`'s support the `long long` type. + * This gives the ability to replace `long long` with just a `long`, + * standard `int` or a `short`. + */ +#ifndef MHD_LONG_LONG +/** + * @deprecated use #MHD_UNSIGNED_LONG_LONG instead! + */ +#define MHD_LONG_LONG long long +#define MHD_UNSIGNED_LONG_LONG unsigned long long +#else /* MHD_LONG_LONG */ +_MHD_DEPR_MACRO("Macro MHD_LONG_LONG is deprecated, use MHD_UNSIGNED_LONG_LONG") +#endif +/** + * Format string for printing a variable of type #MHD_LONG_LONG. + * You should only redefine this if you also define #MHD_LONG_LONG. + */ +#ifndef MHD_LONG_LONG_PRINTF +/** + * @deprecated use #MHD_UNSIGNED_LONG_LONG_PRINTF instead! + */ +#define MHD_LONG_LONG_PRINTF "ll" +#define MHD_UNSIGNED_LONG_LONG_PRINTF "%llu" +#else /* MHD_LONG_LONG_PRINTF */ +_MHD_DEPR_MACRO("Macro MHD_LONG_LONG_PRINTF is deprecated, use MHD_UNSIGNED_LONG_LONG_PRINTF") +#endif + + +/** + * @defgroup httpcode HTTP response codes. + * These are the status codes defined for HTTP responses. + * @{ + */ +/* See http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml */ + +#define MHD_HTTP_CONTINUE 100 +#define MHD_HTTP_SWITCHING_PROTOCOLS 101 +#define MHD_HTTP_PROCESSING 102 + +#define MHD_HTTP_OK 200 +#define MHD_HTTP_CREATED 201 +#define MHD_HTTP_ACCEPTED 202 +#define MHD_HTTP_NON_AUTHORITATIVE_INFORMATION 203 +#define MHD_HTTP_NO_CONTENT 204 +#define MHD_HTTP_RESET_CONTENT 205 +#define MHD_HTTP_PARTIAL_CONTENT 206 +#define MHD_HTTP_MULTI_STATUS 207 +#define MHD_HTTP_ALREADY_REPORTED 208 + +#define MHD_HTTP_IM_USED 226 + +#define MHD_HTTP_MULTIPLE_CHOICES 300 +#define MHD_HTTP_MOVED_PERMANENTLY 301 +#define MHD_HTTP_FOUND 302 +#define MHD_HTTP_SEE_OTHER 303 +#define MHD_HTTP_NOT_MODIFIED 304 +#define MHD_HTTP_USE_PROXY 305 +#define MHD_HTTP_SWITCH_PROXY 306 +#define MHD_HTTP_TEMPORARY_REDIRECT 307 +#define MHD_HTTP_PERMANENT_REDIRECT 308 + +#define MHD_HTTP_BAD_REQUEST 400 +#define MHD_HTTP_UNAUTHORIZED 401 +#define MHD_HTTP_PAYMENT_REQUIRED 402 +#define MHD_HTTP_FORBIDDEN 403 +#define MHD_HTTP_NOT_FOUND 404 +#define MHD_HTTP_METHOD_NOT_ALLOWED 405 +#define MHD_HTTP_NOT_ACCEPTABLE 406 +/** @deprecated */ +#define MHD_HTTP_METHOD_NOT_ACCEPTABLE \ + _MHD_DEPR_IN_MACRO("Value MHD_HTTP_METHOD_NOT_ACCEPTABLE is deprecated, use MHD_HTTP_NOT_ACCEPTABLE") 406 +#define MHD_HTTP_PROXY_AUTHENTICATION_REQUIRED 407 +#define MHD_HTTP_REQUEST_TIMEOUT 408 +#define MHD_HTTP_CONFLICT 409 +#define MHD_HTTP_GONE 410 +#define MHD_HTTP_LENGTH_REQUIRED 411 +#define MHD_HTTP_PRECONDITION_FAILED 412 +#define MHD_HTTP_PAYLOAD_TOO_LARGE 413 +/** @deprecated */ +#define MHD_HTTP_REQUEST_ENTITY_TOO_LARGE \ + _MHD_DEPR_IN_MACRO("Value MHD_HTTP_REQUEST_ENTITY_TOO_LARGE is deprecated, use MHD_HTTP_PAYLOAD_TOO_LARGE") 413 +#define MHD_HTTP_URI_TOO_LONG 414 +/** @deprecated */ +#define MHD_HTTP_REQUEST_URI_TOO_LONG \ + _MHD_DEPR_IN_MACRO("Value MHD_HTTP_REQUEST_URI_TOO_LONG is deprecated, use MHD_HTTP_URI_TOO_LONG") 414 +#define MHD_HTTP_UNSUPPORTED_MEDIA_TYPE 415 +#define MHD_HTTP_RANGE_NOT_SATISFIABLE 416 +/** @deprecated */ +#define MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE \ + _MHD_DEPR_IN_MACRO("Value MHD_HTTP_REQUESTED_RANGE_NOT_SATISFIABLE is deprecated, use MHD_HTTP_RANGE_NOT_SATISFIABLE") 416 +#define MHD_HTTP_EXPECTATION_FAILED 417 + +#define MHD_HTTP_MISDIRECTED_REQUEST 421 +#define MHD_HTTP_UNPROCESSABLE_ENTITY 422 +#define MHD_HTTP_LOCKED 423 +#define MHD_HTTP_FAILED_DEPENDENCY 424 +#define MHD_HTTP_UNORDERED_COLLECTION 425 +#define MHD_HTTP_UPGRADE_REQUIRED 426 + +#define MHD_HTTP_PRECONDITION_REQUIRED 428 +#define MHD_HTTP_TOO_MANY_REQUESTS 429 +#define MHD_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE 431 + +#define MHD_HTTP_NO_RESPONSE 444 + +#define MHD_HTTP_RETRY_WITH 449 +#define MHD_HTTP_BLOCKED_BY_WINDOWS_PARENTAL_CONTROLS 450 +#define MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS 451 + +#define MHD_HTTP_INTERNAL_SERVER_ERROR 500 +#define MHD_HTTP_NOT_IMPLEMENTED 501 +#define MHD_HTTP_BAD_GATEWAY 502 +#define MHD_HTTP_SERVICE_UNAVAILABLE 503 +#define MHD_HTTP_GATEWAY_TIMEOUT 504 +#define MHD_HTTP_HTTP_VERSION_NOT_SUPPORTED 505 +#define MHD_HTTP_VARIANT_ALSO_NEGOTIATES 506 +#define MHD_HTTP_INSUFFICIENT_STORAGE 507 +#define MHD_HTTP_LOOP_DETECTED 508 +#define MHD_HTTP_BANDWIDTH_LIMIT_EXCEEDED 509 +#define MHD_HTTP_NOT_EXTENDED 510 +#define MHD_HTTP_NETWORK_AUTHENTICATION_REQUIRED 511 + +/** @} */ /* end of group httpcode */ + +/** + * Returns the string reason phrase for a response code. + * + * If we don't have a string for a status code, we give the first + * message in that status code class. + */ +_MHD_EXTERN const char * +MHD_get_reason_phrase_for (unsigned int code); + + +/** + * Flag to be or-ed with MHD_HTTP status code for + * SHOUTcast. This will cause the response to begin + * with the SHOUTcast "ICY" line instad of "HTTP". + * @ingroup specialized + */ +#define MHD_ICY_FLAG ((uint32_t)(((uint32_t)1) << 31)) + +/** + * @defgroup headers HTTP headers + * These are the standard headers found in HTTP requests and responses. + * See: http://www.iana.org/assignments/message-headers/message-headers.xml + * Registry Version 2017-01-27 + * @{ + */ + +/* Main HTTP headers. */ +/* Standard. RFC7231, Section 5.3.2 */ +#define MHD_HTTP_HEADER_ACCEPT "Accept" +/* Standard. RFC7231, Section 5.3.3 */ +#define MHD_HTTP_HEADER_ACCEPT_CHARSET "Accept-Charset" +/* Standard. RFC7231, Section 5.3.4; RFC7694, Section 3 */ +#define MHD_HTTP_HEADER_ACCEPT_ENCODING "Accept-Encoding" +/* Standard. RFC7231, Section 5.3.5 */ +#define MHD_HTTP_HEADER_ACCEPT_LANGUAGE "Accept-Language" +/* Standard. RFC7233, Section 2.3 */ +#define MHD_HTTP_HEADER_ACCEPT_RANGES "Accept-Ranges" +/* Standard. RFC7234, Section 5.1 */ +#define MHD_HTTP_HEADER_AGE "Age" +/* Standard. RFC7231, Section 7.4.1 */ +#define MHD_HTTP_HEADER_ALLOW "Allow" +/* Standard. RFC7235, Section 4.2 */ +#define MHD_HTTP_HEADER_AUTHORIZATION "Authorization" +/* Standard. RFC7234, Section 5.2 */ +#define MHD_HTTP_HEADER_CACHE_CONTROL "Cache-Control" +/* Reserved. RFC7230, Section 8.1 */ +#define MHD_HTTP_HEADER_CLOSE "Close" +/* Standard. RFC7230, Section 6.1 */ +#define MHD_HTTP_HEADER_CONNECTION "Connection" +/* Standard. RFC7231, Section 3.1.2.2 */ +#define MHD_HTTP_HEADER_CONTENT_ENCODING "Content-Encoding" +/* Standard. RFC7231, Section 3.1.3.2 */ +#define MHD_HTTP_HEADER_CONTENT_LANGUAGE "Content-Language" +/* Standard. RFC7230, Section 3.3.2 */ +#define MHD_HTTP_HEADER_CONTENT_LENGTH "Content-Length" +/* Standard. RFC7231, Section 3.1.4.2 */ +#define MHD_HTTP_HEADER_CONTENT_LOCATION "Content-Location" +/* Standard. RFC7233, Section 4.2 */ +#define MHD_HTTP_HEADER_CONTENT_RANGE "Content-Range" +/* Standard. RFC7231, Section 3.1.1.5 */ +#define MHD_HTTP_HEADER_CONTENT_TYPE "Content-Type" +/* Standard. RFC7231, Section 7.1.1.2 */ +#define MHD_HTTP_HEADER_DATE "Date" +/* Standard. RFC7232, Section 2.3 */ +#define MHD_HTTP_HEADER_ETAG "ETag" +/* Standard. RFC7231, Section 5.1.1 */ +#define MHD_HTTP_HEADER_EXPECT "Expect" +/* Standard. RFC7234, Section 5.3 */ +#define MHD_HTTP_HEADER_EXPIRES "Expires" +/* Standard. RFC7231, Section 5.5.1 */ +#define MHD_HTTP_HEADER_FROM "From" +/* Standard. RFC7230, Section 5.4 */ +#define MHD_HTTP_HEADER_HOST "Host" +/* Standard. RFC7232, Section 3.1 */ +#define MHD_HTTP_HEADER_IF_MATCH "If-Match" +/* Standard. RFC7232, Section 3.3 */ +#define MHD_HTTP_HEADER_IF_MODIFIED_SINCE "If-Modified-Since" +/* Standard. RFC7232, Section 3.2 */ +#define MHD_HTTP_HEADER_IF_NONE_MATCH "If-None-Match" +/* Standard. RFC7233, Section 3.2 */ +#define MHD_HTTP_HEADER_IF_RANGE "If-Range" +/* Standard. RFC7232, Section 3.4 */ +#define MHD_HTTP_HEADER_IF_UNMODIFIED_SINCE "If-Unmodified-Since" +/* Standard. RFC7232, Section 2.2 */ +#define MHD_HTTP_HEADER_LAST_MODIFIED "Last-Modified" +/* Standard. RFC7231, Section 7.1.2 */ +#define MHD_HTTP_HEADER_LOCATION "Location" +/* Standard. RFC7231, Section 5.1.2 */ +#define MHD_HTTP_HEADER_MAX_FORWARDS "Max-Forwards" +/* Standard. RFC7231, Appendix A.1 */ +#define MHD_HTTP_HEADER_MIME_VERSION "MIME-Version" +/* Standard. RFC7234, Section 5.4 */ +#define MHD_HTTP_HEADER_PRAGMA "Pragma" +/* Standard. RFC7235, Section 4.3 */ +#define MHD_HTTP_HEADER_PROXY_AUTHENTICATE "Proxy-Authenticate" +/* Standard. RFC7235, Section 4.4 */ +#define MHD_HTTP_HEADER_PROXY_AUTHORIZATION "Proxy-Authorization" +/* Standard. RFC7233, Section 3.1 */ +#define MHD_HTTP_HEADER_RANGE "Range" +/* Standard. RFC7231, Section 5.5.2 */ +#define MHD_HTTP_HEADER_REFERER "Referer" +/* Standard. RFC7231, Section 7.1.3 */ +#define MHD_HTTP_HEADER_RETRY_AFTER "Retry-After" +/* Standard. RFC7231, Section 7.4.2 */ +#define MHD_HTTP_HEADER_SERVER "Server" +/* Standard. RFC7230, Section 4.3 */ +#define MHD_HTTP_HEADER_TE "TE" +/* Standard. RFC7230, Section 4.4 */ +#define MHD_HTTP_HEADER_TRAILER "Trailer" +/* Standard. RFC7230, Section 3.3.1 */ +#define MHD_HTTP_HEADER_TRANSFER_ENCODING "Transfer-Encoding" +/* Standard. RFC7230, Section 6.7 */ +#define MHD_HTTP_HEADER_UPGRADE "Upgrade" +/* Standard. RFC7231, Section 5.5.3 */ +#define MHD_HTTP_HEADER_USER_AGENT "User-Agent" +/* Standard. RFC7231, Section 7.1.4 */ +#define MHD_HTTP_HEADER_VARY "Vary" +/* Standard. RFC7230, Section 5.7.1 */ +#define MHD_HTTP_HEADER_VIA "Via" +/* Standard. RFC7235, Section 4.1 */ +#define MHD_HTTP_HEADER_WWW_AUTHENTICATE "WWW-Authenticate" +/* Standard. RFC7234, Section 5.5 */ +#define MHD_HTTP_HEADER_WARNING "Warning" + +/* Additional HTTP headers. */ +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_A_IM "A-IM" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_ACCEPT_ADDITIONS "Accept-Additions" +/* Informational. RFC7089 */ +#define MHD_HTTP_HEADER_ACCEPT_DATETIME "Accept-Datetime" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_ACCEPT_FEATURES "Accept-Features" +/* No category. RFC5789 */ +#define MHD_HTTP_HEADER_ACCEPT_PATCH "Accept-Patch" +/* Standard. RFC7639, Section 2 */ +#define MHD_HTTP_HEADER_ALPN "ALPN" +/* Standard. RFC7838 */ +#define MHD_HTTP_HEADER_ALT_SVC "Alt-Svc" +/* Standard. RFC7838 */ +#define MHD_HTTP_HEADER_ALT_USED "Alt-Used" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_ALTERNATES "Alternates" +/* No category. RFC4437 */ +#define MHD_HTTP_HEADER_APPLY_TO_REDIRECT_REF "Apply-To-Redirect-Ref" +/* Experimental. RFC8053, Section 4 */ +#define MHD_HTTP_HEADER_AUTHENTICATION_CONTROL "Authentication-Control" +/* Standard. RFC7615, Section 3 */ +#define MHD_HTTP_HEADER_AUTHENTICATION_INFO "Authentication-Info" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_EXT "C-Ext" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_MAN "C-Man" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_OPT "C-Opt" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_PEP "C-PEP" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_C_PEP_INFO "C-PEP-Info" +/* Standard. RFC7809, Section 7.1 */ +#define MHD_HTTP_HEADER_CALDAV_TIMEZONES "CalDAV-Timezones" +/* Obsoleted. RFC2068; RFC2616 */ +#define MHD_HTTP_HEADER_CONTENT_BASE "Content-Base" +/* Standard. RFC6266 */ +#define MHD_HTTP_HEADER_CONTENT_DISPOSITION "Content-Disposition" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_ID "Content-ID" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_MD5 "Content-MD5" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_SCRIPT_TYPE "Content-Script-Type" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_STYLE_TYPE "Content-Style-Type" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_CONTENT_VERSION "Content-Version" +/* Standard. RFC6265 */ +#define MHD_HTTP_HEADER_COOKIE "Cookie" +/* Obsoleted. RFC2965; RFC6265 */ +#define MHD_HTTP_HEADER_COOKIE2 "Cookie2" +/* Standard. RFC5323 */ +#define MHD_HTTP_HEADER_DASL "DASL" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_DAV "DAV" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DEFAULT_STYLE "Default-Style" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DELTA_BASE "Delta-Base" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_DEPTH "Depth" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DERIVED_FROM "Derived-From" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_DESTINATION "Destination" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DIFFERENTIAL_ID "Differential-ID" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_DIGEST "Digest" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_EXT "Ext" +/* Standard. RFC7239 */ +#define MHD_HTTP_HEADER_FORWARDED "Forwarded" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_GETPROFILE "GetProfile" +/* Experimental. RFC7486, Section 6.1.1 */ +#define MHD_HTTP_HEADER_HOBAREG "Hobareg" +/* Standard. RFC7540, Section 3.2.1 */ +#define MHD_HTTP_HEADER_HTTP2_SETTINGS "HTTP2-Settings" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_IM "IM" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_IF "If" +/* Standard. RFC6638 */ +#define MHD_HTTP_HEADER_IF_SCHEDULE_TAG_MATCH "If-Schedule-Tag-Match" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_KEEP_ALIVE "Keep-Alive" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_LABEL "Label" +/* No category. RFC5988 */ +#define MHD_HTTP_HEADER_LINK "Link" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_LOCK_TOKEN "Lock-Token" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_MAN "Man" +/* Informational. RFC7089 */ +#define MHD_HTTP_HEADER_MEMENTO_DATETIME "Memento-Datetime" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_METER "Meter" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_NEGOTIATE "Negotiate" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_OPT "Opt" +/* Experimental. RFC8053, Section 3 */ +#define MHD_HTTP_HEADER_OPTIONAL_WWW_AUTHENTICATE "Optional-WWW-Authenticate" +/* Standard. RFC4229 */ +#define MHD_HTTP_HEADER_ORDERING_TYPE "Ordering-Type" +/* Standard. RFC6454 */ +#define MHD_HTTP_HEADER_ORIGIN "Origin" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_OVERWRITE "Overwrite" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_P3P "P3P" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PEP "PEP" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PICS_LABEL "PICS-Label" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PEP_INFO "Pep-Info" +/* Standard. RFC4229 */ +#define MHD_HTTP_HEADER_POSITION "Position" +/* Standard. RFC7240 */ +#define MHD_HTTP_HEADER_PREFER "Prefer" +/* Standard. RFC7240 */ +#define MHD_HTTP_HEADER_PREFERENCE_APPLIED "Preference-Applied" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROFILEOBJECT "ProfileObject" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROTOCOL "Protocol" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROTOCOL_INFO "Protocol-Info" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROTOCOL_QUERY "Protocol-Query" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROTOCOL_REQUEST "Protocol-Request" +/* Standard. RFC7615, Section 4 */ +#define MHD_HTTP_HEADER_PROXY_AUTHENTICATION_INFO "Proxy-Authentication-Info" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROXY_FEATURES "Proxy-Features" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PROXY_INSTRUCTION "Proxy-Instruction" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_PUBLIC "Public" +/* Standard. RFC7469 */ +#define MHD_HTTP_HEADER_PUBLIC_KEY_PINS "Public-Key-Pins" +/* Standard. RFC7469 */ +#define MHD_HTTP_HEADER_PUBLIC_KEY_PINS_REPORT_ONLY "Public-Key-Pins-Report-Only" +/* No category. RFC4437 */ +#define MHD_HTTP_HEADER_REDIRECT_REF "Redirect-Ref" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SAFE "Safe" +/* Standard. RFC6638 */ +#define MHD_HTTP_HEADER_SCHEDULE_REPLY "Schedule-Reply" +/* Standard. RFC6638 */ +#define MHD_HTTP_HEADER_SCHEDULE_TAG "Schedule-Tag" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_ACCEPT "Sec-WebSocket-Accept" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_EXTENSIONS "Sec-WebSocket-Extensions" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_KEY "Sec-WebSocket-Key" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_PROTOCOL "Sec-WebSocket-Protocol" +/* Standard. RFC6455 */ +#define MHD_HTTP_HEADER_SEC_WEBSOCKET_VERSION "Sec-WebSocket-Version" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SECURITY_SCHEME "Security-Scheme" +/* Standard. RFC6265 */ +#define MHD_HTTP_HEADER_SET_COOKIE "Set-Cookie" +/* Obsoleted. RFC2965; RFC6265 */ +#define MHD_HTTP_HEADER_SET_COOKIE2 "Set-Cookie2" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SETPROFILE "SetProfile" +/* Standard. RFC5023 */ +#define MHD_HTTP_HEADER_SLUG "SLUG" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SOAPACTION "SoapAction" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_STATUS_URI "Status-URI" +/* Standard. RFC6797 */ +#define MHD_HTTP_HEADER_STRICT_TRANSPORT_SECURITY "Strict-Transport-Security" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SURROGATE_CAPABILITY "Surrogate-Capability" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_SURROGATE_CONTROL "Surrogate-Control" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_TCN "TCN" +/* Standard. RFC4918 */ +#define MHD_HTTP_HEADER_TIMEOUT "Timeout" +/* Standard. RFC8030, Section 5.4 */ +#define MHD_HTTP_HEADER_TOPIC "Topic" +/* Standard. RFC8030, Section 5.2 */ +#define MHD_HTTP_HEADER_TTL "TTL" +/* Standard. RFC8030, Section 5.3 */ +#define MHD_HTTP_HEADER_URGENCY "Urgency" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_URI "URI" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_VARIANT_VARY "Variant-Vary" +/* No category. RFC4229 */ +#define MHD_HTTP_HEADER_WANT_DIGEST "Want-Digest" +/* Informational. RFC7034 */ +#define MHD_HTTP_HEADER_X_FRAME_OPTIONS "X-Frame-Options" + +/* Some provisional headers. */ +#define MHD_HTTP_HEADER_ACCESS_CONTROL_ALLOW_ORIGIN "Access-Control-Allow-Origin" +/** @} */ /* end of group headers */ + +/** + * @defgroup versions HTTP versions + * These strings should be used to match against the first line of the + * HTTP header. + * @{ + */ +#define MHD_HTTP_VERSION_1_0 "HTTP/1.0" +#define MHD_HTTP_VERSION_1_1 "HTTP/1.1" + +/** @} */ /* end of group versions */ + +/** + * @defgroup methods HTTP methods + * HTTP methods (as strings). + * See: http://www.iana.org/assignments/http-methods/http-methods.xml + * Registry Version 2015-05-19 + * @{ + */ +/* Main HTTP methods. */ +/* Not safe. Not idempotent. RFC7231, Section 4.3.6. */ +#define MHD_HTTP_METHOD_CONNECT "CONNECT" +/* Not safe. Idempotent. RFC7231, Section 4.3.5. */ +#define MHD_HTTP_METHOD_DELETE "DELETE" +/* Safe. Idempotent. RFC7231, Section 4.3.1. */ +#define MHD_HTTP_METHOD_GET "GET" +/* Safe. Idempotent. RFC7231, Section 4.3.2. */ +#define MHD_HTTP_METHOD_HEAD "HEAD" +/* Safe. Idempotent. RFC7231, Section 4.3.7. */ +#define MHD_HTTP_METHOD_OPTIONS "OPTIONS" +/* Not safe. Not idempotent. RFC7231, Section 4.3.3. */ +#define MHD_HTTP_METHOD_POST "POST" +/* Not safe. Idempotent. RFC7231, Section 4.3.4. */ +#define MHD_HTTP_METHOD_PUT "PUT" +/* Safe. Idempotent. RFC7231, Section 4.3.8. */ +#define MHD_HTTP_METHOD_TRACE "TRACE" + +/* Additional HTTP methods. */ +/* Not safe. Idempotent. RFC3744, Section 8.1. */ +#define MHD_HTTP_METHOD_ACL "ACL" +/* Not safe. Idempotent. RFC3253, Section 12.6. */ +#define MHD_HTTP_METHOD_BASELINE_CONTROL "BASELINE-CONTROL" +/* Not safe. Idempotent. RFC5842, Section 4. */ +#define MHD_HTTP_METHOD_BIND "BIND" +/* Not safe. Idempotent. RFC3253, Section 4.4, Section 9.4. */ +#define MHD_HTTP_METHOD_CHECKIN "CHECKIN" +/* Not safe. Idempotent. RFC3253, Section 4.3, Section 8.8. */ +#define MHD_HTTP_METHOD_CHECKOUT "CHECKOUT" +/* Not safe. Idempotent. RFC4918, Section 9.8. */ +#define MHD_HTTP_METHOD_COPY "COPY" +/* Not safe. Idempotent. RFC3253, Section 8.2. */ +#define MHD_HTTP_METHOD_LABEL "LABEL" +/* Not safe. Idempotent. RFC2068, Section 19.6.1.2. */ +#define MHD_HTTP_METHOD_LINK "LINK" +/* Not safe. Not idempotent. RFC4918, Section 9.10. */ +#define MHD_HTTP_METHOD_LOCK "LOCK" +/* Not safe. Idempotent. RFC3253, Section 11.2. */ +#define MHD_HTTP_METHOD_MERGE "MERGE" +/* Not safe. Idempotent. RFC3253, Section 13.5. */ +#define MHD_HTTP_METHOD_MKACTIVITY "MKACTIVITY" +/* Not safe. Idempotent. RFC4791, Section 5.3.1. */ +#define MHD_HTTP_METHOD_MKCALENDAR "MKCALENDAR" +/* Not safe. Idempotent. RFC4918, Section 9.3. */ +#define MHD_HTTP_METHOD_MKCOL "MKCOL" +/* Not safe. Idempotent. RFC4437, Section 6. */ +#define MHD_HTTP_METHOD_MKREDIRECTREF "MKREDIRECTREF" +/* Not safe. Idempotent. RFC3253, Section 6.3. */ +#define MHD_HTTP_METHOD_MKWORKSPACE "MKWORKSPACE" +/* Not safe. Idempotent. RFC4918, Section 9.9. */ +#define MHD_HTTP_METHOD_MOVE "MOVE" +/* Not safe. Idempotent. RFC3648, Section 7. */ +#define MHD_HTTP_METHOD_ORDERPATCH "ORDERPATCH" +/* Not safe. Not idempotent. RFC5789, Section 2. */ +#define MHD_HTTP_METHOD_PATCH "PATCH" +/* Safe. Idempotent. RFC7540, Section 3.5. */ +#define MHD_HTTP_METHOD_PRI "PRI" +/* Safe. Idempotent. RFC4918, Section 9.1. */ +#define MHD_HTTP_METHOD_PROPFIND "PROPFIND" +/* Not safe. Idempotent. RFC4918, Section 9.2. */ +#define MHD_HTTP_METHOD_PROPPATCH "PROPPATCH" +/* Not safe. Idempotent. RFC5842, Section 6. */ +#define MHD_HTTP_METHOD_REBIND "REBIND" +/* Safe. Idempotent. RFC3253, Section 3.6. */ +#define MHD_HTTP_METHOD_REPORT "REPORT" +/* Safe. Idempotent. RFC5323, Section 2. */ +#define MHD_HTTP_METHOD_SEARCH "SEARCH" +/* Not safe. Idempotent. RFC5842, Section 5. */ +#define MHD_HTTP_METHOD_UNBIND "UNBIND" +/* Not safe. Idempotent. RFC3253, Section 4.5. */ +#define MHD_HTTP_METHOD_UNCHECKOUT "UNCHECKOUT" +/* Not safe. Idempotent. RFC2068, Section 19.6.1.3. */ +#define MHD_HTTP_METHOD_UNLINK "UNLINK" +/* Not safe. Idempotent. RFC4918, Section 9.11. */ +#define MHD_HTTP_METHOD_UNLOCK "UNLOCK" +/* Not safe. Idempotent. RFC3253, Section 7.1. */ +#define MHD_HTTP_METHOD_UPDATE "UPDATE" +/* Not safe. Idempotent. RFC4437, Section 7. */ +#define MHD_HTTP_METHOD_UPDATEREDIRECTREF "UPDATEREDIRECTREF" +/* Not safe. Idempotent. RFC3253, Section 3.5. */ +#define MHD_HTTP_METHOD_VERSION_CONTROL "VERSION-CONTROL" + +/** @} */ /* end of group methods */ + +/** + * @defgroup postenc HTTP POST encodings + * See also: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4 + * @{ + */ +#define MHD_HTTP_POST_ENCODING_FORM_URLENCODED "application/x-www-form-urlencoded" +#define MHD_HTTP_POST_ENCODING_MULTIPART_FORMDATA "multipart/form-data" + +/** @} */ /* end of group postenc */ + + +/** + * @brief Handle for the daemon (listening on a socket for HTTP traffic). + * @ingroup event + */ +struct MHD_Daemon; + +/** + * @brief Handle for a connection / HTTP request. + * + * With HTTP/1.1, multiple requests can be run over the same + * connection. However, MHD will only show one request per TCP + * connection to the client at any given time. + * @ingroup request + */ +struct MHD_Connection; + +/** + * @brief Handle for a response. + * @ingroup response + */ +struct MHD_Response; + +/** + * @brief Handle for POST processing. + * @ingroup response + */ +struct MHD_PostProcessor; + + +/** + * @brief Flags for the `struct MHD_Daemon`. + * + * Note that MHD will run automatically in background thread(s) only + * if #MHD_USE_INTERNAL_POLLING_THREAD is used. Otherwise caller (application) + * must use #MHD_run() or #MHD_run_from_select() to have MHD processed + * network connections and data. + * + * Starting the daemon may also fail if a particular option is not + * implemented or not supported on the target platform (i.e. no + * support for TLS, epoll or IPv6). + */ +enum MHD_FLAG +{ + /** + * No options selected. + */ + MHD_NO_FLAG = 0, + + /** + * Print errors messages to custom error logger or to `stderr` if + * custom error logger is not set. + * @sa ::MHD_OPTION_EXTERNAL_LOGGER + */ + MHD_USE_ERROR_LOG = 1, + + /** + * Run in debug mode. If this flag is used, the library should + * print error messages and warnings to `stderr`. + */ + MHD_USE_DEBUG = 1, + + /** + * Run in HTTPS mode. The modern protocol is called TLS. + */ + MHD_USE_TLS = 2, + + /** @deprecated */ + MHD_USE_SSL = 2, +#if 0 + /* let's do this later once versions that define MHD_USE_TLS a more widely deployed. */ +#define MHD_USE_SSL \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_SSL is deprecated, use MHD_USE_TLS") \ + MHD_USE_TLS +#endif + + /** + * Run using one thread per connection. + * Must be used only with #MHD_USE_INTERNAL_POLLING_THREAD. + */ + MHD_USE_THREAD_PER_CONNECTION = 4, + + /** + * Run using an internal thread (or thread pool) for sockets sending + * and receiving and data processing. Without this flag MHD will not + * run automatically in background thread(s). + * If this flag is set, #MHD_run() and #MHD_run_from_select() couldn't + * be used. + * This flag is set explicitly by #MHD_USE_POLL_INTERNAL_THREAD and + * by #MHD_USE_EPOLL_INTERNAL_THREAD. + */ + MHD_USE_INTERNAL_POLLING_THREAD = 8, + + /** @deprecated */ + MHD_USE_SELECT_INTERNALLY = 8, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_SELECT_INTERNALLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_SELECT_INTERNALLY is deprecated, use MHD_USE_INTERNAL_POLLING_THREAD instead") \ + MHD_USE_INTERNAL_POLLING_THREAD +#endif /* 0 */ + + /** + * Run using the IPv6 protocol (otherwise, MHD will just support + * IPv4). If you want MHD to support IPv4 and IPv6 using a single + * socket, pass #MHD_USE_DUAL_STACK, otherwise, if you only pass + * this option, MHD will try to bind to IPv6-only (resulting in + * no IPv4 support). + */ + MHD_USE_IPv6 = 16, + + /** + * Be pedantic about the protocol (as opposed to as tolerant as + * possible). Specifically, at the moment, this flag causes MHD to + * reject HTTP 1.1 connections without a "Host" header. This is + * required by the standard, but of course in violation of the "be + * as liberal as possible in what you accept" norm. It is + * recommended to turn this ON if you are testing clients against + * MHD, and OFF in production. + */ + MHD_USE_PEDANTIC_CHECKS = 32, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_PEDANTIC_CHECKS \ + _MHD_DEPR_IN_MACRO("Flag MHD_USE_PEDANTIC_CHECKS is deprecated, use option MHD_OPTION_STRICT_FOR_CLIENT instead") \ + 32 +#endif /* 0 */ + + /** + * Use `poll()` instead of `select()`. This allows sockets with `fd >= + * FD_SETSIZE`. This option is not compatible with using an + * 'external' polling mode (as there is no API to get the file + * descriptors for the external poll() from MHD) and must also not + * be used in combination with #MHD_USE_EPOLL. + * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL_INTERNAL_THREAD + */ + MHD_USE_POLL = 64, + + /** + * Run using an internal thread (or thread pool) doing `poll()`. + * @sa ::MHD_FEATURE_POLL, #MHD_USE_POLL, #MHD_USE_INTERNAL_POLLING_THREAD + */ + MHD_USE_POLL_INTERNAL_THREAD = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, + + /** @deprecated */ + MHD_USE_POLL_INTERNALLY = MHD_USE_POLL | MHD_USE_INTERNAL_POLLING_THREAD, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_POLL_INTERNALLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_POLL_INTERNALLY is deprecated, use MHD_USE_POLL_INTERNAL_THREAD instead") \ + MHD_USE_POLL_INTERNAL_THREAD +#endif /* 0 */ + + /** + * Suppress (automatically) adding the 'Date:' header to HTTP responses. + * This option should ONLY be used on systems that do not have a clock + * and that DO provide other mechanisms for cache control. See also + * RFC 2616, section 14.18 (exception 3). + */ + MHD_USE_SUPPRESS_DATE_NO_CLOCK = 128, + + /** @deprecated */ + MHD_SUPPRESS_DATE_NO_CLOCK = 128, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_SUPPRESS_DATE_NO_CLOCK \ + _MHD_DEPR_IN_MACRO("Value MHD_SUPPRESS_DATE_NO_CLOCK is deprecated, use MHD_USE_SUPPRESS_DATE_NO_CLOCK instead") \ + MHD_USE_SUPPRESS_DATE_NO_CLOCK +#endif /* 0 */ + + /** + * Run without a listen socket. This option only makes sense if + * #MHD_add_connection is to be used exclusively to connect HTTP + * clients to the HTTP server. This option is incompatible with + * using a thread pool; if it is used, #MHD_OPTION_THREAD_POOL_SIZE + * is ignored. + */ + MHD_USE_NO_LISTEN_SOCKET = 256, + + /** + * Use `epoll()` instead of `select()` or `poll()` for the event loop. + * This option is only available on some systems; using the option on + * systems without epoll will cause #MHD_start_daemon to fail. Using + * this option is not supported with #MHD_USE_THREAD_PER_CONNECTION. + * @sa ::MHD_FEATURE_EPOLL + */ + MHD_USE_EPOLL = 512, + + /** @deprecated */ + MHD_USE_EPOLL_LINUX_ONLY = 512, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_EPOLL_LINUX_ONLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_EPOLL_LINUX_ONLY is deprecated, use MHD_USE_EPOLL") \ + MHD_USE_EPOLL +#endif /* 0 */ + + /** + * Run using an internal thread (or thread pool) doing `epoll()`. + * This option is only available on certain platforms; using the option on + * platform without `epoll` support will cause #MHD_start_daemon to fail. + * @sa ::MHD_FEATURE_EPOLL, #MHD_USE_EPOLL, #MHD_USE_INTERNAL_POLLING_THREAD + */ + MHD_USE_EPOLL_INTERNAL_THREAD = MHD_USE_EPOLL | MHD_USE_INTERNAL_POLLING_THREAD, + + /** @deprecated */ + MHD_USE_EPOLL_INTERNALLY = MHD_USE_EPOLL | MHD_USE_INTERNAL_POLLING_THREAD, + /** @deprecated */ + MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY = MHD_USE_EPOLL | MHD_USE_INTERNAL_POLLING_THREAD, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_EPOLL_INTERNALLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_EPOLL_INTERNALLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ + MHD_USE_EPOLL_INTERNAL_THREAD + /** @deprecated */ +#define MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_EPOLL_INTERNALLY_LINUX_ONLY is deprecated, use MHD_USE_EPOLL_INTERNAL_THREAD") \ + MHD_USE_EPOLL_INTERNAL_THREAD +#endif /* 0 */ + + /** + * Use inter-thread communication channel. + * #MHD_USE_ITC can be used with #MHD_USE_INTERNAL_POLLING_THREAD + * and is ignored with any "external" mode. + * It's required for use of #MHD_quiesce_daemon + * or #MHD_add_connection. + * This option is enforced by #MHD_ALLOW_SUSPEND_RESUME or + * #MHD_USE_NO_LISTEN_SOCKET. + * #MHD_USE_ITC is always used automatically on platforms + * where select()/poll()/other ignore shutdown of listen + * socket. + */ + MHD_USE_ITC = 1024, + + /** @deprecated */ + MHD_USE_PIPE_FOR_SHUTDOWN = 1024, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_PIPE_FOR_SHUTDOWN \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_PIPE_FOR_SHUTDOWN is deprecated, use MHD_USE_ITC") \ + MHD_USE_ITC +#endif /* 0 */ + + /** + * Use a single socket for IPv4 and IPv6. + */ + MHD_USE_DUAL_STACK = MHD_USE_IPv6 | 2048, + + /** + * Enable `turbo`. Disables certain calls to `shutdown()`, + * enables aggressive non-blocking optimistic reads and + * other potentially unsafe optimizations. + * Most effects only happen with #MHD_USE_EPOLL. + */ + MHD_USE_TURBO = 4096, + + /** @deprecated */ + MHD_USE_EPOLL_TURBO = 4096, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_EPOLL_TURBO \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_EPOLL_TURBO is deprecated, use MHD_USE_TURBO") \ + MHD_USE_TURBO +#endif /* 0 */ + + /** + * Enable suspend/resume functions, which also implies setting up + * ITC to signal resume. + */ + MHD_ALLOW_SUSPEND_RESUME = 8192 | MHD_USE_ITC, + + /** @deprecated */ + MHD_USE_SUSPEND_RESUME = 8192 | MHD_USE_ITC, +#if 0 /* Will be marked for real deprecation later. */ +#define MHD_USE_SUSPEND_RESUME \ + _MHD_DEPR_IN_MACRO("Value MHD_USE_SUSPEND_RESUME is deprecated, use MHD_ALLOW_SUSPEND_RESUME instead") \ + MHD_ALLOW_SUSPEND_RESUME +#endif /* 0 */ + + /** + * Enable TCP_FASTOPEN option. This option is only available on Linux with a + * kernel >= 3.6. On other systems, using this option cases #MHD_start_daemon + * to fail. + */ + MHD_USE_TCP_FASTOPEN = 16384, + + /** + * You need to set this option if you want to use HTTP "Upgrade". + * "Upgrade" may require usage of additional internal resources, + * which we do not want to use unless necessary. + */ + MHD_ALLOW_UPGRADE = 32768, + + /** + * Automatically use best available polling function. + * Choice of polling function is also depend on other daemon options. + * If #MHD_USE_INTERNAL_POLLING_THREAD is specified then epoll, poll() or + * select() will be used (listed in decreasing preference order, first + * function available on system will be used). + * If #MHD_USE_THREAD_PER_CONNECTION is specified then poll() or select() + * will be used. + * If those flags are not specified then epoll or select() will be + * used (as the only suitable for MHD_get_fdset()) + */ + MHD_USE_AUTO = 65536, + + /** + * Run using an internal thread (or thread pool) with best available on + * system polling function. + * This is combination of #MHD_USE_AUTO and #MHD_USE_INTERNAL_POLLING_THREAD + * flags. + */ + MHD_USE_AUTO_INTERNAL_THREAD = MHD_USE_AUTO | MHD_USE_INTERNAL_POLLING_THREAD + +}; + + +/** + * Type of a callback function used for logging by MHD. + * + * @param cls closure + * @param fm format string (`printf()`-style) + * @param ap arguments to @a fm + * @ingroup logging + */ +typedef void +(*MHD_LogCallback)(void *cls, + const char *fm, + va_list ap); + + +/** + * @brief MHD options. + * + * Passed in the varargs portion of #MHD_start_daemon. + */ +enum MHD_OPTION +{ + + /** + * No more options / last option. This is used + * to terminate the VARARGs list. + */ + MHD_OPTION_END = 0, + + /** + * Maximum memory size per connection (followed by a `size_t`). + * Default is 32 kb (#MHD_POOL_SIZE_DEFAULT). + * Values above 128k are unlikely to result in much benefit, as half + * of the memory will be typically used for IO, and TCP buffers are + * unlikely to support window sizes above 64k on most systems. + */ + MHD_OPTION_CONNECTION_MEMORY_LIMIT = 1, + + /** + * Maximum number of concurrent connections to + * accept (followed by an `unsigned int`). + */ + MHD_OPTION_CONNECTION_LIMIT = 2, + + /** + * After how many seconds of inactivity should a + * connection automatically be timed out? (followed + * by an `unsigned int`; use zero for no timeout). + */ + MHD_OPTION_CONNECTION_TIMEOUT = 3, + + /** + * Register a function that should be called whenever a request has + * been completed (this can be used for application-specific clean + * up). Requests that have never been presented to the application + * (via #MHD_AccessHandlerCallback) will not result in + * notifications. + * + * This option should be followed by TWO pointers. First a pointer + * to a function of type #MHD_RequestCompletedCallback and second a + * pointer to a closure to pass to the request completed callback. + * The second pointer maybe NULL. + */ + MHD_OPTION_NOTIFY_COMPLETED = 4, + + /** + * Limit on the number of (concurrent) connections made to the + * server from the same IP address. Can be used to prevent one + * IP from taking over all of the allowed connections. If the + * same IP tries to establish more than the specified number of + * connections, they will be immediately rejected. The option + * should be followed by an `unsigned int`. The default is + * zero, which means no limit on the number of connections + * from the same IP address. + */ + MHD_OPTION_PER_IP_CONNECTION_LIMIT = 5, + + /** + * Bind daemon to the supplied `struct sockaddr`. This option should + * be followed by a `struct sockaddr *`. If #MHD_USE_IPv6 is + * specified, the `struct sockaddr*` should point to a `struct + * sockaddr_in6`, otherwise to a `struct sockaddr_in`. + */ + MHD_OPTION_SOCK_ADDR = 6, + + /** + * Specify a function that should be called before parsing the URI from + * the client. The specified callback function can be used for processing + * the URI (including the options) before it is parsed. The URI after + * parsing will no longer contain the options, which maybe inconvenient for + * logging. This option should be followed by two arguments, the first + * one must be of the form + * + * void * my_logger(void *cls, const char *uri, struct MHD_Connection *con) + * + * where the return value will be passed as + * (`* con_cls`) in calls to the #MHD_AccessHandlerCallback + * when this request is processed later; returning a + * value of NULL has no special significance (however, + * note that if you return non-NULL, you can no longer + * rely on the first call to the access handler having + * `NULL == *con_cls` on entry;) + * "cls" will be set to the second argument following + * #MHD_OPTION_URI_LOG_CALLBACK. Finally, uri will + * be the 0-terminated URI of the request. + * + * Note that during the time of this call, most of the connection's + * state is not initialized (as we have not yet parsed the headers). + * However, information about the connecting client (IP, socket) + * is available. + * + * The specified function is called only once per request, therefore some + * programmers may use it to instantiate their own request objects, freeing + * them in the notifier #MHD_OPTION_NOTIFY_COMPLETED. + */ + MHD_OPTION_URI_LOG_CALLBACK = 7, + + /** + * Memory pointer for the private key (key.pem) to be used by the + * HTTPS daemon. This option should be followed by a + * `const char *` argument. + * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_CERT. + */ + MHD_OPTION_HTTPS_MEM_KEY = 8, + + /** + * Memory pointer for the certificate (cert.pem) to be used by the + * HTTPS daemon. This option should be followed by a + * `const char *` argument. + * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. + */ + MHD_OPTION_HTTPS_MEM_CERT = 9, + + /** + * Daemon credentials type. + * Followed by an argument of type + * `gnutls_credentials_type_t`. + */ + MHD_OPTION_HTTPS_CRED_TYPE = 10, + + /** + * Memory pointer to a `const char *` specifying the + * cipher algorithm (default: "NORMAL"). + */ + MHD_OPTION_HTTPS_PRIORITIES = 11, + + /** + * Pass a listen socket for MHD to use (systemd-style). If this + * option is used, MHD will not open its own listen socket(s). The + * argument passed must be of type `MHD_socket` and refer to an + * existing socket that has been bound to a port and is listening. + */ + MHD_OPTION_LISTEN_SOCKET = 12, + + /** + * Use the given function for logging error messages. This option + * must be followed by two arguments; the first must be a pointer to + * a function of type #MHD_LogCallback and the second a pointer + * `void *` which will be passed as the first argument to the log + * callback. + * + * Note that MHD will not generate any log messages + * if it was compiled without the "--enable-messages" + * flag being set. + */ + MHD_OPTION_EXTERNAL_LOGGER = 13, + + /** + * Number (`unsigned int`) of threads in thread pool. Enable + * thread pooling by setting this value to to something + * greater than 1. Currently, thread model must be + * #MHD_USE_INTERNAL_POLLING_THREAD if thread pooling is enabled + * (#MHD_start_daemon returns NULL for an unsupported thread + * model). + */ + MHD_OPTION_THREAD_POOL_SIZE = 14, + + /** + * Additional options given in an array of `struct MHD_OptionItem`. + * The array must be terminated with an entry `{MHD_OPTION_END, 0, NULL}`. + * An example for code using #MHD_OPTION_ARRAY is: + * + * struct MHD_OptionItem ops[] = { + * { MHD_OPTION_CONNECTION_LIMIT, 100, NULL }, + * { MHD_OPTION_CONNECTION_TIMEOUT, 10, NULL }, + * { MHD_OPTION_END, 0, NULL } + * }; + * d = MHD_start_daemon (0, 8080, NULL, NULL, dh, NULL, + * MHD_OPTION_ARRAY, ops, + * MHD_OPTION_END); + * + * For options that expect a single pointer argument, the + * second member of the `struct MHD_OptionItem` is ignored. + * For options that expect two pointer arguments, the first + * argument must be cast to `intptr_t`. + */ + MHD_OPTION_ARRAY = 15, + + /** + * Specify a function that should be called for unescaping escape + * sequences in URIs and URI arguments. Note that this function + * will NOT be used by the `struct MHD_PostProcessor`. If this + * option is not specified, the default method will be used which + * decodes escape sequences of the form "%HH". This option should + * be followed by two arguments, the first one must be of the form + * + * size_t my_unescaper(void *cls, + * struct MHD_Connection *c, + * char *s) + * + * where the return value must be "strlen(s)" and "s" should be + * updated. Note that the unescape function must not lengthen "s" + * (the result must be shorter than the input and still be + * 0-terminated). "cls" will be set to the second argument + * following #MHD_OPTION_UNESCAPE_CALLBACK. + */ + MHD_OPTION_UNESCAPE_CALLBACK = 16, + + /** + * Memory pointer for the random values to be used by the Digest + * Auth module. This option should be followed by two arguments. + * First an integer of type `size_t` which specifies the size + * of the buffer pointed to by the second argument in bytes. + * Note that the application must ensure that the buffer of the + * second argument remains allocated and unmodified while the + * deamon is running. + */ + MHD_OPTION_DIGEST_AUTH_RANDOM = 17, + + /** + * Size of the internal array holding the map of the nonce and + * the nonce counter. This option should be followed by an `unsigend int` + * argument. + */ + MHD_OPTION_NONCE_NC_SIZE = 18, + + /** + * Desired size of the stack for threads created by MHD. Followed + * by an argument of type `size_t`. Use 0 for system default. + */ + MHD_OPTION_THREAD_STACK_SIZE = 19, + + /** + * Memory pointer for the certificate (ca.pem) to be used by the + * HTTPS daemon for client authentification. + * This option should be followed by a `const char *` argument. + */ + MHD_OPTION_HTTPS_MEM_TRUST = 20, + + /** + * Increment to use for growing the read buffer (followed by a + * `size_t`). Must fit within #MHD_OPTION_CONNECTION_MEMORY_LIMIT. + */ + MHD_OPTION_CONNECTION_MEMORY_INCREMENT = 21, + + /** + * Use a callback to determine which X.509 certificate should be + * used for a given HTTPS connection. This option should be + * followed by a argument of type `gnutls_certificate_retrieve_function2 *`. + * This option provides an + * alternative to #MHD_OPTION_HTTPS_MEM_KEY, + * #MHD_OPTION_HTTPS_MEM_CERT. You must use this version if + * multiple domains are to be hosted at the same IP address using + * TLS's Server Name Indication (SNI) extension. In this case, + * the callback is expected to select the correct certificate + * based on the SNI information provided. The callback is expected + * to access the SNI data using `gnutls_server_name_get()`. + * Using this option requires GnuTLS 3.0 or higher. + */ + MHD_OPTION_HTTPS_CERT_CALLBACK = 22, + + /** + * When using #MHD_USE_TCP_FASTOPEN, this option changes the default TCP + * fastopen queue length of 50. Note that having a larger queue size can + * cause resource exhaustion attack as the TCP stack has to now allocate + * resources for the SYN packet along with its DATA. This option should be + * followed by an `unsigned int` argument. + */ + MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE = 23, + + /** + * Memory pointer for the Diffie-Hellman parameters (dh.pem) to be used by the + * HTTPS daemon for key exchange. + * This option must be followed by a `const char *` argument. + */ + MHD_OPTION_HTTPS_MEM_DHPARAMS = 24, + + /** + * If present and set to true, allow reusing address:port socket + * (by using SO_REUSEPORT on most platform, or platform-specific ways). + * If present and set to false, disallow reusing address:port socket + * (does nothing on most plaform, but uses SO_EXCLUSIVEADDRUSE on Windows). + * This option must be followed by a `unsigned int` argument. + */ + MHD_OPTION_LISTENING_ADDRESS_REUSE = 25, + + /** + * Memory pointer for a password that decrypts the private key (key.pem) + * to be used by the HTTPS daemon. This option should be followed by a + * `const char *` argument. + * This should be used in conjunction with #MHD_OPTION_HTTPS_MEM_KEY. + * @sa ::MHD_FEATURE_HTTPS_KEY_PASSWORD + */ + MHD_OPTION_HTTPS_KEY_PASSWORD = 26, + + /** + * Register a function that should be called whenever a connection is + * started or closed. + * + * This option should be followed by TWO pointers. First a pointer + * to a function of type #MHD_NotifyConnectionCallback and second a + * pointer to a closure to pass to the request completed callback. + * The second pointer maybe NULL. + */ + MHD_OPTION_NOTIFY_CONNECTION = 27, + + /** + * Allow to change maximum length of the queue of pending connections on + * listen socket. If not present than default platform-specific SOMAXCONN + * value is used. This option should be followed by an `unsigned int` + * argument. + */ + MHD_OPTION_LISTEN_BACKLOG_SIZE = 28, + + /** + * If set to 1 - be strict about the protocol (as opposed to as + * tolerant as possible). Specifically, at the moment, this flag + * causes MHD to reject HTTP 1.1 connections without a "Host" header. + * This is required by the standard, but of course in violation of + * the "be as liberal as possible in what you accept" norm. It is + * recommended to set this to 1 if you are testing clients against + * MHD, and 0 in production. + * if set to -1 - be opposite to strict and be permissive about the + * protocol, allowing slight deviations that are technically not + * allowed by the RFC. Specifically, at the moment, this flag + * causes MHD to allow spaces in header field names. This is + * disallowed by the standard. + * It is not recommended to set it to -1 on publicly available + * servers as it may potentially lower level of protection. + * This option should be followed by an `int` argument. + */ + MHD_OPTION_STRICT_FOR_CLIENT = 29 +}; + + +/** + * Entry in an #MHD_OPTION_ARRAY. + */ +struct MHD_OptionItem +{ + /** + * Which option is being given. Use #MHD_OPTION_END + * to terminate the array. + */ + enum MHD_OPTION option; + + /** + * Option value (for integer arguments, and for options requiring + * two pointer arguments); should be 0 for options that take no + * arguments or only a single pointer argument. + */ + intptr_t value; + + /** + * Pointer option value (use NULL for options taking no arguments + * or only an integer option). + */ + void *ptr_value; + +}; + + +/** + * The `enum MHD_ValueKind` specifies the source of + * the key-value pairs in the HTTP protocol. + */ +enum MHD_ValueKind +{ + + /** + * Response header + * @deprecated + */ + MHD_RESPONSE_HEADER_KIND = 0, +#define MHD_RESPONSE_HEADER_KIND \ + _MHD_DEPR_IN_MACRO("Value MHD_RESPONSE_HEADER_KIND is deprecated and not used") \ + MHD_RESPONSE_HEADER_KIND + + /** + * HTTP header (request/response). + */ + MHD_HEADER_KIND = 1, + + /** + * Cookies. Note that the original HTTP header containing + * the cookie(s) will still be available and intact. + */ + MHD_COOKIE_KIND = 2, + + /** + * POST data. This is available only if a content encoding + * supported by MHD is used (currently only URL encoding), + * and only if the posted content fits within the available + * memory pool. Note that in that case, the upload data + * given to the #MHD_AccessHandlerCallback will be + * empty (since it has already been processed). + */ + MHD_POSTDATA_KIND = 4, + + /** + * GET (URI) arguments. + */ + MHD_GET_ARGUMENT_KIND = 8, + + /** + * HTTP footer (only for HTTP 1.1 chunked encodings). + */ + MHD_FOOTER_KIND = 16 +}; + + +/** + * The `enum MHD_RequestTerminationCode` specifies reasons + * why a request has been terminated (or completed). + * @ingroup request + */ +enum MHD_RequestTerminationCode +{ + + /** + * We finished sending the response. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_COMPLETED_OK = 0, + + /** + * Error handling the connection (resources + * exhausted, other side closed connection, + * application error accepting request, etc.) + * @ingroup request + */ + MHD_REQUEST_TERMINATED_WITH_ERROR = 1, + + /** + * No activity on the connection for the number + * of seconds specified using + * #MHD_OPTION_CONNECTION_TIMEOUT. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_TIMEOUT_REACHED = 2, + + /** + * We had to close the session since MHD was being + * shut down. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_DAEMON_SHUTDOWN = 3, + + /** + * We tried to read additional data, but the other side closed the + * connection. This error is similar to + * #MHD_REQUEST_TERMINATED_WITH_ERROR, but specific to the case where + * the connection died because the other side did not send expected + * data. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_READ_ERROR = 4, + + /** + * The client terminated the connection by closing the socket + * for writing (TCP half-closed); MHD aborted sending the + * response according to RFC 2616, section 8.1.4. + * @ingroup request + */ + MHD_REQUEST_TERMINATED_CLIENT_ABORT = 5 + +}; + + +/** + * The `enum MHD_ConnectionNotificationCode` specifies types + * of connection notifications. + * @ingroup request + */ +enum MHD_ConnectionNotificationCode +{ + + /** + * A new connection has been started. + * @ingroup request + */ + MHD_CONNECTION_NOTIFY_STARTED = 0, + + /** + * A connection is closed. + * @ingroup request + */ + MHD_CONNECTION_NOTIFY_CLOSED = 1 + +}; + + +/** + * Information about a connection. + */ +union MHD_ConnectionInfo +{ + + /** + * Cipher algorithm used, of type "enum gnutls_cipher_algorithm". + */ + int /* enum gnutls_cipher_algorithm */ cipher_algorithm; + + /** + * Protocol used, of type "enum gnutls_protocol". + */ + int /* enum gnutls_protocol */ protocol; + + /** + * The suspended status of a connection. + */ + int /* MHD_YES or MHD_NO */ suspended; + + /** + * Amount of second that connection could spend in idle state + * before automatically disconnected. + * Zero for no timeout (unlimited idle time). + */ + unsigned int connection_timeout; + + /** + * Connect socket + */ + MHD_socket connect_fd; + + /** + * Size of the client's HTTP header. + */ + size_t header_size; + + /** + * GNUtls session handle, of type "gnutls_session_t". + */ + void * /* gnutls_session_t */ tls_session; + + /** + * GNUtls client certificate handle, of type "gnutls_x509_crt_t". + */ + void * /* gnutls_x509_crt_t */ client_cert; + + /** + * Address information for the client. + */ + struct sockaddr *client_addr; + + /** + * Which daemon manages this connection (useful in case there are many + * daemons running). + */ + struct MHD_Daemon *daemon; + + /** + * Socket-specific client context. Points to the same address as + * the "socket_context" of the #MHD_NotifyConnectionCallback. + */ + void *socket_context; +}; + + +/** + * Values of this enum are used to specify what + * information about a connection is desired. + * @ingroup request + */ +enum MHD_ConnectionInfoType +{ + /** + * What cipher algorithm is being used. + * Takes no extra arguments. + * @ingroup request + */ + MHD_CONNECTION_INFO_CIPHER_ALGO, + + /** + * + * Takes no extra arguments. + * @ingroup request + */ + MHD_CONNECTION_INFO_PROTOCOL, + + /** + * Obtain IP address of the client. Takes no extra arguments. + * Returns essentially a `struct sockaddr **` (since the API returns + * a `union MHD_ConnectionInfo *` and that union contains a `struct + * sockaddr *`). + * @ingroup request + */ + MHD_CONNECTION_INFO_CLIENT_ADDRESS, + + /** + * Get the gnuTLS session handle. + * @ingroup request + */ + MHD_CONNECTION_INFO_GNUTLS_SESSION, + + /** + * Get the gnuTLS client certificate handle. Dysfunctional (never + * implemented, deprecated). Use #MHD_CONNECTION_INFO_GNUTLS_SESSION + * to get the `gnutls_session_t` and then call + * gnutls_certificate_get_peers(). + */ + MHD_CONNECTION_INFO_GNUTLS_CLIENT_CERT, + + /** + * Get the `struct MHD_Daemon *` responsible for managing this connection. + * @ingroup request + */ + MHD_CONNECTION_INFO_DAEMON, + + /** + * Request the file descriptor for the connection socket. + * No extra arguments should be passed. + * @ingroup request + */ + MHD_CONNECTION_INFO_CONNECTION_FD, + + /** + * Returns the client-specific pointer to a `void *` that was (possibly) + * set during a #MHD_NotifyConnectionCallback when the socket was + * first accepted. Note that this is NOT the same as the "con_cls" + * argument of the #MHD_AccessHandlerCallback. The "con_cls" is + * fresh for each HTTP request, while the "socket_context" is fresh + * for each socket. + */ + MHD_CONNECTION_INFO_SOCKET_CONTEXT, + + /** + * Check whether the connection is suspended. + * @ingroup request + */ + MHD_CONNECTION_INFO_CONNECTION_SUSPENDED, + + /** + * Get connection timeout + * @ingroup request + */ + MHD_CONNECTION_INFO_CONNECTION_TIMEOUT, + + /** + * Return length of the client's HTTP request header. + * @ingroup request + */ + MHD_CONNECTION_INFO_REQUEST_HEADER_SIZE +}; + + +/** + * Values of this enum are used to specify what + * information about a deamon is desired. + */ +enum MHD_DaemonInfoType +{ + /** + * No longer supported (will return NULL). + */ + MHD_DAEMON_INFO_KEY_SIZE, + + /** + * No longer supported (will return NULL). + */ + MHD_DAEMON_INFO_MAC_KEY_SIZE, + + /** + * Request the file descriptor for the listening socket. + * No extra arguments should be passed. + */ + MHD_DAEMON_INFO_LISTEN_FD, + + /** + * Request the file descriptor for the external epoll. + * No extra arguments should be passed. + */ + MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, + MHD_DAEMON_INFO_EPOLL_FD = MHD_DAEMON_INFO_EPOLL_FD_LINUX_ONLY, + + /** + * Request the number of current connections handled by the daemon. + * No extra arguments should be passed. + * Note: when using MHD in external polling mode, this type of request + * could be used only when #MHD_run()/#MHD_run_from_select is not + * working in other thread at the same time. + */ + MHD_DAEMON_INFO_CURRENT_CONNECTIONS, + + /** + * Request the daemon flags. + * No extra arguments should be passed. + * Note: flags may differ from original 'flags' specified for + * daemon, especially if #MHD_USE_AUTO was set. + */ + MHD_DAEMON_INFO_FLAGS +}; + + +/** + * Callback for serious error condition. The default action is to print + * an error message and `abort()`. + * + * @param cls user specified value + * @param file where the error occured + * @param line where the error occured + * @param reason error detail, may be NULL + * @ingroup logging + */ +typedef void +(*MHD_PanicCallback) (void *cls, + const char *file, + unsigned int line, + const char *reason); + +/** + * Allow or deny a client to connect. + * + * @param cls closure + * @param addr address information from the client + * @param addrlen length of @a addr + * @return #MHD_YES if connection is allowed, #MHD_NO if not + */ +typedef int +(*MHD_AcceptPolicyCallback) (void *cls, + const struct sockaddr *addr, + socklen_t addrlen); + + +/** + * A client has requested the given url using the given method + * (#MHD_HTTP_METHOD_GET, #MHD_HTTP_METHOD_PUT, + * #MHD_HTTP_METHOD_DELETE, #MHD_HTTP_METHOD_POST, etc). The callback + * must call MHD callbacks to provide content to give back to the + * client and return an HTTP status code (i.e. #MHD_HTTP_OK, + * #MHD_HTTP_NOT_FOUND, etc.). + * + * @param cls argument given together with the function + * pointer when the handler was registered with MHD + * @param url the requested url + * @param method the HTTP method used (#MHD_HTTP_METHOD_GET, + * #MHD_HTTP_METHOD_PUT, etc.) + * @param version the HTTP version string (i.e. + * #MHD_HTTP_VERSION_1_1) + * @param upload_data the data being uploaded (excluding HEADERS, + * for a POST that fits into memory and that is encoded + * with a supported encoding, the POST data will NOT be + * given in upload_data and is instead available as + * part of #MHD_get_connection_values; very large POST + * data *will* be made available incrementally in + * @a upload_data) + * @param upload_data_size set initially to the size of the + * @a upload_data provided; the method must update this + * value to the number of bytes NOT processed; + * @param con_cls pointer that the callback can set to some + * address and that will be preserved by MHD for future + * calls for this request; since the access handler may + * be called many times (i.e., for a PUT/POST operation + * with plenty of upload data) this allows the application + * to easily associate some request-specific state. + * If necessary, this state can be cleaned up in the + * global #MHD_RequestCompletedCallback (which + * can be set with the #MHD_OPTION_NOTIFY_COMPLETED). + * Initially, `*con_cls` will be NULL. + * @return #MHD_YES if the connection was handled successfully, + * #MHD_NO if the socket must be closed due to a serios + * error while handling the request + */ +typedef int +(*MHD_AccessHandlerCallback) (void *cls, + struct MHD_Connection *connection, + const char *url, + const char *method, + const char *version, + const char *upload_data, + size_t *upload_data_size, + void **con_cls); + + +/** + * Signature of the callback used by MHD to notify the + * application about completed requests. + * + * @param cls client-defined closure + * @param connection connection handle + * @param con_cls value as set by the last call to + * the #MHD_AccessHandlerCallback + * @param toe reason for request termination + * @see #MHD_OPTION_NOTIFY_COMPLETED + * @ingroup request + */ +typedef void +(*MHD_RequestCompletedCallback) (void *cls, + struct MHD_Connection *connection, + void **con_cls, + enum MHD_RequestTerminationCode toe); + +/** + * Signature of the callback used by MHD to notify the + * application about started/stopped connections + * + * @param cls client-defined closure + * @param connection connection handle + * @param socket_context socket-specific pointer where the + * client can associate some state specific + * to the TCP connection; note that this is + * different from the "con_cls" which is per + * HTTP request. The client can initialize + * during #MHD_CONNECTION_NOTIFY_STARTED and + * cleanup during #MHD_CONNECTION_NOTIFY_CLOSED + * and access in the meantime using + * #MHD_CONNECTION_INFO_SOCKET_CONTEXT. + * @param toe reason for connection notification + * @see #MHD_OPTION_NOTIFY_CONNECTION + * @ingroup request + */ +typedef void +(*MHD_NotifyConnectionCallback) (void *cls, + struct MHD_Connection *connection, + void **socket_context, + enum MHD_ConnectionNotificationCode toe); + + +/** + * Iterator over key-value pairs. This iterator + * can be used to iterate over all of the cookies, + * headers, or POST-data fields of a request, and + * also to iterate over the headers that have been + * added to a response. + * + * @param cls closure + * @param kind kind of the header we are looking at + * @param key key for the value, can be an empty string + * @param value corresponding value, can be NULL + * @return #MHD_YES to continue iterating, + * #MHD_NO to abort the iteration + * @ingroup request + */ +typedef int +(*MHD_KeyValueIterator) (void *cls, + enum MHD_ValueKind kind, + const char *key, + const char *value); + + +/** + * Callback used by libmicrohttpd in order to obtain content. The + * callback is to copy at most @a max bytes of content into @a buf. The + * total number of bytes that has been placed into @a buf should be + * returned. + * + * Note that returning zero will cause libmicrohttpd to try again. + * Thus, returning zero should only be used in conjunction + * with MHD_suspend_connection() to avoid busy waiting. + * + * @param cls extra argument to the callback + * @param pos position in the datastream to access; + * note that if a `struct MHD_Response` object is re-used, + * it is possible for the same content reader to + * be queried multiple times for the same data; + * however, if a `struct MHD_Response` is not re-used, + * libmicrohttpd guarantees that "pos" will be + * the sum of all non-negative return values + * obtained from the content reader so far. + * @param buf where to copy the data + * @param max maximum number of bytes to copy to @a buf (size of @a buf) + * @return number of bytes written to @a buf; + * 0 is legal unless we are running in internal select mode (since + * this would cause busy-waiting); 0 in external select mode + * will cause this function to be called again once the external + * select calls MHD again; + * #MHD_CONTENT_READER_END_OF_STREAM (-1) for the regular + * end of transmission (with chunked encoding, MHD will then + * terminate the chunk and send any HTTP footers that might be + * present; without chunked encoding and given an unknown + * response size, MHD will simply close the connection; note + * that while returning #MHD_CONTENT_READER_END_OF_STREAM is not technically + * legal if a response size was specified, MHD accepts this + * and treats it just as #MHD_CONTENT_READER_END_WITH_ERROR; + * #MHD_CONTENT_READER_END_WITH_ERROR (-2) to indicate a server + * error generating the response; this will cause MHD to simply + * close the connection immediately. If a response size was + * given or if chunked encoding is in use, this will indicate + * an error to the client. Note, however, that if the client + * does not know a response size and chunked encoding is not in + * use, then clients will not be able to tell the difference between + * #MHD_CONTENT_READER_END_WITH_ERROR and #MHD_CONTENT_READER_END_OF_STREAM. + * This is not a limitation of MHD but rather of the HTTP protocol. + */ +typedef ssize_t +(*MHD_ContentReaderCallback) (void *cls, + uint64_t pos, + char *buf, + size_t max); + + +/** + * This method is called by libmicrohttpd if we + * are done with a content reader. It should + * be used to free resources associated with the + * content reader. + * + * @param cls closure + * @ingroup response + */ +typedef void +(*MHD_ContentReaderFreeCallback) (void *cls); + + +/** + * Iterator over key-value pairs where the value + * maybe made available in increments and/or may + * not be zero-terminated. Used for processing + * POST data. + * + * @param cls user-specified closure + * @param kind type of the value, always #MHD_POSTDATA_KIND when called from MHD + * @param key 0-terminated key for the value + * @param filename name of the uploaded file, NULL if not known + * @param content_type mime-type of the data, NULL if not known + * @param transfer_encoding encoding of the data, NULL if not known + * @param data pointer to @a size bytes of data at the + * specified offset + * @param off offset of data in the overall value + * @param size number of bytes in @a data available + * @return #MHD_YES to continue iterating, + * #MHD_NO to abort the iteration + */ +typedef int +(*MHD_PostDataIterator) (void *cls, + enum MHD_ValueKind kind, + const char *key, + const char *filename, + const char *content_type, + const char *transfer_encoding, + const char *data, + uint64_t off, + size_t size); + +/* **************** Daemon handling functions ***************** */ + +/** + * Start a webserver on the given port. + * + * @param flags combination of `enum MHD_FLAG` values + * @param port port to bind to (in host byte order) + * @param apc callback to call to check which clients + * will be allowed to connect; you can pass NULL + * in which case connections from any IP will be + * accepted + * @param apc_cls extra argument to apc + * @param dh handler called for all requests (repeatedly) + * @param dh_cls extra argument to @a dh + * @param ap list of options (type-value pairs, + * terminated with #MHD_OPTION_END). + * @return NULL on error, handle to daemon on success + * @ingroup event + */ +_MHD_EXTERN struct MHD_Daemon * +MHD_start_daemon_va (unsigned int flags, + uint16_t port, + MHD_AcceptPolicyCallback apc, void *apc_cls, + MHD_AccessHandlerCallback dh, void *dh_cls, + va_list ap); + + +/** + * Start a webserver on the given port. Variadic version of + * #MHD_start_daemon_va. + * + * @param flags combination of `enum MHD_FLAG` values + * @param port port to bind to + * @param apc callback to call to check which clients + * will be allowed to connect; you can pass NULL + * in which case connections from any IP will be + * accepted + * @param apc_cls extra argument to apc + * @param dh handler called for all requests (repeatedly) + * @param dh_cls extra argument to @a dh + * @return NULL on error, handle to daemon on success + * @ingroup event + */ +_MHD_EXTERN struct MHD_Daemon * +MHD_start_daemon (unsigned int flags, + uint16_t port, + MHD_AcceptPolicyCallback apc, void *apc_cls, + MHD_AccessHandlerCallback dh, void *dh_cls, + ...); + + +/** + * Stop accepting connections from the listening socket. Allows + * clients to continue processing, but stops accepting new + * connections. Note that the caller is responsible for closing the + * returned socket; however, if MHD is run using threads (anything but + * external select mode), it must not be closed until AFTER + * #MHD_stop_daemon has been called (as it is theoretically possible + * that an existing thread is still using it). + * + * Note that some thread modes require the caller to have passed + * #MHD_USE_ITC when using this API. If this daemon is + * in one of those modes and this option was not given to + * #MHD_start_daemon, this function will return #MHD_INVALID_SOCKET. + * + * @param daemon daemon to stop accepting new connections for + * @return old listen socket on success, #MHD_INVALID_SOCKET if + * the daemon was already not listening anymore + * @ingroup specialized + */ +_MHD_EXTERN MHD_socket +MHD_quiesce_daemon (struct MHD_Daemon *daemon); + + +/** + * Shutdown an HTTP daemon. + * + * @param daemon daemon to stop + * @ingroup event + */ +_MHD_EXTERN void +MHD_stop_daemon (struct MHD_Daemon *daemon); + + +/** + * Add another client connection to the set of connections managed by + * MHD. This API is usually not needed (since MHD will accept inbound + * connections on the server socket). Use this API in special cases, + * for example if your HTTP server is behind NAT and needs to connect + * out to the HTTP client, or if you are building a proxy. + * + * If you use this API in conjunction with a internal select or a + * thread pool, you must set the option + * #MHD_USE_ITC to ensure that the freshly added + * connection is immediately processed by MHD. + * + * The given client socket will be managed (and closed!) by MHD after + * this call and must no longer be used directly by the application + * afterwards. + * + * Per-IP connection limits are ignored when using this API. + * + * @param daemon daemon that manages the connection + * @param client_socket socket to manage (MHD will expect + * to receive an HTTP request from this socket next). + * @param addr IP address of the client + * @param addrlen number of bytes in @a addr + * @return #MHD_YES on success, #MHD_NO if this daemon could + * not handle the connection (i.e. `malloc()` failed, etc). + * The socket will be closed in any case; `errno` is + * set to indicate further details about the error. + * @ingroup specialized + */ +_MHD_EXTERN int +MHD_add_connection (struct MHD_Daemon *daemon, + MHD_socket client_socket, + const struct sockaddr *addr, + socklen_t addrlen); + + +/** + * Obtain the `select()` sets for this daemon. + * Daemon's FDs will be added to fd_sets. To get only + * daemon FDs in fd_sets, call FD_ZERO for each fd_set + * before calling this function. FD_SETSIZE is assumed + * to be platform's default. + * + * This function should only be called in when MHD is configured to + * use external select with @code{select()} or with @code{epoll()}. + * In the latter case, it will only add the single @code{epoll()} file + * descriptor used by MHD to the sets. + * + * This function must be called only for daemon started + * without #MHD_USE_INTERNAL_POLLING_THREAD flag. + * + * @param daemon daemon to get sets from + * @param read_fd_set read set + * @param write_fd_set write set + * @param except_fd_set except set + * @param max_fd increased to largest FD added (if larger + * than existing value); can be NULL + * @return #MHD_YES on success, #MHD_NO if this + * daemon was not started with the right + * options for this call or any FD didn't + * fit fd_set. + * @ingroup event + */ +_MHD_EXTERN int +MHD_get_fdset (struct MHD_Daemon *daemon, + fd_set *read_fd_set, + fd_set *write_fd_set, + fd_set *except_fd_set, + MHD_socket *max_fd); + + +/** + * Obtain the `select()` sets for this daemon. + * Daemon's FDs will be added to fd_sets. To get only + * daemon FDs in fd_sets, call FD_ZERO for each fd_set + * before calling this function. + * + * Passing custom FD_SETSIZE as @a fd_setsize allow usage of + * larger/smaller than platform's default fd_sets. + * + * This function should only be called in when MHD is configured to + * use external select with @code{select()} or with @code{epoll()}. + * In the latter case, it will only add the single @code{epoll()} file + * descriptor used by MHD to the sets. + * + * This function must be called only for daemon started + * without #MHD_USE_INTERNAL_POLLING_THREAD flag. + * + * @param daemon daemon to get sets from + * @param read_fd_set read set + * @param write_fd_set write set + * @param except_fd_set except set + * @param max_fd increased to largest FD added (if larger + * than existing value); can be NULL + * @param fd_setsize value of FD_SETSIZE + * @return #MHD_YES on success, #MHD_NO if this + * daemon was not started with the right + * options for this call or any FD didn't + * fit fd_set. + * @ingroup event + */ +_MHD_EXTERN int +MHD_get_fdset2 (struct MHD_Daemon *daemon, + fd_set *read_fd_set, + fd_set *write_fd_set, + fd_set *except_fd_set, + MHD_socket *max_fd, + unsigned int fd_setsize); + + +/** + * Obtain the `select()` sets for this daemon. + * Daemon's FDs will be added to fd_sets. To get only + * daemon FDs in fd_sets, call FD_ZERO for each fd_set + * before calling this function. Size of fd_set is + * determined by current value of FD_SETSIZE. + * + * This function could be called only for daemon started + * without #MHD_USE_INTERNAL_POLLING_THREAD flag. + * + * @param daemon daemon to get sets from + * @param read_fd_set read set + * @param write_fd_set write set + * @param except_fd_set except set + * @param max_fd increased to largest FD added (if larger + * than existing value); can be NULL + * @return #MHD_YES on success, #MHD_NO if this + * daemon was not started with the right + * options for this call or any FD didn't + * fit fd_set. + * @ingroup event + */ +#define MHD_get_fdset(daemon,read_fd_set,write_fd_set,except_fd_set,max_fd) \ + MHD_get_fdset2((daemon),(read_fd_set),(write_fd_set),(except_fd_set),(max_fd),FD_SETSIZE) + + +/** + * Obtain timeout value for `select()` for this daemon (only needed if + * connection timeout is used). The returned value is how many milliseconds + * `select()` or `poll()` should at most block, not the timeout value set for + * connections. This function MUST NOT be called if MHD is running with + * #MHD_USE_THREAD_PER_CONNECTION. + * + * @param daemon daemon to query for timeout + * @param timeout set to the timeout (in milliseconds) + * @return #MHD_YES on success, #MHD_NO if timeouts are + * not used (or no connections exist that would + * necessiate the use of a timeout right now). + * @ingroup event + */ +_MHD_EXTERN int +MHD_get_timeout (struct MHD_Daemon *daemon, + MHD_UNSIGNED_LONG_LONG *timeout); + + +/** + * Run webserver operations (without blocking unless in client + * callbacks). This method should be called by clients in combination + * with #MHD_get_fdset if the client-controlled select method is used. + * + * This function is a convenience method, which is useful if the + * fd_sets from #MHD_get_fdset were not directly passed to `select()`; + * with this function, MHD will internally do the appropriate `select()` + * call itself again. While it is always safe to call #MHD_run (if + * #MHD_USE_INTERNAL_POLLING_THREAD is not set), you should call + * #MHD_run_from_select if performance is important (as it saves an + * expensive call to `select()`). + * + * @param daemon daemon to run + * @return #MHD_YES on success, #MHD_NO if this + * daemon was not started with the right + * options for this call. + * @ingroup event + */ +_MHD_EXTERN int +MHD_run (struct MHD_Daemon *daemon); + + +/** + * Run webserver operations. This method should be called by clients + * in combination with #MHD_get_fdset if the client-controlled select + * method is used. + * + * You can use this function instead of #MHD_run if you called + * `select()` on the result from #MHD_get_fdset. File descriptors in + * the sets that are not controlled by MHD will be ignored. Calling + * this function instead of #MHD_run is more efficient as MHD will + * not have to call `select()` again to determine which operations are + * ready. + * + * This function cannot be used with daemon started with + * #MHD_USE_INTERNAL_POLLING_THREAD flag. + * + * @param daemon daemon to run select loop for + * @param read_fd_set read set + * @param write_fd_set write set + * @param except_fd_set except set + * @return #MHD_NO on serious errors, #MHD_YES on success + * @ingroup event + */ +_MHD_EXTERN int +MHD_run_from_select (struct MHD_Daemon *daemon, + const fd_set *read_fd_set, + const fd_set *write_fd_set, + const fd_set *except_fd_set); + + + + +/* **************** Connection handling functions ***************** */ + +/** + * Get all of the headers from the request. + * + * @param connection connection to get values from + * @param kind types of values to iterate over, can be a bitmask + * @param iterator callback to call on each header; + * maybe NULL (then just count headers) + * @param iterator_cls extra argument to @a iterator + * @return number of entries iterated over + * @ingroup request + */ +_MHD_EXTERN int +MHD_get_connection_values (struct MHD_Connection *connection, + enum MHD_ValueKind kind, + MHD_KeyValueIterator iterator, + void *iterator_cls); + + +/** + * This function can be used to add an entry to the HTTP headers of a + * connection (so that the #MHD_get_connection_values function will + * return them -- and the `struct MHD_PostProcessor` will also see + * them). This maybe required in certain situations (see Mantis + * #1399) where (broken) HTTP implementations fail to supply values + + * needed by the post processor (or other parts of the application). + * + * This function MUST only be called from within the + * #MHD_AccessHandlerCallback (otherwise, access maybe improperly + * synchronized). Furthermore, the client must guarantee that the key + * and value arguments are 0-terminated strings that are NOT freed + * until the connection is closed. (The easiest way to do this is by + * passing only arguments to permanently allocated strings.). + * + * @param connection the connection for which a + * value should be set + * @param kind kind of the value + * @param key key for the value + * @param value the value itself + * @return #MHD_NO if the operation could not be + * performed due to insufficient memory; + * #MHD_YES on success + * @ingroup request + */ +_MHD_EXTERN int +MHD_set_connection_value (struct MHD_Connection *connection, + enum MHD_ValueKind kind, + const char *key, + const char *value); + + +/** + * Sets the global error handler to a different implementation. @a cb + * will only be called in the case of typically fatal, serious + * internal consistency issues. These issues should only arise in the + * case of serious memory corruption or similar problems with the + * architecture. While @a cb is allowed to return and MHD will then + * try to continue, this is never safe. + * + * The default implementation that is used if no panic function is set + * simply prints an error message and calls `abort()`. Alternative + * implementations might call `exit()` or other similar functions. + * + * @param cb new error handler + * @param cls passed to @a cb + * @ingroup logging + */ +_MHD_EXTERN void +MHD_set_panic_func (MHD_PanicCallback cb, void *cls); + + +/** + * Process escape sequences ('%HH') Updates val in place; the + * result should be UTF-8 encoded and cannot be larger than the input. + * The result must also still be 0-terminated. + * + * @param val value to unescape (modified in the process) + * @return length of the resulting val (`strlen(val)` may be + * shorter afterwards due to elimination of escape sequences) + */ +_MHD_EXTERN size_t +MHD_http_unescape (char *val); + + +/** + * Get a particular header value. If multiple + * values match the kind, return any one of them. + * + * @param connection connection to get values from + * @param kind what kind of value are we looking for + * @param key the header to look for, NULL to lookup 'trailing' value without a key + * @return NULL if no such item was found + * @ingroup request + */ +_MHD_EXTERN const char * +MHD_lookup_connection_value (struct MHD_Connection *connection, + enum MHD_ValueKind kind, + const char *key); + + +/** + * Queue a response to be transmitted to the client (as soon as + * possible but after #MHD_AccessHandlerCallback returns). + * + * @param connection the connection identifying the client + * @param status_code HTTP status code (i.e. #MHD_HTTP_OK) + * @param response response to transmit + * @return #MHD_NO on error (i.e. reply already sent), + * #MHD_YES on success or if message has been queued + * @ingroup response + */ +_MHD_EXTERN int +MHD_queue_response (struct MHD_Connection *connection, + unsigned int status_code, + struct MHD_Response *response); + + +/** + * Suspend handling of network data for a given connection. This can + * be used to dequeue a connection from MHD's event loop for a while. + * + * If you use this API in conjunction with a internal select or a + * thread pool, you must set the option #MHD_USE_ITC to + * ensure that a resumed connection is immediately processed by MHD. + * + * Suspended connections continue to count against the total number of + * connections allowed (per daemon, as well as per IP, if such limits + * are set). Suspended connections will NOT time out; timeouts will + * restart when the connection handling is resumed. While a + * connection is suspended, MHD will not detect disconnects by the + * client. + * + * The only safe time to suspend a connection is from the + * #MHD_AccessHandlerCallback. + * + * Finally, it is an API violation to call #MHD_stop_daemon while + * having suspended connections (this will at least create memory and + * socket leaks or lead to undefined behavior). You must explicitly + * resume all connections before stopping the daemon. + * + * @param connection the connection to suspend + */ +_MHD_EXTERN void +MHD_suspend_connection (struct MHD_Connection *connection); + + +/** + * Resume handling of network data for suspended connection. It is + * safe to resume a suspended connection at any time. Calling this + * function on a connection that was not previously suspended will + * result in undefined behavior. + * + * If you are using this function in ``external'' select mode, you must + * make sure to run #MHD_run() afterwards (before again calling + * #MHD_get_fdset(), as otherwise the change may not be reflected in + * the set returned by #MHD_get_fdset() and you may end up with a + * connection that is stuck until the next network activity. + * + * @param connection the connection to resume + */ +_MHD_EXTERN void +MHD_resume_connection (struct MHD_Connection *connection); + + +/* **************** Response manipulation functions ***************** */ + + +/** + * Flags for special handling of responses. + */ +enum MHD_ResponseFlags +{ + /** + * Default: no special flags. + */ + MHD_RF_NONE = 0, + + /** + * Only respond in conservative HTTP 1.0-mode. In particular, + * do not (automatically) sent "Connection" headers and always + * close the connection after generating the response. + */ + MHD_RF_HTTP_VERSION_1_0_ONLY = 1 + +}; + + +/** + * MHD options (for future extensions). + */ +enum MHD_ResponseOptions +{ + /** + * End of the list of options. + */ + MHD_RO_END = 0 +}; + + +/** + * Set special flags and options for a response. + * + * @param response the response to modify + * @param flags to set for the response + * @param ... #MHD_RO_END terminated list of options + * @return #MHD_YES on success, #MHD_NO on error + */ +_MHD_EXTERN int +MHD_set_response_options (struct MHD_Response *response, + enum MHD_ResponseFlags flags, + ...); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response, #MHD_SIZE_UNKNOWN for unknown + * @param block_size preferred block size for querying crc (advisory only, + * MHD may still call @a crc using smaller chunks); this + * is essentially the buffer size used for IO, clients + * should pick a value that is appropriate for IO and + * memory performance requirements + * @param crc callback to use to obtain response data + * @param crc_cls extra argument to @a crc + * @param crfc callback to call to free @a crc_cls resources + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_callback (uint64_t size, + size_t block_size, + MHD_ContentReaderCallback crc, void *crc_cls, + MHD_ContentReaderFreeCallback crfc); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the @a data portion of the response + * @param data the data itself + * @param must_free libmicrohttpd should free data when done + * @param must_copy libmicrohttpd must make a copy of @a data + * right away, the data maybe released anytime after + * this call returns + * @return NULL on error (i.e. invalid arguments, out of memory) + * @deprecated use #MHD_create_response_from_buffer instead + * @ingroup response + */ +_MHD_DEPR_FUNC("MHD_create_response_from_data() is deprecated, use MHD_create_response_from_buffer()") \ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_data (size_t size, + void *data, + int must_free, + int must_copy); + + +/** + * Specification for how MHD should treat the memory buffer + * given for the response. + * @ingroup response + */ +enum MHD_ResponseMemoryMode +{ + + /** + * Buffer is a persistent (static/global) buffer that won't change + * for at least the lifetime of the response, MHD should just use + * it, not free it, not copy it, just keep an alias to it. + * @ingroup response + */ + MHD_RESPMEM_PERSISTENT, + + /** + * Buffer is heap-allocated with `malloc()` (or equivalent) and + * should be freed by MHD after processing the response has + * concluded (response reference counter reaches zero). + * @ingroup response + */ + MHD_RESPMEM_MUST_FREE, + + /** + * Buffer is in transient memory, but not on the heap (for example, + * on the stack or non-`malloc()` allocated) and only valid during the + * call to #MHD_create_response_from_buffer. MHD must make its + * own private copy of the data for processing. + * @ingroup response + */ + MHD_RESPMEM_MUST_COPY + +}; + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response + * @param buffer size bytes containing the response's data portion + * @param mode flags for buffer management + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_buffer (size_t size, + void *buffer, + enum MHD_ResponseMemoryMode mode); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response + * @param fd file descriptor referring to a file on disk with the + * data; will be closed when response is destroyed; + * fd should be in 'blocking' mode + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_fd (size_t size, + int fd); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response; + * sizes larger than 2 GiB may be not supported by OS or + * MHD build; see ::MHD_FEATURE_LARGE_FILE + * @param fd file descriptor referring to a file on disk with the + * data; will be closed when response is destroyed; + * fd should be in 'blocking' mode + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_fd64 (uint64_t size, + int fd); + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response + * @param fd file descriptor referring to a file on disk with the + * data; will be closed when response is destroyed; + * fd should be in 'blocking' mode + * @param offset offset to start reading from in the file; + * Be careful! `off_t` may have been compiled to be a + * 64-bit variable for MHD, in which case your application + * also has to be compiled using the same options! Read + * the MHD manual for more details. + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_DEPR_FUNC("Function MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()") \ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_fd_at_offset (size_t size, + int fd, + off_t offset); + +#if !defined(_MHD_NO_DEPR_IN_MACRO) || defined(_MHD_NO_DEPR_FUNC) +/* Substitute MHD_create_response_from_fd_at_offset64() instead of MHD_create_response_from_fd_at_offset() + to minimize potential problems with different off_t sizes */ +#define MHD_create_response_from_fd_at_offset(size,fd,offset) \ + _MHD_DEPR_IN_MACRO("Usage of MHD_create_response_from_fd_at_offset() is deprecated, use MHD_create_response_from_fd_at_offset64()") \ + MHD_create_response_from_fd_at_offset64((size),(fd),(offset)) +#endif /* !_MHD_NO_DEPR_IN_MACRO || _MHD_NO_DEPR_FUNC */ + + +/** + * Create a response object. The response object can be extended with + * header information and then be used any number of times. + * + * @param size size of the data portion of the response; + * sizes larger than 2 GiB may be not supported by OS or + * MHD build; see ::MHD_FEATURE_LARGE_FILE + * @param fd file descriptor referring to a file on disk with the + * data; will be closed when response is destroyed; + * fd should be in 'blocking' mode + * @param offset offset to start reading from in the file; + * reading file beyond 2 GiB may be not supported by OS or + * MHD build; see ::MHD_FEATURE_LARGE_FILE + * @return NULL on error (i.e. invalid arguments, out of memory) + * @ingroup response + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_from_fd_at_offset64 (uint64_t size, + int fd, + uint64_t offset); + + +/** + * Enumeration for actions MHD should perform on the underlying socket + * of the upgrade. This API is not finalized, and in particular + * the final set of actions is yet to be decided. This is just an + * idea for what we might want. + */ +enum MHD_UpgradeAction +{ + + /** + * Close the socket, the application is done with it. + * + * Takes no extra arguments. + */ + MHD_UPGRADE_ACTION_CLOSE = 0 + +}; + + +/** + * Handle given to the application to manage special + * actions relating to MHD responses that "upgrade" + * the HTTP protocol (i.e. to WebSockets). + */ +struct MHD_UpgradeResponseHandle; + + +/** + * This connection-specific callback is provided by MHD to + * applications (unusual) during the #MHD_UpgradeHandler. + * It allows applications to perform 'special' actions on + * the underlying socket from the upgrade. + * + * @param urh the handle identifying the connection to perform + * the upgrade @a action on. + * @param action which action should be performed + * @param ... arguments to the action (depends on the action) + * @return #MHD_NO on error, #MHD_YES on success + */ +_MHD_EXTERN int +MHD_upgrade_action (struct MHD_UpgradeResponseHandle *urh, + enum MHD_UpgradeAction action, + ...); + + +/** + * Function called after a protocol "upgrade" response was sent + * successfully and the socket should now be controlled by some + * protocol other than HTTP. + * + * Any data already received on the socket will be made available in + * @e extra_in. This can happen if the application sent extra data + * before MHD send the upgrade response. The application should + * treat data from @a extra_in as if it had read it from the socket. + * + * Note that the application must not close() @a sock directly, + * but instead use #MHD_upgrade_action() for special operations + * on @a sock. + * + * Data forwarding to "upgraded" @a sock will be started as soon + * as this function return. + * + * Except when in 'thread-per-connection' mode, implementations + * of this function should never block (as it will still be called + * from within the main event loop). + * + * @param cls closure, whatever was given to #MHD_create_response_for_upgrade(). + * @param connection original HTTP connection handle, + * giving the function a last chance + * to inspect the original HTTP request + * @param con_cls last value left in `con_cls` of the `MHD_AccessHandlerCallback` + * @param extra_in if we happened to have read bytes after the + * HTTP header already (because the client sent + * more than the HTTP header of the request before + * we sent the upgrade response), + * these are the extra bytes already read from @a sock + * by MHD. The application should treat these as if + * it had read them from @a sock. + * @param extra_in_size number of bytes in @a extra_in + * @param sock socket to use for bi-directional communication + * with the client. For HTTPS, this may not be a socket + * that is directly connected to the client and thus certain + * operations (TCP-specific setsockopt(), getsockopt(), etc.) + * may not work as expected (as the socket could be from a + * socketpair() or a TCP-loopback). The application is expected + * to perform read()/recv() and write()/send() calls on the socket. + * The application may also call shutdown(), but must not call + * close() directly. + * @param urh argument for #MHD_upgrade_action()s on this @a connection. + * Applications must eventually use this callback to (indirectly) + * perform the close() action on the @a sock. + */ +typedef void +(*MHD_UpgradeHandler)(void *cls, + struct MHD_Connection *connection, + void *con_cls, + const char *extra_in, + size_t extra_in_size, + MHD_socket sock, + struct MHD_UpgradeResponseHandle *urh); + + +/** + * Create a response object that can be used for 101 UPGRADE + * responses, for example to implement WebSockets. After sending the + * response, control over the data stream is given to the callback (which + * can then, for example, start some bi-directional communication). + * If the response is queued for multiple connections, the callback + * will be called for each connection. The callback + * will ONLY be called after the response header was successfully passed + * to the OS; if there are communication errors before, the usual MHD + * connection error handling code will be performed. + * + * Setting the correct HTTP code (i.e. MHD_HTTP_SWITCHING_PROTOCOLS) + * and setting correct HTTP headers for the upgrade must be done + * manually (this way, it is possible to implement most existing + * WebSocket versions using this API; in fact, this API might be useful + * for any protocol switch, not just WebSockets). Note that + * draft-ietf-hybi-thewebsocketprotocol-00 cannot be implemented this + * way as the header "HTTP/1.1 101 WebSocket Protocol Handshake" + * cannot be generated; instead, MHD will always produce "HTTP/1.1 101 + * Switching Protocols" (if the response code 101 is used). + * + * As usual, the response object can be extended with header + * information and then be used any number of times (as long as the + * header information is not connection-specific). + * + * @param upgrade_handler function to call with the "upgraded" socket + * @param upgrade_handler_cls closure for @a upgrade_handler + * @return NULL on error (i.e. invalid arguments, out of memory) + */ +_MHD_EXTERN struct MHD_Response * +MHD_create_response_for_upgrade (MHD_UpgradeHandler upgrade_handler, + void *upgrade_handler_cls); + + +/** + * Destroy a response object and associated resources. Note that + * libmicrohttpd may keep some of the resources around if the response + * is still in the queue for some clients, so the memory may not + * necessarily be freed immediatley. + * + * @param response response to destroy + * @ingroup response + */ +_MHD_EXTERN void +MHD_destroy_response (struct MHD_Response *response); + + +/** + * Add a header line to the response. + * + * @param response response to add a header to + * @param header the header to add + * @param content value to add + * @return #MHD_NO on error (i.e. invalid header or content format), + * or out of memory + * @ingroup response + */ +_MHD_EXTERN int +MHD_add_response_header (struct MHD_Response *response, + const char *header, + const char *content); + + +/** + * Add a footer line to the response. + * + * @param response response to remove a header from + * @param footer the footer to delete + * @param content value to delete + * @return #MHD_NO on error (i.e. invalid footer or content format). + * @ingroup response + */ +_MHD_EXTERN int +MHD_add_response_footer (struct MHD_Response *response, + const char *footer, + const char *content); + + +/** + * Delete a header (or footer) line from the response. + * + * @param response response to remove a header from + * @param header the header to delete + * @param content value to delete + * @return #MHD_NO on error (no such header known) + * @ingroup response + */ +_MHD_EXTERN int +MHD_del_response_header (struct MHD_Response *response, + const char *header, + const char *content); + + +/** + * Get all of the headers (and footers) added to a response. + * + * @param response response to query + * @param iterator callback to call on each header; + * maybe NULL (then just count headers) + * @param iterator_cls extra argument to @a iterator + * @return number of entries iterated over + * @ingroup response + */ +_MHD_EXTERN int +MHD_get_response_headers (struct MHD_Response *response, + MHD_KeyValueIterator iterator, void *iterator_cls); + + +/** + * Get a particular header (or footer) from the response. + * + * @param response response to query + * @param key which header to get + * @return NULL if header does not exist + * @ingroup response + */ +_MHD_EXTERN const char * +MHD_get_response_header (struct MHD_Response *response, + const char *key); + + +/* ********************** PostProcessor functions ********************** */ + +/** + * Create a `struct MHD_PostProcessor`. + * + * A `struct MHD_PostProcessor` can be used to (incrementally) parse + * the data portion of a POST request. Note that some buggy browsers + * fail to set the encoding type. If you want to support those, you + * may have to call #MHD_set_connection_value with the proper encoding + * type before creating a post processor (if no supported encoding + * type is set, this function will fail). + * + * @param connection the connection on which the POST is + * happening (used to determine the POST format) + * @param buffer_size maximum number of bytes to use for + * internal buffering (used only for the parsing, + * specifically the parsing of the keys). A + * tiny value (256-1024) should be sufficient. + * Do NOT use a value smaller than 256. For good + * performance, use 32 or 64k (i.e. 65536). + * @param iter iterator to be called with the parsed data, + * Must NOT be NULL. + * @param iter_cls first argument to @a iter + * @return NULL on error (out of memory, unsupported encoding), + * otherwise a PP handle + * @ingroup request + */ +_MHD_EXTERN struct MHD_PostProcessor * +MHD_create_post_processor (struct MHD_Connection *connection, + size_t buffer_size, + MHD_PostDataIterator iter, void *iter_cls); + + +/** + * Parse and process POST data. Call this function when POST data is + * available (usually during an #MHD_AccessHandlerCallback) with the + * "upload_data" and "upload_data_size". Whenever possible, this will + * then cause calls to the #MHD_PostDataIterator. + * + * @param pp the post processor + * @param post_data @a post_data_len bytes of POST data + * @param post_data_len length of @a post_data + * @return #MHD_YES on success, #MHD_NO on error + * (out-of-memory, iterator aborted, parse error) + * @ingroup request + */ +_MHD_EXTERN int +MHD_post_process (struct MHD_PostProcessor *pp, + const char *post_data, size_t post_data_len); + + +/** + * Release PostProcessor resources. + * + * @param pp the PostProcessor to destroy + * @return #MHD_YES if processing completed nicely, + * #MHD_NO if there were spurious characters / formatting + * problems; it is common to ignore the return + * value of this function + * @ingroup request + */ +_MHD_EXTERN int +MHD_destroy_post_processor (struct MHD_PostProcessor *pp); + + +/* ********************* Digest Authentication functions *************** */ + + +/** + * Constant to indicate that the nonce of the provided + * authentication code was wrong. + * @ingroup authentication + */ +#define MHD_INVALID_NONCE -1 + + +/** + * Get the username from the authorization header sent by the client + * + * @param connection The MHD connection structure + * @return NULL if no username could be found, a pointer + * to the username if found + * @ingroup authentication + */ +_MHD_EXTERN char * +MHD_digest_auth_get_username (struct MHD_Connection *connection); + + +/** + * Authenticates the authorization header sent by the client + * + * @param connection The MHD connection structure + * @param realm The realm presented to the client + * @param username The username needs to be authenticated + * @param password The password used in the authentication + * @param nonce_timeout The amount of time for a nonce to be + * invalid in seconds + * @return #MHD_YES if authenticated, #MHD_NO if not, + * #MHD_INVALID_NONCE if nonce is invalid + * @ingroup authentication + */ +_MHD_EXTERN int +MHD_digest_auth_check (struct MHD_Connection *connection, + const char *realm, + const char *username, + const char *password, + unsigned int nonce_timeout); + + +/** + * Queues a response to request authentication from the client + * + * @param connection The MHD connection structure + * @param realm The realm presented to the client + * @param opaque string to user for opaque value + * @param response reply to send; should contain the "access denied" + * body; note that this function will set the "WWW Authenticate" + * header and that the caller should not do this + * @param signal_stale #MHD_YES if the nonce is invalid to add + * 'stale=true' to the authentication header + * @return #MHD_YES on success, #MHD_NO otherwise + * @ingroup authentication + */ +_MHD_EXTERN int +MHD_queue_auth_fail_response (struct MHD_Connection *connection, + const char *realm, + const char *opaque, + struct MHD_Response *response, + int signal_stale); + + +/** + * Get the username and password from the basic authorization header sent by the client + * + * @param connection The MHD connection structure + * @param password a pointer for the password + * @return NULL if no username could be found, a pointer + * to the username if found + * @ingroup authentication + */ +_MHD_EXTERN char * +MHD_basic_auth_get_username_password (struct MHD_Connection *connection, + char** password); + + +/** + * Queues a response to request basic authentication from the client + * The given response object is expected to include the payload for + * the response; the "WWW-Authenticate" header will be added and the + * response queued with the 'UNAUTHORIZED' status code. + * + * @param connection The MHD connection structure + * @param realm the realm presented to the client + * @param response response object to modify and queue + * @return #MHD_YES on success, #MHD_NO otherwise + * @ingroup authentication + */ +_MHD_EXTERN int +MHD_queue_basic_auth_fail_response (struct MHD_Connection *connection, + const char *realm, + struct MHD_Response *response); + +/* ********************** generic query functions ********************** */ + + +/** + * Obtain information about the given connection. + * + * @param connection what connection to get information about + * @param info_type what information is desired? + * @param ... depends on @a info_type + * @return NULL if this information is not available + * (or if the @a info_type is unknown) + * @ingroup specialized + */ +_MHD_EXTERN const union MHD_ConnectionInfo * +MHD_get_connection_info (struct MHD_Connection *connection, + enum MHD_ConnectionInfoType info_type, + ...); + + +/** + * MHD connection options. Given to #MHD_set_connection_option to + * set custom options for a particular connection. + */ +enum MHD_CONNECTION_OPTION +{ + + /** + * Set a custom timeout for the given connection. Specified + * as the number of seconds, given as an `unsigned int`. Use + * zero for no timeout. + * If timeout was set to zero (or unset) before, setup of new value by + * MHD_set_connection_option() will reset timeout timer. + */ + MHD_CONNECTION_OPTION_TIMEOUT + +}; + + +/** + * Set a custom option for the given connection, overriding defaults. + * + * @param connection connection to modify + * @param option option to set + * @param ... arguments to the option, depending on the option type + * @return #MHD_YES on success, #MHD_NO if setting the option failed + * @ingroup specialized + */ +_MHD_EXTERN int +MHD_set_connection_option (struct MHD_Connection *connection, + enum MHD_CONNECTION_OPTION option, + ...); + + +/** + * Information about an MHD daemon. + */ +union MHD_DaemonInfo +{ + /** + * Size of the key, no longer supported. + * @deprecated + */ + size_t key_size; + + /** + * Size of the mac key, no longer supported. + * @deprecated + */ + size_t mac_key_size; + + /** + * Socket, returned for #MHD_DAEMON_INFO_LISTEN_FD. + */ + MHD_socket listen_fd; + + /** + * epoll FD, returned for #MHD_DAEMON_INFO_EPOLL_FD. + */ + int epoll_fd; + + /** + * Number of active connections, for #MHD_DAEMON_INFO_CURRENT_CONNECTIONS. + */ + unsigned int num_connections; + + /** + * Combination of #MHD_FLAG values, for #MHD_DAEMON_INFO_FLAGS. + * This value is actually a bitfield. + * Note: flags may differ from original 'flags' specified for + * daemon, especially if #MHD_USE_AUTO was set. + */ + enum MHD_FLAG flags; +}; + + +/** + * Obtain information about the given daemon + * (not fully implemented!). + * + * @param daemon what daemon to get information about + * @param info_type what information is desired? + * @param ... depends on @a info_type + * @return NULL if this information is not available + * (or if the @a info_type is unknown) + * @ingroup specialized + */ +_MHD_EXTERN const union MHD_DaemonInfo * +MHD_get_daemon_info (struct MHD_Daemon *daemon, + enum MHD_DaemonInfoType info_type, + ...); + + +/** + * Obtain the version of this library + * + * @return static version string, e.g. "0.9.9" + * @ingroup specialized + */ +_MHD_EXTERN const char* +MHD_get_version (void); + + +/** + * Types of information about MHD features, + * used by #MHD_is_feature_supported(). + */ +enum MHD_FEATURE +{ + /** + * Get whether messages are supported. If supported then in debug + * mode messages can be printed to stderr or to external logger. + */ + MHD_FEATURE_MESSAGES = 1, + + /** + * Get whether HTTPS is supported. If supported then flag + * #MHD_USE_TLS and options #MHD_OPTION_HTTPS_MEM_KEY, + * #MHD_OPTION_HTTPS_MEM_CERT, #MHD_OPTION_HTTPS_MEM_TRUST, + * #MHD_OPTION_HTTPS_MEM_DHPARAMS, #MHD_OPTION_HTTPS_CRED_TYPE, + * #MHD_OPTION_HTTPS_PRIORITIES can be used. + */ + MHD_FEATURE_TLS = 2, + MHD_FEATURE_SSL = 2, + + /** + * Get whether option #MHD_OPTION_HTTPS_CERT_CALLBACK is + * supported. + */ + MHD_FEATURE_HTTPS_CERT_CALLBACK = 3, + + /** + * Get whether IPv6 is supported. If supported then flag + * #MHD_USE_IPv6 can be used. + */ + MHD_FEATURE_IPv6 = 4, + + /** + * Get whether IPv6 without IPv4 is supported. If not supported + * then IPv4 is always enabled in IPv6 sockets and + * flag #MHD_USE_DUAL_STACK if always used when #MHD_USE_IPv6 is + * specified. + */ + MHD_FEATURE_IPv6_ONLY = 5, + + /** + * Get whether `poll()` is supported. If supported then flag + * #MHD_USE_POLL can be used. + */ + MHD_FEATURE_POLL = 6, + + /** + * Get whether `epoll()` is supported. If supported then Flags + * #MHD_USE_EPOLL and + * #MHD_USE_EPOLL_INTERNAL_THREAD can be used. + */ + MHD_FEATURE_EPOLL = 7, + + /** + * Get whether shutdown on listen socket to signal other + * threads is supported. If not supported flag + * #MHD_USE_ITC is automatically forced. + */ + MHD_FEATURE_SHUTDOWN_LISTEN_SOCKET = 8, + + /** + * Get whether socketpair is used internally instead of pipe to + * signal other threads. + */ + MHD_FEATURE_SOCKETPAIR = 9, + + /** + * Get whether TCP Fast Open is supported. If supported then + * flag #MHD_USE_TCP_FASTOPEN and option + * #MHD_OPTION_TCP_FASTOPEN_QUEUE_SIZE can be used. + */ + MHD_FEATURE_TCP_FASTOPEN = 10, + + /** + * Get whether HTTP Basic authorization is supported. If supported + * then functions #MHD_basic_auth_get_username_password and + * #MHD_queue_basic_auth_fail_response can be used. + */ + MHD_FEATURE_BASIC_AUTH = 11, + + /** + * Get whether HTTP Digest authorization is supported. If + * supported then options #MHD_OPTION_DIGEST_AUTH_RANDOM, + * #MHD_OPTION_NONCE_NC_SIZE and + * #MHD_digest_auth_check() can be used. + */ + MHD_FEATURE_DIGEST_AUTH = 12, + + /** + * Get whether postprocessor is supported. If supported then + * functions #MHD_create_post_processor(), #MHD_post_process() and + * #MHD_destroy_post_processor() can + * be used. + */ + MHD_FEATURE_POSTPROCESSOR = 13, + + /** + * Get whether password encrypted private key for HTTPS daemon is + * supported. If supported then option + * ::MHD_OPTION_HTTPS_KEY_PASSWORD can be used. + */ + MHD_FEATURE_HTTPS_KEY_PASSWORD = 14, + + /** + * Get whether reading files beyond 2 GiB boundary is supported. + * If supported then #MHD_create_response_from_fd(), + * #MHD_create_response_from_fd64 #MHD_create_response_from_fd_at_offset() + * and #MHD_create_response_from_fd_at_offset64() can be used with sizes and + * offsets larger than 2 GiB. If not supported value of size+offset is + * limited to 2 GiB. + */ + MHD_FEATURE_LARGE_FILE = 15, + + /** + * Get whether MHD set names on generated threads. + */ + MHD_FEATURE_THREAD_NAMES = 16, + MHD_THREAD_NAMES = 16, + + /** + * Get whether HTTP "Upgrade" is supported. + * If supported then #MHD_ALLOW_UPGRADE, #MHD_upgrade_action() and + * #MHD_create_response_for_upgrade() can be used. + */ + MHD_FEATURE_UPGRADE = 17, + + /** + * Get whether it's safe to use same FD for multiple calls of + * #MHD_create_response_from_fd() and whether it's safe to use single + * response generated by #MHD_create_response_from_fd() with multiple + * connections at same time. + * If #MHD_is_feature_supported() return #MHD_NO for this feature then + * usage of responses with same file FD in multiple parallel threads may + * results in incorrect data sent to remote client. + * It's always safe to use same file FD in multiple responses if MHD + * is run in any single thread mode. + */ + MHD_FEATURE_RESPONSES_SHARED_FD = 18 +}; + + +/** + * Get information about supported MHD features. + * Indicate that MHD was compiled with or without support for + * particular feature. Some features require additional support + * by kernel. Kernel support is not checked by this function. + * + * @param feature type of requested information + * @return #MHD_YES if feature is supported by MHD, #MHD_NO if + * feature is not supported or feature is unknown. + * @ingroup specialized + */ +_MHD_EXTERN int +MHD_is_feature_supported (enum MHD_FEATURE feature); + + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +#endif diff --git a/microhttpd/0.9.55/Linux-x86_64/libmicrohttpd.so.12.43.0 b/microhttpd/0.9.55/Linux-x86_64/libmicrohttpd.so.12.43.0 new file mode 100755 index 0000000000000000000000000000000000000000..a317dea853896b4255170d509739f58a103dc83f Binary files /dev/null and b/microhttpd/0.9.55/Linux-x86_64/libmicrohttpd.so.12.43.0 differ diff --git a/ocilib/4.4.0/AIX-00FB437F4C00/include/ocilib.h b/ocilib/4.4.0/AIX-00FB437F4C00/include/ocilib.h new file mode 100755 index 0000000000000000000000000000000000000000..84dbb1fb651e2def225f36b33f836828e8b3d4b2 --- /dev/null +++ b/ocilib/4.4.0/AIX-00FB437F4C00/include/ocilib.h @@ -0,0 +1,19176 @@ +/* + * OCILIB - C Driver for Oracle (C Wrapper for Oracle OCI) + * + * Website: http://www.ocilib.net + * + * Copyright (c) 2007-2017 Vincent ROGIER + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* IMPORTANT NOTICE + * + * This file contains explanations about Oracle and OCI technologies. + * OCILIB is a wrapper around OCI and thus exposes OCI features. + * The OCILIB documentation intends to explain Oracle / OCI concepts + * and is naturally based on the official Oracle OCI documentation. + * + * Some parts of OCILIB documentation may include some informations + * taken and adapted from the following Oracle documentations : + * - Oracle Call Interface Programmer's Guide + * - Oracle Streams - Advanced Queuing User's Guide + */ + +#ifndef OCILIB_H_INCLUDED +#define OCILIB_H_INCLUDED + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + + +/** + * @defgroup OcilibCApi C API + * @{ + * + */ + +/* --------------------------------------------------------------------------------------------- * + * Platform configuration + * --------------------------------------------------------------------------------------------- */ + +#ifdef HAVE_CONFIG_H + #include +#endif + +/* --------------------------------------------------------------------------------------------- * + * C headers + * --------------------------------------------------------------------------------------------- */ + +#include +#include +#include +#include +#include +#include +#include +#include + +/* --------------------------------------------------------------------------------------------- * + * MS Windows platform detection + * --------------------------------------------------------------------------------------------- */ + +#ifndef _WINDOWS + #if defined(_WIN32)|| defined(WIN32) || defined(_WIN64) || defined(WIN64) || defined(_WIN32_WINNT) + #define _WINDOWS + #endif +#endif + +#ifdef _WINDOWS + #ifdef boolean + #undef boolean + #endif + #include + #ifdef boolean + #undef boolean + #endif +#endif + +/* --------------------------------------------------------------------------------------------- * + * OCILIB version information + * --------------------------------------------------------------------------------------------- */ + +#define OCILIB_MAJOR_VERSION 4 +#define OCILIB_MINOR_VERSION 4 +#define OCILIB_REVISION_VERSION 0 + +/* Import mode */ + +#define OCI_IMPORT_MODE_LINKAGE 1 +#define OCI_IMPORT_MODE_RUNTIME 2 + +#ifdef OCI_IMPORT_RUNTIME + #undef OCI_IMPORT_LINKAGE +#endif + +#ifdef OCI_IMPORT_LINKAGE + #undef OCI_IMPORT_RUNTIME +#endif + +#if !defined(OCI_IMPORT_RUNTIME) && !defined(OCI_IMPORT_LINKAGE) + #define OCI_IMPORT_LINKAGE +#endif + +#ifdef OCI_IMPORT_RUNTIME + #define OCI_IMPORT_MODE OCI_IMPORT_MODE_RUNTIME +#else + #define OCI_IMPORT_MODE OCI_IMPORT_MODE_LINKAGE +#endif + +/* Charset modes */ + +#ifdef OCI_CHARSET_UNICODE + #define OCI_CHARSET_WIDE +#endif + +#ifdef OCI_CHARSET_WIDE + #undef OCI_CHARSET_ANSI +#endif + +#ifdef OCI_CHARSET_ANSI + #undef OCI_CHARSET_ANSI +#endif + +#if !defined(OCI_CHARSET_ANSI) && !defined(OCI_CHARSET_WIDE) + #define OCI_CHARSET_ANSI +#endif + +/* Calling convention */ + +#ifndef OCI_API + #ifdef _MSC_VER + #define OCI_API __stdcall + #else + #define OCI_API + #endif +#endif + +/* Build mode */ + +#ifndef OCI_EXPORT + #define OCI_EXPORT +#endif + +/** + * @defgroup OcilibCApiSupportedCharsets Character sets + * @{ + * + * OCILIB supports both ANSI and Unicode. + * + * Oracle started a real Unicode support with Oracle8i but only for bind and fetch data. + * All SQL and PL/SQ/ statements, database objects names were still only supported in ANSI. + * + * With Oracle 9i, Oracle provides a full Unicode support. + * + * So depending on the compile time Oracle library or the runtime loaded library, Unicode support differs. + * + * OCILIB supports: + * + * - ANSI (char) + * - Unicode (wchar_t) + * - UTF8 strings + * + * OCILIB uses the character type 'otext' that is a define around char and wchar_t depending on the charset mode. + * + * @par Option OCI_CHARSET_ANSI + * + * - otext --> char + * - OTEXT(x) --> x + * + * @par Option OCI_CHARSET_WIDE + * + * - otext --> wchar_t + * - OTEXT(x) --> L ## x + * + * @par Unicode and ISO C + * + * Well, ISO C: + * - doesn't know anything about Unicode. + * - makes wide characters support tricky because wide character size is not defined and is freely adaptable by implementations. + * + * OCILIB uses char/wchar_t strings for both public interface and internal storage. + * + * Unicode builds of OCILIB initialize OCI in UTF16 Unicode mode. + * Oracle implements this mode with a 2 bytes (fixed length) UTF16 encoding. + * + * @warning + * When using Unicode builds of OCILIB, make sure that the target + * Database charset is also using an Unicode charset or is a superset of UTF16. + * If not, strings may be converted with substitution characters by the Oracle client ! + * + * So, on systems implementing wchar_t as 2 bytes based UTF16 (e.g. Ms Windows), + * strings are directly passed to Oracle and taken back from it. + * + * On other systems (most of the Unix systems) that use UTF32 as encoding, (4 bytes based wchar_t), OCILIB uses: + * - temporary buffers for statements and object names + * - buffer expansion from UTF16 to UTF32 for fetch and bind string: + * - allocation based on sizeof(wchar_t) + * - data filling based on sizeof(short) -> (UTF16 2 bytes) + * - data expansion to sizeof(wchar_t). + * + * Buffer expansion is done in place and has the advantage of not requiring extra buffer. + * That reduces the cost of the Unicode/ISO C handling overhead on Unix systems. + * + * @par UTF8 strings + * + * OCILIB fully supports UTF8 strings : + * - Within OCI_CHARSET_ANSI builds + * - NLS_LANG environment variable must be set to any valid UTF8 Oracle charset string + * + * @par Charset mapping macros + * + * OCILIB main header file provides macro around most common string functions of + * the C standard library. + * + * these macros are based on the model: ostr[libc function name]() + * + * xxx is the standard C library string function name without the character type prefix (str/wcs). + * + * List of available macros: + * - ostrdup + * - ostrcpy + * - ostrncpy + * - ostrcat + * - ostrncat + * - ostrlen + * - ostrcmp + * - ostrcasecmp + * - osprintf + * - ostol + * +**/ + +#if defined(__cplusplus) && defined(_MSC_VER) && (_MSC_VER < 1300) +extern "C++" { +#endif + +#include + +#if defined(__cplusplus) && defined(_MSC_VER) && (_MSC_VER < 1300) +} +#endif + +/* Charset macros */ + +#define OCI_CHAR_ANSI 1 +#define OCI_CHAR_WIDE 2 + +#ifdef OCI_CHARSET_ANSI + typedef char otext; + #define OTEXT(x) x + #define OCI_CHAR_TEXT OCI_CHAR_ANSI +#else + typedef wchar_t otext; + #define OTEXT(x) L ## x + #define OCI_CHAR_TEXT OCI_CHAR_WIDE +#endif + +/* + For ISO conformance, strdup/wcsdup/stricmp/strncasecmp are not used. + All wide char routines are part of the 1995 Normative Addendum 1 to the ISO C90 standard. + OCILIB also needs an ANSI equivalent to swprintf => ocisprintf + Thus OCILIB exports the following helper functions + +*/ + +OCI_EXPORT int ocisprintf +( + char *str, + int size, + const char *format, + ... +); + +OCI_EXPORT char * ocistrdup +( + const char * src +); + +OCI_EXPORT int ocistrcasecmp +( + const char *str1, + const char *str2 +); + +OCI_EXPORT wchar_t * ociwcsdup +( + const wchar_t * src +); + +OCI_EXPORT int ociwcscasecmp +( + const wchar_t *str1, + const wchar_t *str2 +); + +/* special defines for Microsoft C runtime that is not C ISO compliant */ + +#ifdef _WINDOWS + + #define vsnprintf _vsnprintf + #define swprintf _snwprintf + +#endif + +/* helpers mapping macros */ + +#ifdef OCI_CHARSET_ANSI + #define ostrdup ocistrdup + #define ostrcpy strcpy + #define ostrncpy strncpy + #define ostrcat strcat + #define ostrncat strncat + #define ostrlen strlen + #define ostrcmp strcmp + #define ostrcasecmp ocistrcasecmp + #define osprintf ocisprintf + #define ostrtol strtol + #define osscanf sscanf + #define otoupper toupper + #define oisdigit isdigit +#else + #define ostrdup ociwcsdup + #define ostrcpy wcscpy + #define ostrncpy wcsncpy + #define ostrcat wcscat + #define ostrncat wcsncat + #define ostrlen wcslen + #define ostrcmp wcscmp + #define ostrcasecmp ociwcscasecmp + #define osprintf swprintf + #define ostrtol wcstol + #define osscanf swscanf + #define otoupper towupper + #define oisdigit iswdigit + +#endif + +/* string size macros */ + +#define otextsize(s) (ostrlen(s) * sizeof(otext)) + +/** + * @} + */ + +/** + * @defgroup OcilibCApiDatatypes Data types + * @{ + * + * OCILIB implements: + * + * - Oracle Scalar data types through scalar C data types + * - Oracle opaque/complex objects though opaque library handles + * - Library objects for manipulating the database: connections, transactions, statements... + * + * @par Supported Oracle data types + * + * - All Database types are supported excluding REFs. + * + * Here is a summary of the supported data types: + * + * - Scalar types CHAR/NCHAR, VARCHAR2/NVARCHAR2, NUMBER, FLOAT, REAL, RAW, ... + * - Binary types: RAW, LONG RAW, VARRAW, .. + * - Larges Objects (Lobs and Files) : BLOB, CLOB, NCLOB, BFILE + * - LONG types: LONG, VAR LONG + * - Date, Timestamps et Intervals: DATE, TIMESTAMP, INTERVAL + * - PL/SQL types: Ref cursors, PL/SQL Tables + * - Named Types (by value): Built-in system objects and User defined objects + * - VARRAYs and Nested Tables + * - ROWIDs + * + * @par OCILIB library objects + * + * The public OCILIB library interface implements encapsulation for + * representing database objects (such as connections, statements ...) through + * opaque structures (pointers to structures whose definition is kept private) + * + * Instead of directly manipulating the structures and their members, the library + * has functions to access the underlying members. + * + * It's designed to make the user code as more independent as possible of + * the library details. + * +**/ + +/** + * @typedef OCI_Pool + * + * @brief + * Pool object (session or connection) + * + * A pool is a set of pooled objects + * + */ + +typedef struct OCI_Pool OCI_Pool; + +/** + * @typedef OCI_Connection + * + * @brief + * Oracle physical connection. + * + * It holds all information about a connection such as error handling, associated statements, ... + * Error handling and transactions are embedded within a connection object. + * + * @warning + * Multi threaded applications that use multiple connections should use one connection per thread + * as all statements associated with a connection share the same context. + * + */ + +typedef struct OCI_Connection OCI_Connection; + +/** + * @typedef OCI_Statement + * + * @brief + * Oracle SQL or PL/SQL statement. + * + * A Statement object allows users to prepare, execute SQL orders or PL/SQL blocks + * + */ + +typedef struct OCI_Statement OCI_Statement; + +/** + * @typedef OCI_Bind + * + * @brief + * Internal bind representation. + * + * A bind object is an object that holds all information about an Oracle statement binding operation + * + */ + +typedef struct OCI_Bind OCI_Bind; + +/** + * @typedef OCI_Resultset + * + * @brief + * Collection of output columns from a select statement. + * + * A resultset object is the result of 'select' SQL Statement. + * + * It's a set of data (ordered in columns) that can be fetched row by row + * to get data returned by the SQL statement + * + */ + +typedef struct OCI_Resultset OCI_Resultset; + +/** + * @typedef OCI_Column + * + * @brief + * Oracle SQL Column and Type member representation. + * + * A column object represents an output column from a select statement + * + */ + +typedef struct OCI_Column OCI_Column; + +/** + * @typedef OCI_Lob + * + * @brief + * Oracle Internal Large objects: + * + * The following internal Larges Objects are supported: + * + * - BLOBs : Binary large objects + * - CLOBs / NCLOBs : Character large objects + * + * LOBs were introduced by OCI8 to replace Long data types. + * + * It's designed to store really larges objects (buffer, files) inside the database + * + * Oracle encourages programmers to use those objects instead of LONG, LONG RAW, ... + * + * OCILIB supports both LOBs and LONGs + * + */ + +typedef struct OCI_Lob OCI_Lob; + +/** + * @typedef OCI_File + * + * @brief + * Oracle External Large objects: + * + * The following external Larges Objects are supported: + * + * - BFILEs : Binary files + * - CFILEs : Character files + * + * FILEs were introduced by OCI8 in order to store references to files located outside the database. + * + * @warning + * Only Read-only access is allowed on BFILEs + * + * Two way to use FILEs : + * + * - within statement context (query, binding) + * - without statement context (server files reading) through OCI_File properties functions + * + */ + +typedef struct OCI_File OCI_File; + +/** + * @typedef OCI_Transaction + * + * @brief + * Oracle Transaction. + * + * A transaction can be: + * + * - Local: it's implicitly created by OCILIB + * - Global: it's explicitly created by the program + * + */ + +typedef struct OCI_Transaction OCI_Transaction; + +/** + * @typedef OCI_Long + * + * @brief Oracle Long data type. + * + * The following long Objects are supported: + * + * - LONG RAW : Binary long objects + * - LONG : Character long objects + * + * Those types were used in older versions of Oracle (before Oracle8i) to store + * large chunks of data in the database. + * + * It's now depreciated by Oracle that recommends using LOBs + * + * Many databases and applications are still designed to use LONGs that's why + * OCILIB supports Long Objects and piecewise operations + * + */ + +typedef struct OCI_Long OCI_Long; + +/** +* @typedef OCI_Number +* +* @brief +* Oracle NUMBER representation. +* +*/ +typedef struct OCI_Number OCI_Number; + +/** + * @typedef OCI_Date + * + * @brief + * Oracle internal date representation. + * + */ + +typedef struct OCI_Date OCI_Date; + +/** + * @typedef OCI_Timestamp + * + * @brief + * Oracle internal timestamp representation. + * + */ + +typedef struct OCI_Timestamp OCI_Timestamp; + +/** + * @typedef OCI_Interval + * + * @brief + * Oracle internal interval representation. + * + */ + +typedef struct OCI_Interval OCI_Interval; + +/** + * @typedef OCI_Object + * + * @brief + * Oracle Named types representation. + * + */ + +typedef struct OCI_Object OCI_Object; + +/** + * @typedef OCI_Coll + * + * @brief + * Oracle Collections (VARRAYs and Nested Tables) representation. + * + */ + +typedef struct OCI_Coll OCI_Coll; + +/** + * @typedef OCI_Elem + * + * @brief + * Oracle Collection item representation. + * + */ + +typedef struct OCI_Elem OCI_Elem; + +/** + * @typedef OCI_Iter + * + * @brief + * Oracle Collection iterator representation. + * + */ +typedef struct OCI_Iter OCI_Iter; + +/** + * @typedef OCI_TypeInfo + * + * @brief + * Type info metadata handle. + * + */ + +/** + * @typedef OCI_Ref + * + * @brief + * Oracle REF type representation. + * + */ + +typedef struct OCI_Ref OCI_Ref; + +/** + * @typedef OCI_TypeInfo + * + * @brief + * Type info meta data handle. + * + */ + +typedef struct OCI_TypeInfo OCI_TypeInfo; + +/** + * @typedef OCI_HashTable + * + * @brief + * OCILIB implementation of hash tables. + * + */ + +typedef struct OCI_HashTable OCI_HashTable; + +/** + * @typedef OCI_Error + * + * @brief + * Encapsulates an Oracle or OCILIB exception. + * + * The error object is used to raise internal or oracle errors. + * When an error occurs, if the application has provided an error handler, an + * error object is constructed and passed to the handler + * + */ + +typedef struct OCI_Error OCI_Error; + +/** + * @typedef OCI_Mutex + * + * @brief + * OCILIB encapsulation of OCI mutexes. + * + */ + +typedef struct OCI_Mutex OCI_Mutex; + +/** + * @typedef OCI_Thread + * + * @brief + * OCILIB encapsulation of OCI Threads. + * + */ + +typedef struct OCI_Thread OCI_Thread; + +/** + * @typedef OCI_DirPath + * + * @brief + * OCILIB encapsulation of OCI Direct Path handle. + * + */ + +typedef struct OCI_DirPath OCI_DirPath; + +/** + * @typedef OCI_Subscription + * + * @brief + * OCILIB encapsulation of Oracle DCN notification + * + */ + +typedef struct OCI_Subscription OCI_Subscription; + +/** + * @typedef OCI_Event + * + * @brief + * OCILIB encapsulation of Oracle DCN event + * + */ + +typedef struct OCI_Event OCI_Event; + +/** + * @typedef OCI_Msg + * + * @brief + * OCILIB encapsulation of A/Q message + * + */ + +typedef struct OCI_Msg OCI_Msg; + +/** + * @typedef OCI_Agent + * + * @brief + * OCILIB encapsulation of A/Q Agent + * + */ + +typedef struct OCI_Agent OCI_Agent; + +/** + * @typedef OCI_Dequeue + * + * @brief + * OCILIB encapsulation of A/Q dequeuing operations + * + */ + +typedef struct OCI_Dequeue OCI_Dequeue; + +/** + * @typedef OCI_Enqueue + * + * @brief + * OCILIB encapsulation of A/Q enqueuing operations + * + */ + +typedef struct OCI_Enqueue OCI_Enqueue; + +/** + * @var POCI_ERROR + * + * @brief + * Error procedure prototype + * + * @param err - Error handle + * + */ + +typedef void (*POCI_ERROR) +( + OCI_Error *err +); + +/** + * @var POCI_THREAD + * + * @brief + * Thread procedure prototype + * + * @param thread - Thread handle + * @param arg - Pointer passed to OCI_ThreadRun() + * + */ + +typedef void (*POCI_THREAD) +( + OCI_Thread *thread, + void *arg +); + +/** + * @var POCI_THREADKEYDEST + * + * @brief + * Thread key destructor prototype. + * + * @param data - Thread Key current pointer value + * + */ + +typedef void (*POCI_THREADKEYDEST) +( + void *data +); + +/** + * @var POCI_NOTIFY + * + * @brief + * Database Change Notification User callback prototype. + * + * @param event - Event handle + * + */ + +typedef void (*POCI_NOTIFY) +( + OCI_Event *event +); + +/** + * @var POCI_NOTIFY_AQ + * + * @brief + * AQ notification callback prototype. + * + * @param dequeue - dequeue handle + * + */ + +typedef void (*POCI_NOTIFY_AQ) +( + OCI_Dequeue *dequeue +); + +/** + * @var POCI_TAF_HANDLER + * + * @brief + * Failover Notification User callback prototype. + * + * @param con - Connection handle related to the event + * @param type - Event type + * @param event - Event code + * + * @note + * Possible values for parameter 'type' : + * - OCI_FOT_NONE + * - OCI_FOT_SESSION + * - OCI_FOT_SELECT + * + * @note + * Possible values for parameter 'event' : + * - OCI_FOE_END + * - OCI_FOE_ABORT + * - OCI_FOE_REAUTH + * - OCI_FOE_BEGIN + * - OCI_FOE_ERROR + * + * @return + * User callback should return one of the following value : + * - OCI_FOC_OK + * - OCI_FOC_RETRY + * + */ + +typedef unsigned int (*POCI_TAF_HANDLER) +( + OCI_Connection *con, + unsigned int type, + unsigned int event +); + +/** + * @var POCI_HA_HANDLER + * + * @brief + * HA (High Availability) events Notification User callback prototype. + * + * @param con - Connection handle related to the event + * @param source - source of the event + * @param event - type of the event + * @param time - Timestamp of the event + * + * @note + * Currently, Oracle only send HA down events + * + * @note + * Possible values for parameter 'source' : + * - OCI_HES_INSTANCE + * - OCI_HES_DATABASE + * - OCI_HES_NODE + * - OCI_HES_SERVICE + * - OCI_HES_SERVICE_MEMBER + * - OCI_HES_ASM_INSTANCE + * - OCI_HES_PRECONNECT + * + * @note + * Possible values for parameter 'event' : + * - OCI_HET_DOWN : HA event type down + * - OCI_HET_UP : HA event type up + * + */ + +typedef void (*POCI_HA_HANDLER) +( + OCI_Connection *con, + unsigned int source, + unsigned int event, + OCI_Timestamp *time +); + +/* public structures */ + +/** + * @typedef OCI_XID + * + * @brief + * Global transaction identifier + * + */ + +typedef struct OCI_XID { + long formatID; + long gtrid_length; + long bqual_length; + char data[128]; +} OCI_XID; + +/** + * @typedef OCI_Variant + * + * @brief + * Internal Variant type based on union C type. + * + * @note + * Helpful for generic buffer, it reduces the amount of casts + * + */ + +typedef union OCI_Variant { + /* integers */ + int num; + + /* raw data */ + unsigned char *p_bytes; + + /* pointer to c natives types */ + void *p_void; + int *p_int; + float *p_float; + double *p_double; + otext *p_text; + + /* ocilib object types */ + OCI_Date *p_date; + OCI_Interval *p_interval; + OCI_Timestamp *p_timestamp; + OCI_Long *p_long; + OCI_Lob *p_lob; + OCI_File *p_file; + OCI_Statement *p_stmt; + OCI_Column *p_col; + OCI_Object *p_obj; + OCI_Coll *p_coll; + OCI_Iter *p_iter; + OCI_Elem *p_elem; +} OCI_Variant; + +/** +* @typedef OCI_HashValue +* +* @brief +* Hash table entry value +* +* OCILIB implementation of hash tables uses chaining method for dealing with collisions +* +*/ + +typedef struct OCI_HashValue { + OCI_Variant value; + struct OCI_HashValue *next; +} OCI_HashValue; + +/** + * @typedef OCI_HashEntry + * + * @brief + * Hash table entry + * + */ + +typedef struct OCI_HashEntry { + otext *key; + struct OCI_HashValue *values; + struct OCI_HashEntry *next; +} OCI_HashEntry; + +/** + * @typedef big_int + * + * @brief + * big_int is a C scalar integer (32 or 64 bits) depending on compiler support for 64bits integers. + * big_uint is an unsigned big_int + * + */ + +/* check for long long support */ + +#if defined(_LONGLONG) || defined(LONG_LONG_MAX) || defined(LLONG_MAX) || defined(__LONG_LONG_MAX__) + +/* C99 long long supported */ + +typedef long long big_int; +typedef unsigned long long big_uint; + + #define OCI_BIG_UINT_ENABLED + +#elif defined(_WINDOWS) + +/* Microsoft extension supported */ + +typedef __int64 big_int; +typedef unsigned __int64 big_uint; + + #define OCI_BIG_UINT_ENABLED + +#else + +typedef int big_int; +typedef unsigned int big_uint; + +#endif + +/** + * @} + */ + +/* boolean values */ + +#ifndef TRUE + #define TRUE 1 + #define FALSE 0 +#endif + +#ifndef boolean + #define boolean int +#endif + +/* oracle OCI key versions*/ + +#define OCI_8_0 800 +#define OCI_8_1 810 +#define OCI_9_0 900 +#define OCI_9_2 920 +#define OCI_10_1 1010 +#define OCI_10_2 1020 +#define OCI_11_1 1110 +#define OCI_11_2 1120 +#define OCI_12_1 1210 +#define OCI_12_2 1220 + +/* versions extract macros */ + +#define OCI_VER_MAJ(v) (unsigned int) (v/100) +#define OCI_VER_MIN(v) (unsigned int) ((v/10) - ((v/100)*10)) +#define OCI_VER_REV(v) (unsigned int) ((v) - ((v/10)*10)) + +/* OCILIB Error types */ + +#define OCI_ERR_ORACLE 1 +#define OCI_ERR_OCILIB 2 +#define OCI_ERR_WARNING 3 + +/* OCILIB Error codes */ + +#define OCI_ERR_NONE 0 +#define OCI_ERR_NOT_INITIALIZED 1 +#define OCI_ERR_LOADING_SHARED_LIB 2 +#define OCI_ERR_LOADING_SYMBOLS 3 +#define OCI_ERR_MULTITHREADED 4 +#define OCI_ERR_MEMORY 5 +#define OCI_ERR_NOT_AVAILABLE 6 +#define OCI_ERR_NULL_POINTER 7 +#define OCI_ERR_DATATYPE_NOT_SUPPORTED 8 +#define OCI_ERR_PARSE_TOKEN 9 +#define OCI_ERR_MAP_ARGUMENT 10 +#define OCI_ERR_OUT_OF_BOUNDS 11 +#define OCI_ERR_UNFREED_DATA 12 +#define OCI_ERR_MAX_BIND 13 +#define OCI_ERR_ATTR_NOT_FOUND 14 +#define OCI_ERR_MIN_VALUE 15 +#define OCI_ERR_NOT_COMPATIBLE 16 +#define OCI_ERR_STMT_STATE 17 +#define OCI_ERR_STMT_NOT_SCROLLABLE 18 +#define OCI_ERR_BIND_ALREADY_USED 19 +#define OCI_ERR_BIND_ARRAY_SIZE 20 +#define OCI_ERR_COLUMN_NOT_FOUND 21 +#define OCI_ERR_DIRPATH_STATE 22 +#define OCI_ERR_CREATE_OCI_ENVIRONMENT 23 +#define OCI_ERR_REBIND_BAD_DATATYPE 24 +#define OCI_ERR_TYPEINFO_DATATYPE 25 +#define OCI_ERR_ITEM_NOT_FOUND 26 +#define OCI_ERR_ARG_INVALID_VALUE 27 +#define OCI_ERR_XA_ENV_FROM_STRING 28 +#define OCI_ERR_XA_CONN_FROM_STRING 29 + +#define OCI_ERR_COUNT 30 + + +/* allocated bytes types */ + +#define OCI_MEM_ORACLE 1 +#define OCI_MEM_OCILIB 2 +#define OCI_MEM_ALL OCI_MEM_ORACLE | OCI_MEM_OCILIB + +/* binding */ + +#define OCI_BIND_BY_POS 0 +#define OCI_BIND_BY_NAME 1 +#define OCI_BIND_SIZE 6 +#define OCI_BIND_MAX 65535 + +/* fetching */ + +#define OCI_FETCH_SIZE 20 +#define OCI_PREFETCH_SIZE 20 +#define OCI_LONG_EXPLICIT 1 +#define OCI_LONG_IMPLICIT 2 + +/* unknown value */ + +#define OCI_UNKNOWN 0 + +/* C Data Type mapping */ + +#define OCI_CDT_NUMERIC 1 +#define OCI_CDT_DATETIME 3 +#define OCI_CDT_TEXT 4 +#define OCI_CDT_LONG 5 +#define OCI_CDT_CURSOR 6 +#define OCI_CDT_LOB 7 +#define OCI_CDT_FILE 8 +#define OCI_CDT_TIMESTAMP 9 +#define OCI_CDT_INTERVAL 10 +#define OCI_CDT_RAW 11 +#define OCI_CDT_OBJECT 12 +#define OCI_CDT_COLLECTION 13 +#define OCI_CDT_REF 14 +#define OCI_CDT_BOOLEAN 15 + +/* Data Type codes for OCI_ImmediateXXX() calls */ + +#define OCI_ARG_SHORT 1 +#define OCI_ARG_USHORT 2 +#define OCI_ARG_INT 3 +#define OCI_ARG_UINT 4 +#define OCI_ARG_BIGINT 5 +#define OCI_ARG_BIGUINT 6 +#define OCI_ARG_DOUBLE 7 +#define OCI_ARG_DATETIME 8 +#define OCI_ARG_TEXT 9 +#define OCI_ARG_LOB 10 +#define OCI_ARG_FILE 11 +#define OCI_ARG_TIMESTAMP 12 +#define OCI_ARG_INTERVAL 13 +#define OCI_ARG_RAW 14 +#define OCI_ARG_OBJECT 15 +#define OCI_ARG_COLLECTION 16 +#define OCI_ARG_REF 17 +#define OCI_ARG_FLOAT 18 +#define OCI_ARG_NUMBER 19 + +/* statement types */ + +#define OCI_CST_SELECT 1 +#define OCI_CST_UPDATE 2 +#define OCI_CST_DELETE 3 +#define OCI_CST_INSERT 4 +#define OCI_CST_CREATE 5 +#define OCI_CST_DROP 6 +#define OCI_CST_ALTER 7 +#define OCI_CST_BEGIN 8 +#define OCI_CST_DECLARE 9 +#define OCI_CST_CALL 10 + +/* environment modes */ + +#define OCI_ENV_DEFAULT 0 +#define OCI_ENV_THREADED 1 +#define OCI_ENV_CONTEXT 2 +#define OCI_ENV_EVENTS 4 + +/* sessions modes */ + +#define OCI_SESSION_DEFAULT 0x00000000 /* any version */ +#define OCI_SESSION_SYSDBA 0x00000002 /* any version */ +#define OCI_SESSION_SYSOPER 0x00000004 /* any version */ +#define OCI_SESSION_SYSASM 0x00008000 /* From 11gR1 */ +#define OCI_SESSION_SYSBKP 0x00020000 /* From 12cR1 */ +#define OCI_SESSION_SYSDGD 0x00040000 /* From 12cR1 */ +#define OCI_SESSION_SYSKMT 0x00080000 /* From 12cR1 */ +#define OCI_SESSION_SYSRAC 0x00100000 /* From 12cR2 */ + +#define OCI_SESSION_XA 0x00000001 +#define OCI_SESSION_PRELIM_AUTH 0x00000008 + +/* change notification types */ + +#define OCI_CNT_OBJECTS 1 +#define OCI_CNT_ROWS 2 +#define OCI_CNT_DATABASES 4 +#define OCI_CNT_ALL OCI_CNT_OBJECTS | OCI_CNT_ROWS | OCI_CNT_DATABASES + +/* event notification types */ + +#define OCI_ENT_STARTUP 1 +#define OCI_ENT_SHUTDOWN 2 +#define OCI_ENT_SHUTDOWN_ANY 3 +#define OCI_ENT_DROP_DATABASE 4 +#define OCI_ENT_DEREGISTER 5 +#define OCI_ENT_OBJECT_CHANGED 6 + +/* event object notification types */ + +#define OCI_ONT_INSERT 0x2 +#define OCI_ONT_UPDATE 0x4 +#define OCI_ONT_DELETE 0x8 +#define OCI_ONT_ALTER 0x10 +#define OCI_ONT_DROP 0x20 +#define OCI_ONT_GENERIC 0x40 + +/* database startup modes */ + +#define OCI_DB_SPM_START 1 +#define OCI_DB_SPM_MOUNT 2 +#define OCI_DB_SPM_OPEN 4 +#define OCI_DB_SPM_FULL OCI_DB_SPM_START | OCI_DB_SPM_MOUNT | OCI_DB_SPM_OPEN + +/* database startup flags */ + +#define OCI_DB_SPF_DEFAULT 0 +#define OCI_DB_SPF_FORCE 1 +#define OCI_DB_SPF_RESTRICT 2 + +/* database shutdown modes */ + +#define OCI_DB_SDM_SHUTDOWN 1 +#define OCI_DB_SDM_CLOSE 2 +#define OCI_DB_SDM_DISMOUNT 4 +#define OCI_DB_SDM_FULL OCI_DB_SDM_SHUTDOWN | OCI_DB_SDM_CLOSE | OCI_DB_SDM_DISMOUNT + +/* database shutdown flags */ + +#define OCI_DB_SDF_DEFAULT 0 +#define OCI_DB_SDF_TRANS 1 +#define OCI_DB_SDF_TRANS_LOCAL 2 +#define OCI_DB_SDF_IMMEDIATE 3 +#define OCI_DB_SDF_ABORT 4 + +/* charset form types */ + +#define OCI_CSF_NONE 0 +#define OCI_CSF_DEFAULT 1 +#define OCI_CSF_NATIONAL 2 + +/* statement fetch mode */ + +#define OCI_SFM_DEFAULT 0 +#define OCI_SFM_SCROLLABLE 0x08 + +/* statement fetch direction */ + +#define OCI_SFD_ABSOLUTE 0x20 +#define OCI_SFD_RELATIVE 0x40 + +/* bind allocation mode */ + +#define OCI_BAM_EXTERNAL 1 +#define OCI_BAM_INTERNAL 2 + +/* bind direction mode */ + +#define OCI_BDM_IN 1 +#define OCI_BDM_OUT 2 +#define OCI_BDM_IN_OUT (OCI_BDM_IN | OCI_BDM_OUT) + +/* Column property flags */ + +#define OCI_CPF_NONE 0 +#define OCI_CPF_IS_IDENTITY 1 +#define OCI_CPF_IS_GEN_ALWAYS 2 +#define OCI_CPF_IS_GEN_BY_DEFAULT_ON_NULL 4 + +/* Column collation IDs */ + +#define OCI_CCI_NONE 0x00000000 +#define OCI_CCI_NLS_COMP 0x00003FFE +#define OCI_CCI_NLS_SORT 0x00003FFD +#define OCI_CCI_NLS_SORT_CI 0x00003FFC +#define OCI_CCI_NLS_SORT_AI 0x00003FFB +#define OCI_CCI_NLS_SORT_CS 0x00003FFA +#define OCI_CCI_NLS_SORT_VAR1 0x00003FF9 +#define OCI_CCI_NLS_SORT_VAR1_CI 0x00003FF8 +#define OCI_CCI_NLS_SORT_VAR1_AI 0x00003FF7 +#define OCI_CCI_NLS_SORT_VAR1_CS 0x00003FF6 +#define OCI_CCI_BINARY 0x00003FFF +#define OCI_CCI_BINARY_CI 0x00023FFF +#define OCI_CCI_BINARY_AI 0x00013FFF + + +/* Integer sign flag */ + +#define OCI_NUM_UNSIGNED 2 + +/* External Integer types */ + +#define OCI_NUM_SHORT 4 +#define OCI_NUM_INT 8 +#define OCI_NUM_BIGINT 16 +#define OCI_NUM_FLOAT 32 +#define OCI_NUM_DOUBLE 64 +#define OCI_NUM_NUMBER 128 + +#define OCI_NUM_USHORT (OCI_NUM_SHORT | OCI_NUM_UNSIGNED) +#define OCI_NUM_UINT (OCI_NUM_INT | OCI_NUM_UNSIGNED) +#define OCI_NUM_BIGUINT (OCI_NUM_BIGINT | OCI_NUM_UNSIGNED) + +/* timestamp types */ + +#define OCI_TIMESTAMP 1 +#define OCI_TIMESTAMP_TZ 2 +#define OCI_TIMESTAMP_LTZ 3 + +/* interval types */ + +#define OCI_INTERVAL_YM 1 +#define OCI_INTERVAL_DS 2 + +/* long types */ + +#define OCI_BLONG 1 +#define OCI_CLONG 2 + +/* lob types */ + +#define OCI_BLOB 1 +#define OCI_CLOB 2 +#define OCI_NCLOB 3 + +/* lob opening mode */ + +#define OCI_LOB_READONLY 1 +#define OCI_LOB_READWRITE 2 + +/* file types */ + +#define OCI_BFILE 1 +#define OCI_CFILE 2 + +/* lob browsing mode */ + +#define OCI_SEEK_SET 1 +#define OCI_SEEK_END 2 +#define OCI_SEEK_CUR 3 + +/* type info types */ + +#define OCI_TIF_TABLE 1 +#define OCI_TIF_VIEW 2 +#define OCI_TIF_TYPE 3 + +/* object type */ + +#define OCI_OBJ_PERSISTENT 1 +#define OCI_OBJ_TRANSIENT 2 +#define OCI_OBJ_VALUE 3 + +/* collection types */ + +#define OCI_COLL_VARRAY 1 +#define OCI_COLL_NESTED_TABLE 2 +#define OCI_COLL_INDEXED_TABLE 3 + +/* pool types */ + +#define OCI_POOL_CONNECTION 1 +#define OCI_POOL_SESSION 2 + +/* AQ message state */ + +#define OCI_AMS_READY 1 +#define OCI_AMS_WAITING 2 +#define OCI_AMS_PROCESSED 3 +#define OCI_AMS_EXPIRED 4 + +/* AQ sequence deviation */ + +#define OCI_ASD_BEFORE 2 +#define OCI_ASD_TOP 3 + +/* AQ message visibility */ + +#define OCI_AMV_IMMEDIATE 1 +#define OCI_AMV_ON_COMMIT 2 + +/* AQ dequeue mode */ + +#define OCI_ADM_BROWSE 1 +#define OCI_ADM_LOCKED 2 +#define OCI_ADM_REMOVE 3 +#define OCI_ADM_REMOVE_NODATA 4 + +/* AQ dequeue navigation */ + +#define OCI_ADN_FIRST_MSG 1 +#define OCI_ADN_NEXT_TRANSACTION 2 +#define OCI_ADN_NEXT_MSG 3 + +/* AQ queue table purge mode */ + +#define OCI_APM_BUFFERED 1 +#define OCI_APM_PERSISTENT 2 +#define OCI_APM_ALL (OCI_APM_BUFFERED | OCI_APM_PERSISTENT) + +/* AQ queue table grouping mode */ + +#define OCI_AGM_NONE 0 +#define OCI_AGM_TRANSACTIONNAL 1 + +/* AQ queue table type */ + +#define OCI_AQT_NORMAL 0 +#define OCI_AQT_EXCEPTION 1 +#define OCI_AQT_NON_PERSISTENT 2 + +/* direct path processing return status */ + +#define OCI_DPR_COMPLETE 1 +#define OCI_DPR_ERROR 2 +#define OCI_DPR_FULL 3 +#define OCI_DPR_PARTIAL 4 +#define OCI_DPR_EMPTY 5 + +/* direct path conversion modes */ + +#define OCI_DCM_DEFAULT 1 +#define OCI_DCM_FORCE 2 + +/* trace size constants */ + +#define OCI_SIZE_TRACE_ID 64 +#define OCI_SIZE_TRACE_MODULE 48 +#define OCI_SIZE_TRACE_ACTION 32 +#define OCI_SIZE_TRACE_INFO 64 + +/* trace types */ + +#define OCI_TRC_IDENTITY 1 +#define OCI_TRC_MODULE 2 +#define OCI_TRC_ACTION 3 +#define OCI_TRC_DETAIL 4 + +/* HA event type */ + +#define OCI_HET_DOWN 0 +#define OCI_HET_UP 1 + +/* HA event source */ +#define OCI_HES_INSTANCE 0 +#define OCI_HES_DATABASE 1 +#define OCI_HES_NODE 2 +#define OCI_HES_SERVICE 3 +#define OCI_HES_SERVICE_MEMBER 4 +#define OCI_HES_ASM_INSTANCE 5 +#define OCI_HES_PRECONNECT 6 + +/* Fail over types */ + +#define OCI_FOT_NONE 1 +#define OCI_FOT_SESSION 2 +#define OCI_FOT_SELECT 4 + +/* fail over notifications */ + +#define OCI_FOE_END 1 +#define OCI_FOE_ABORT 2 +#define OCI_FOE_REAUTH 4 +#define OCI_FOE_BEGIN 8 +#define OCI_FOE_ERROR 16 + +/* fail over callback return code */ + +#define OCI_FOC_OK 0 +#define OCI_FOC_RETRY 25410 + +/* hash tables support */ + +#define OCI_HASH_STRING 1 +#define OCI_HASH_INTEGER 2 +#define OCI_HASH_POINTER 3 + +/* transaction types */ + +#define OCI_TRS_NEW 0x00000001 +#define OCI_TRS_READONLY 0x00000100 +#define OCI_TRS_READWRITE 0x00000200 +#define OCI_TRS_SERIALIZABLE 0x00000400 +#define OCI_TRS_LOOSE 0x00010000 +#define OCI_TRS_TIGHT 0x00020000 + +/* format types */ + +#define OCI_FMT_DATE 1 +#define OCI_FMT_TIMESTAMP 2 +#define OCI_FMT_NUMERIC 3 +#define OCI_FMT_BINARY_DOUBLE 4 +#define OCI_FMT_BINARY_FLOAT 5 + +/* sql function codes */ + +#define OCI_SFC_CREATE_TABLE 1 +#define OCI_SFC_SET_ROLE 2 +#define OCI_SFC_INSERT 3 +#define OCI_SFC_SELECT 4 +#define OCI_SFC_UPDATE 5 +#define OCI_SFC_DROP_ROLE 6 +#define OCI_SFC_DROP_VIEW 7 +#define OCI_SFC_DROP_TABLE 8 +#define OCI_SFC_DELETE 9 +#define OCI_SFC_CREATE_VIEW 10 +#define OCI_SFC_DROP_USER 11 +#define OCI_SFC_CREATE_ROLE 12 +#define OCI_SFC_CREATE_SEQUENCE 13 +#define OCI_SFC_ALTER_SEQUENCE 14 + +#define OCI_SFC_DROP_SEQUENCE 16 +#define OCI_SFC_CREATE_SCHEMA 17 +#define OCI_SFC_CREATE_CLUSTER 18 +#define OCI_SFC_CREATE_USER 19 +#define OCI_SFC_CREATE_INDEX 20 +#define OCI_SFC_DROP_INDEX 21 +#define OCI_SFC_DROP_CLUSTER 22 +#define OCI_SFC_VALIDATE_INDEX 23 +#define OCI_SFC_CREATE_PROCEDURE 24 +#define OCI_SFC_ALTER_PROCEDURE 25 +#define OCI_SFC_ALTER_TABLE 26 +#define OCI_SFC_EXPLAIN 27 +#define OCI_SFC_GRANT 28 +#define OCI_SFC_REVOKE 29 +#define OCI_SFC_CREATE_SYNONYM 30 +#define OCI_SFC_DROP_SYNONYM 31 +#define OCI_SFC_ALTER_SYSTEM_SWITCHLOG 32 +#define OCI_SFC_SET_TRANSACTION 33 +#define OCI_SFC_PLSQL_EXECUTE 34 +#define OCI_SFC_LOCK 35 +#define OCI_SFC_NOOP 36 +#define OCI_SFC_RENAME 37 +#define OCI_SFC_COMMENT 38 +#define OCI_SFC_AUDIT 39 +#define OCI_SFC_NO_AUDIT 40 +#define OCI_SFC_ALTER_INDEX 41 +#define OCI_SFC_CREATE_EXTERNAL_DATABASE 42 +#define OCI_SFC_DROP_EXTERNALDATABASE 43 +#define OCI_SFC_CREATE_DATABASE 44 +#define OCI_SFC_ALTER_DATABASE 45 +#define OCI_SFC_CREATE_ROLLBACK_SEGMENT 46 +#define OCI_SFC_ALTER_ROLLBACK_SEGMENT 47 +#define OCI_SFC_DROP_ROLLBACK_SEGMENT 48 +#define OCI_SFC_CREATE_TABLESPACE 49 +#define OCI_SFC_ALTER_TABLESPACE 50 +#define OCI_SFC_DROP_TABLESPACE 51 +#define OCI_SFC_ALTER_SESSION 52 +#define OCI_SFC_ALTER_USER 53 +#define OCI_SFC_COMMIT_WORK 54 +#define OCI_SFC_ROLLBACK 55 +#define OCI_SFC_SAVEPOINT 56 +#define OCI_SFC_CREATE_CONTROL_FILE 57 +#define OCI_SFC_ALTER_TRACING 58 +#define OCI_SFC_CREATE_TRIGGER 59 +#define OCI_SFC_ALTER_TRIGGER 60 +#define OCI_SFC_DROP_TRIGGER 61 +#define OCI_SFC_ANALYZE_TABLE 62 +#define OCI_SFC_ANALYZE_INDEX 63 +#define OCI_SFC_ANALYZE_CLUSTER 64 +#define OCI_SFC_CREATE_PROFILE 65 +#define OCI_SFC_DROP_PROFILE 66 +#define OCI_SFC_ALTER_PROFILE 67 +#define OCI_SFC_DROP_PROCEDURE 68 + +#define OCI_SFC_ALTER_RESOURCE_COST 70 +#define OCI_SFC_CREATE_SNAPSHOT_LOG 71 +#define OCI_SFC_ALTER_SNAPSHOT_LOG 72 +#define OCI_SFC_DROP_SNAPSHOT_LOG 73 +#define OCI_SFC_DROP_SUMMARY 73 +#define OCI_SFC_CREATE_SNAPSHOT 74 +#define OCI_SFC_ALTER_SNAPSHOT 75 +#define OCI_SFC_DROP_SNAPSHOT 76 +#define OCI_SFC_CREATE_TYPE 77 +#define OCI_SFC_DROP_TYPE 78 +#define OCI_SFC_ALTER_ROLE 79 +#define OCI_SFC_ALTER_TYPE 80 +#define OCI_SFC_CREATE_TYPE_BODY 81 +#define OCI_SFC_ALTER_TYPE_BODY 82 +#define OCI_SFC_DROP_TYPE_BODY 83 +#define OCI_SFC_DROP_LIBRARY 84 +#define OCI_SFC_TRUNCATE_TABLE 85 +#define OCI_SFC_TRUNCATE_CLUSTER 86 +#define OCI_SFC_CREATE_BITMAPFILE 87 +#define OCI_SFC_ALTER_VIEW 88 +#define OCI_SFC_DROP_BITMAPFILE 89 +#define OCI_SFC_SET_CONSTRAINTS 90 +#define OCI_SFC_CREATE_FUNCTION 91 +#define OCI_SFC_ALTER_FUNCTION 92 +#define OCI_SFC_DROP_FUNCTION 93 +#define OCI_SFC_CREATE_PACKAGE 94 +#define OCI_SFC_ALTER_PACKAGE 95 +#define OCI_SFC_DROP_PACKAGE 96 +#define OCI_SFC_CREATE_PACKAGE_BODY 97 +#define OCI_SFC_ALTER_PACKAGE_BODY 98 +#define OCI_SFC_DROP_PACKAGE_BODY 99 +#define OCI_SFC_CREATE_DIRECTORY 157 +#define OCI_SFC_DROP_DIRECTORY 158 +#define OCI_SFC_CREATE_LIBRARY 159 +#define OCI_SFC_CREATE_JAVA 160 +#define OCI_SFC_ALTER_JAVA 161 +#define OCI_SFC_DROP_JAVA 162 +#define OCI_SFC_CREATE_OPERATOR 163 +#define OCI_SFC_CREATE_INDEXTYPE 164 +#define OCI_SFC_DROP_INDEXTYPE 165 +#define OCI_SFC_ALTER_INDEXTYPE 166 +#define OCI_SFC_DROP_OPERATOR 167 +#define OCI_SFC_ASSOCIATE_STATISTICS 168 +#define OCI_SFC_DISASSOCIATE_STATISTICS 169 +#define OCI_SFC_CALL_METHOD 170 +#define OCI_SFC_CREATE_SUMMARY 171 +#define OCI_SFC_ALTER_SUMMARY 172 +#define OCI_SFC_CREATE_DIMENSION 174 +#define OCI_SFC_ALTER_DIMENSION 175 +#define OCI_SFC_DROP_DIMENSION 176 +#define OCI_SFC_CREATE_CONTEXT 177 +#define OCI_SFC_DROP_CONTEXT 178 +#define OCI_SFC_ALTER_OUTLINE 179 +#define OCI_SFC_CREATE_OUTLINE 180 +#define OCI_SFC_DROP_OUTLINE 181 +#define OCI_SFC_UPDATE_INDEXES 182 +#define OCI_SFC_ALTER_OPERATOR 183 + +/* size constants */ + +#define OCI_SIZE_FORMAT 64 +#define OCI_SIZE_BUFFER 512 +#define OCI_SIZE_LONG (64*1024)-1 +#define OCI_SIZE_DATE 45 +#define OCI_SIZE_TIMESTAMP 54 +#define OCI_SIZE_FORMAT_TODATE 14 +#define OCI_SIZE_NULL 4 +#define OCI_SIZE_PRECISION 10 +#define OCI_SIZE_ROWID 23 +#define OCI_SIZE_DIRECTORY 30 +#define OCI_SIZE_FILENAME 255 +#define OCI_SIZE_FORMAT_NUMS 40 +#define OCI_SIZE_FORMAT_NUML 65 +#define OCI_SIZE_OBJ_NAME 128 + +#define OCI_HASH_DEFAULT_SIZE 256 + +/* string constants */ + +#define OCILIB_DRIVER_NAME OTEXT("OCILIB") +#define OCI_STRING_NULL OTEXT("NULL") +#define OCI_STRING_EMPTY OTEXT("") +#define OCI_STRING_FORMAT_DATE OTEXT("YYYY-MM-DD") +#define OCI_STRING_FORMAT_TIME OTEXT("HH24:MI:SS") +#define OCI_STRING_FORMAT_DATETIME OTEXT("YYYY-MM-DD HH24:MI:SS") +#define OCI_STRING_FORMAT_TIMESTAMP OTEXT("YYYY-MM-DD HH24:MI:SS.FF") +#define OCI_STRING_DEFAULT_PREC 3 +#define OCI_STRING_FORMAT_NUM \ + OTEXT("FM99999999999999999999999999999999999990.999999999999999999999999") +#define OCI_STRING_FORMAT_NUM_BDOUBLE OTEXT("%lf") +#define OCI_STRING_FORMAT_NUM_BFLOAT OTEXT("%f") +#define OCI_STRING_FORMAT_NUM_SHORT OTEXT("%hd") +#define OCI_STRING_FORMAT_NUM_INT OTEXT("%d") +#define OCI_STRING_TRUE OTEXT("TRUE") +#define OCI_STRING_FALSE OTEXT("FALSE") +#define OCI_STRING_TRUE_SIZE 4 +#define OCI_STRING_FALSE_SIZE 5 + +#ifdef _WINDOWS + #define OCI_CHAR_SLASH '\\' +#else + #define OCI_CHAR_SLASH '/' +#endif + +/** + * @defgroup OcilibCApiInitialization Initializing the library + * @{ + * + * To use OCILIB, it first needs to be initialized through a call to OCI_Initialize(). + * + * Then, the application connects to server, executes queries... + * + * Finally, OCILIB resources must be released by OCI_Cleanup() + * + * @note + * + * The following objects are automatically freed by the library: + * - Connections + * - pools + * - Statements + * - Type info objects + * - Thread keys + * + * @warning + * + * All other standalone object instances (mutexes, threads, dates, lobs, ...) ARE NOT freed. + * + */ + +/** + * @brief + * Initialize the library + * + * @param err_handler - Pointer to error handler procedure (optional) + * @param lib_path - Oracle shared library path (optional) + * @param mode - Environment mode + * + * Possible values for parameter mode: + * - OCI_ENV_DEFAULT : default mode + * - OCI_ENV_THREADED : multi-threading support + * - OCI_ENV_CONTEXT : thread contextual error handling + * - OCI_ENV_EVENTS : enables events for subscription, HA Events, AQ notifications + * + * @note + * This function must be called before any OCILIB library function. + * + * @warning + * - The parameter 'libpath' is only used if OCILIB has been built with the option OCI_IMPORT_RUNTIME + * - If the parameter 'lib_path' is NULL, the Oracle library is loaded from system environment variables + * + * @warning + * OCI_Initialize() should be called ONCE per application + * + * @return + * TRUE on success otherwise FALSE (only with Oracle runtime loading mode + * if the oracle shared libraries can't be loaded or if OCI subsystem cannot be initialized) + * + */ + +OCI_EXPORT boolean OCI_API OCI_Initialize +( + POCI_ERROR err_handler, + const otext *lib_path, + unsigned int mode +); + +/** + * @brief + * Clean up all resources allocated by the library + * + * @note + * * This function must be the last OCILIB library function call. + * - It deallocates objects not explicitly freed by the program (connections, statements, ...) + * - It unloads the Oracle shared library if it has been dynamically loaded + * + * @warning + * OCI_Cleanup() should be called ONCE per application + * + * @return TRUE + */ + +OCI_EXPORT boolean OCI_API OCI_Cleanup +( + void +); + +/** + * @brief + * Return the version of OCI used for compilation + * + * @note + * - with linkage build option, the version is determined from the oci.h header through different ways + * - with runtime loading build option, the version is set to the highest version + * of OCI needed by OCILIB, not necessarily the real OCI version + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetOCICompileVersion +( + void +); + +/** + * @brief + * Return the version of OCI used at runtime + * + * @note + * - with linkage build option, the version is determined from the oci.h header + * through different ways + * - with runtime loading build option, the version determined from the symbols + * dynamically loaded. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetOCIRuntimeVersion +( + void +); + +/** + * @brief + * Return the Oracle shared library import mode + * + * @note + * Possible values are: + * - OCI_IMPORT_MODE_LINKAGE + * - OCI_IMPORT_MODE_RUNTIME + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetImportMode +( + void +); + +/** + * @brief + * Return the OCILIB charset type + * + * @note + * Possible values are: + * - OCI_CHAR_ANSI + * - OCI_CHAR_WIDE + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetCharset +( + void +); + +/** +* @brief +* Return the current number of bytes allocated internally in the library +* +* @param mem_type : type of memory to request +* +* @note +* Possible values are: +* - OCI_MEM_ORACLE : bytes allocated by Oracle client library +* - OCI_MEM_OCILIB : bytes allocated by OCILIB library +* - OCI_MEM_ORACLE : bytes allocated by all libraries +* +*/ + +OCI_EXPORT big_uint OCI_API OCI_GetAllocatedBytes +( + unsigned int mem_type +); + +/** + * @brief + * Enable or disable Oracle warning notifications + * + * @param value - enable/disable warnings + * + * @note + * Default value is FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnableWarnings +( + boolean value +); + +/** + * @brief + * Set the global error user handler + * + * @param handler - Pointer to error handler procedure + * + * @note + * Use this call to change or remove the user callback error handler installed by OCI_Initialize() + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetErrorHandler +( + POCI_ERROR handler +); + +/** + * @brief + * Set the High availability (HA) user handler + * + * @param handler - Pointer to HA handler procedure + * + * @note + * See POCI_HA_HANDLER documentation for more details + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * HA events + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns FALSE without throwing any exception. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetHAHandler +( + POCI_HA_HANDLER handler +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiErrorHandling Error handling + * @{ + * + * OCILIB provides two mechanisms for error handling: + * + * - Global error handling through callbacks. + * - Contextual thread error handling + * + * Exceptions are raised: + * + * - On Oracle OCI API call error + * - On Oracle SQL statement error + * - On Internal OCILIB error (type checking, memory allocations ...) + * - On Oracle warnings (OCI API or SQL) + * + * If an error handler was provided to OCI_Initialize(), when an error occurs, the + * library generates an OCI_Error handle and pass it to the error handler. + * + * In order to use the thread contextual error handling, you must call + * OCI_Initialize() with the flag OCI_ENV_CONTEXT for the mode parameter. When + * activated, error handles are stored per thread and the last error within a + * thread can be retrieved with OCI_GetLastError() + * + * Exception properties are accessible through a set of functions + * + * @note + * The two ways to handle errors are not exclusive and can be mixed. + * + * @note + * Thread contextual error is also available for single thread based applications + * + * @par Oracle Warnings + * + * Oracle warnings are raised through OCI_Error API. + * Such error handles have their error type property (OCI_ErrorGetType()) set to OCI_ERR_WARNING. + * Warning handing is disabled by default. To activate/deactivate it, use OCI_EnableWarnings() + * + * @par Example with callbacks + * @include err.c + * + * @par Example with thread context + * @include err_ctx.c + * + *@par Example of warning handling + * @include err_warning.c + * + */ + +/** + * @brief + * Retrieve the last error or warning occurred within the last OCILIB call + * + * @note + * OCI_GetLastError() is based on thread context and thus OCILIB must be + * initialized with the flag OCI_ENV_CONTEXT + * + * @warning + * OCILIB functions that returns a boolean value to indicate their success : + * - return TRUE if no error occurred OR if a warning occurred + * - return FALSE if an error occurred + * + */ + +OCI_EXPORT OCI_Error * OCI_API OCI_GetLastError +( + void +); + +/** + * @brief + * Retrieve error message from error handle + * + * @param err - Error handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ErrorGetString +( + OCI_Error *err +); + +/** + * @brief + * Retrieve the type of error from error handle + * + * @param err - Error handle + * + * @note + * Returns one of the following values: + * + * - OCI_ERR_ORACLE + * - OCI_ERR_OCILIB + * - OCI_ERR_WARNING + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ErrorGetType +( + OCI_Error *err +); + +/** + * @brief + * Retrieve Oracle Error code from error handle + * + * @param err - Error handle + * + */ + +OCI_EXPORT int OCI_API OCI_ErrorGetOCICode +( + OCI_Error *err +); + +/** + * @brief + * Retrieve Internal Error code from error handle + * + * @param err - Error handle + * + */ + +OCI_EXPORT int OCI_API OCI_ErrorGetInternalCode +( + OCI_Error *err +); + +/** + * @brief + * Retrieve connection handle within the error occurred + * + * @param err - Error handle + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_ErrorGetConnection +( + OCI_Error *err +); + +/** + * @brief + * Retrieve statement handle within the error occurred + * + * @param err - Error handle + * + * @note + * If the error occurred outside of a statement context, it returns NULL + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_ErrorGetStatement +( + OCI_Error *err +); + +/** + * @brief + * Return the row index which caused an error during statement execution + * + * @param err - Error handle + * + * @warning + * Row index start at 1. + * + * @return + * 0 is the error is not related to array DML otherwise the index of the given + * row which caused the error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ErrorGetRow +( + OCI_Error *err +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiConnections Connecting to Database + * @{ + * + * Connecting to a database server is done with one call to OCI_ConnectionCreate(). + * + * OCI_ConnectionFree() closes the established connection. + * + * Connection properties are accessible through a set of functions + * + * @par Example + * @include conn.c + * + */ + +/** + * @brief + * Create a physical connection to an Oracle database server + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param mode - Session mode + * + * Possible values for parameter mode : + * - OCI_SESSION_DEFAULT + * - OCI_SESSION_SYSDBA + * - OCI_SESSION_SYSOPER + * - OCI_SESSION_XA + * + * @note + * External credentials are supported by supplying a null value for the + * 'user' and 'pwd' parameters. + * If the param 'db' is NULL then a connection to the default local DB is done + * + * @note + * For parameter 'mode', the possible values are exclusive and cannot be combined + * + * @par Oracle XA support + * + * OCILIB supports Oracle XA connectivity. In order to get a connection using + * the XA interface : + * - For parameter 'db' : pass the value of the 'DB' parameter of the given + * XA connection string passed to the Transaction Processing Monitor (TPM) + * - Pass NULL to the 'user' and 'pwd' parameters + * - Pass the value OCI_SESSION_XA to parameter 'mode' + * + * @par Oracle XA Connection String + * + * The XA connection string used in a transaction monitor to connect to Oracle must + * be compatible with OCILIB : + * + * - the XA parameter 'Objects' MUST be set to 'true' + * - If OCI_ENV_THREADED is passed to OCI_Initialize(), the XA parameter 'Threads' must + * be set to 'true', otherwise to 'false' + * - If OCI_ENV_EVENTS is passed to OCI_Initialize(), the XA parameter 'Events' must + * be set to 'true', otherwise to 'false' + * - As Oracle does not support Unicode UTF16 character set through the XA interface, + * Only OCI_CHARSET_ANSI builds of OCILIB can be used + * - You still can use UTF8 if the NLS_LANG environment variable is set with a valid + * UTF8 NLS value + * - DO NOT USE OCI_CHARSET_WIDE OCILIB builds with XA connections + * + * @note + * On success, a local transaction is automatically created and started ONLY for regular + * standalone connections and connections retrieved from connection pools. + * No transaction is created for a XA connection or q connection retrieved from session pools. + * + * @return + * Connection handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_ConnectionCreate +( + const otext *db, + const otext *user, + const otext *pwd, + unsigned int mode +); + +/** + * @brief + * Close a physical connection to an Oracle database server + * + * @param con - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ConnectionFree +( + OCI_Connection *con +); + +/** + * @brief + * Returns TRUE is the given connection is still connected otherwise FALSE + * + * @param con - Connection handle + * + */ + +OCI_EXPORT boolean OCI_API OCI_IsConnected +( + OCI_Connection *con +); + +/** + * @brief + * Return the pointer to user data previously associated with the connection + * + * @param con - Connection handle + * + */ + +OCI_EXPORT void * OCI_API OCI_GetUserData +( + OCI_Connection *con +); + +/** + * @brief + * Associate a pointer to user data to the given connection + * + * @param con - Connection handle + * @param data - User data pointer + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetUserData +( + OCI_Connection *con, + void *data +); + +/** + * @brief + * Associate a tag to the given connection/session + * + * @param con - Connection handle + * @param tag - user tag string + * + * @note + * Use this call only for connections retrieved from a session pool + * See OCI_PoolGetConnection() for more details + * + * @note + * To untag a session, call OCI_SetSessionTag() with 'tag' parameter set to NULL + * + * @warning + * No error is raised if the connection is a standalone connection or retrieved from a connection + * pool + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetSessionTag +( + OCI_Connection *con, + const otext *tag +); + +/** + * @brief + * Return the tag associated the given connection + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetSessionTag +( + OCI_Connection *con +); + +/** + * @brief + * Return the name of the connected database/service name + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetDatabase +( + OCI_Connection *con +); + +/** + * @brief + * Return the current logged user name + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetUserName +( + OCI_Connection *con +); + +/** + * @brief + * Return the current logged user password + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetPassword +( + OCI_Connection *con +); + +/** + * @brief + * Change the password of the logged user + * + * @param con - Connection handle + * @param password - New password + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetPassword +( + OCI_Connection *con, + const otext *password +); + +/** + * @brief + * Change the password of the given user on the given database + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param new_pwd - Oracle User New password + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetUserPassword +( + const otext *db, + const otext *user, + const otext *pwd, + const otext *new_pwd +); + +/** + * @brief + * Return the current session mode + * + * @param con - Connection handle + * + * @note + * See OCI_ConnectionCreate() for possible values + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetSessionMode +( + OCI_Connection *con +); + +/** + * @brief + * Return the connected database server version + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetVersionServer +( + OCI_Connection *con +); + +/** + * @brief + * Return the major version number of the connected database server + * + * @param con - Connection handle + * + * @return + * Version number or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetServerMajorVersion +( + OCI_Connection *con +); + +/** + * @brief + * Return the minor version number of the connected database server + * + * @param con - Connection handle + * + * @return + * Version number or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetServerMinorVersion +( + OCI_Connection *con +); + +/** + * @brief + * Return the revision version number of the connected database server + * + * @param con - Connection handle + * + * @return + * Version number or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetServerRevisionVersion +( + OCI_Connection *con +); + +/** + * @brief + * Set the format string for implicit string conversions of the given type + * + * @param con - Connection handle (optional) + * @param type - Type of format + * @param format - Format string + * + * Formats can set at 2 levels: + * - Library level: by passing a NULL Connection handle + * - Connection level: by passing a valid Connection handle + * + * When the library needs to perform a string conversion, it search for a valid format using the + * following order: + * - Connection format + * - Library format + * - Default format + * + * @note + * Possible values of parameter 'type' : + * + * - OCI_FMT_DATE : format used to convert DATE to string + * - OCI_FMT_TIMESTAMP : format used to convert TIMESTAMP to string + * - OCI_FMT_NUMERIC : format used to convert numeric types to string + * - OCI_FMT_BINARY_DOUBLE : format used to convert BINARY_DOUBLE to string + * - OCI_FMT_BINARY FLOAT : format used to convert BINARY_FLOAT to string + * + * @note + * Default format values are : + * - OCI_FMT_DATE : constant OCI_STRING_FORMAT_DATE + * - OCI_FMT_TIMESTAMP : constant OCI_STRING_FORMAT_TIMESTAMP + * - OCI_FMT_NUMERIC : constant OCI_STRING_FORMAT_NUMERIC + * - OCI_FMT_BINARY_DOUBLE : constant OCI_STRING_FORMAT_BINARY_DOUBLE + * - OCI_FMT_BINARY FLOAT : constant OCI_STRING_FORMAT_BINARY_FLOAT + * + * @note + * Conversions are performed by Oracle built-in functions whenever possible. + * For DATE, TIMESTAMP and numeric types, see documentation of Oracle SQL to_char() function for more details + * For BINARY_DOUBLE and BINARY_FLOAT, refer to the C Standard Library printf() family documentation + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetFormat +( + OCI_Connection *con, + unsigned int type, + const otext *format +); + +/** + * @brief + * Return the format string for implicit string conversions of the given type + * + * @param con - Connection handle + * @param type - Type of format + * + * @note + * See OCI_SetFormat() for possible values + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetFormat +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Return the current transaction of the connection + * + * @param con - Connection handle + * + * @note + * From v3.9.4, no more default transaction object is created for a new connection + * + */ + +OCI_EXPORT OCI_Transaction * OCI_API OCI_GetTransaction +( + OCI_Connection *con +); + +/** + * @brief + * Set a transaction to a connection + * + * @param con - Connection handle + * @param trans - Transaction handle to assign + * + * @note + * The current transaction (if any) is automatically stopped but the newly assigned is not + * started or resumed + * + * @warning + * Do not set transaction object to XA connection or connection retrieved from a session pool + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetTransaction +( + OCI_Connection *con, + OCI_Transaction *trans +); + +/** + * @brief + * Return the highest Oracle version is supported by the connection + * + * @param con - connection handle + * + * @note + * The highest supported version is the lower version between client and server: + * + * @note + * Returns one of the following values: + * + * - OCI_UNKNOWN + * - OCI_8_0 + * - OCI_8_1 + * - OCI_9_0 + * - OCI_9_2 + * - OCI_10_1 + * - OCI_10_2 + * - OCI_11_1 + * - OCI_11_2 + * - OCI_12_1 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetVersionConnection +( + OCI_Connection *con +); + +/** + * @brief + * Set tracing information to the session of the given connection + * + * @param con - connection handle + * @param trace - trace type + * @param value - trace content + * + * Store current trace information to the given connection handle. + * These information: + * + * - is stored in the system view V$SESSION + * - can be retrieved from the connection property of an OCI_Error handle + * + * @note + * Possible values of parameter 'trace' : + * + * - OCI_TRC_IDENTITY : Specifies the user defined identifier in the session. + * It's recorded in the column CLIENT_IDENTIFIER of the + * system view V$SESSION + * - OCI_TRC_MODULE : name of the current module in the client application. + * It's recorded in the column MODULE of the + * system view V$SESSION + * - OCI_TRC_ACTION : name of the current action within the current module. + * It's recorded in the column ACTION of the + * system view V$SESSION + * - OCI_TRC_DETAIL : Client application additional information. + * It's recorded in the column CLIENT_INFO of the + * system view V$SESSION + * + * @warning + * The system view V$SESSION is updated on Oracle versions >= 10g + * + * @warning + * Oracle limits the size of these traces content and thus OCILIB will truncate + * the given values if needed : + * + * - OCI_TRC_IDENTITY : 64 bytes + * - OCI_TRC_MODULE : 48 bytes + * - OCI_TRC_ACTION : 32 bytes + * - OCI_TRC_DETAIL : 64 bytes + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetTrace +( + OCI_Connection *con, + unsigned int trace, + const otext *value +); + +/** + * @brief + * Get the current trace for the trace type from the given connection. + * + * @param con - connection handle + * @param trace - trace type + * + * @note + * See OCI_SetTrace() for more details. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetTrace +( + OCI_Connection *con, + unsigned int trace +); + +/** + * @brief + * Makes a round trip call to the server to confirm that the connection and the server are active. + * + * @param con - Connection handle + * + * @note + * Returns TRUE is the connection is still alive otherwise FALSE + * + * @warning + * This call is supported from Oracle 10g. + * For previous versions, it returns FALSE without throwing any exception. + * + */ + +OCI_EXPORT boolean OCI_API OCI_Ping +( + OCI_Connection *con +); + +/** + * @brief + * Return the Oracle server database name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetDBName +( + OCI_Connection *con +); + +/** + * @brief + * Return the Oracle server Instance name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetInstanceName +( + OCI_Connection *con +); + + +/** + * @brief + * Return the Oracle server service name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetServiceName +( + OCI_Connection *con +); + + +/** + * @brief + * Return the Oracle server machine name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetServerName +( + OCI_Connection *con +); + + +/** + * @brief + * Return the Oracle server domain name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetDomainName +( + OCI_Connection *con +); + + +/** + * @brief + * Return the date and time (Timestamp) server instance start of the + * connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_GetInstanceStartTime +( + OCI_Connection *con +); + +/** + * @brief + * Verify if the given connection support TAF events + * + * @param con - Connection handle + * + * @note + * Returns TRUE is the connection supports TAF event otherwise FALSE + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns FALSE without throwing any exception. + * + */ + +OCI_EXPORT boolean OCI_API OCI_IsTAFCapable +( + OCI_Connection *con +); + +/** + * @brief + * Set the Transparent Application Failover (TAF) user handler + * + * @param con - Connection handle + * @param handler - Pointer to TAF handler procedure + * + * @note + * See POCI_TAF_HANDLER documentation for more details + * +* @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns FALSE without throwing any exception. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetTAFHandler +( + OCI_Connection *con, + POCI_TAF_HANDLER handler +); + +/** + * @brief + * Return the maximum number of statements to keep in the statement cache + * + * @param con - Connection handle + * + * @note + * Default value is 20 (value from Oracle Documentation) + * + * @warning + * Requires Oracle Client 9.2 or above + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetStatementCacheSize +( + OCI_Connection *con +); + +/** + * @brief + * Set the maximum number of statements to keep in the statement cache + * + * @param con - Connection handle + * @param value - maximum number of statements in the cache + * + * @warning + * Requires Oracle Client 9.2 or above + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetStatementCacheSize +( + OCI_Connection *con, + unsigned int value +); + +/** + * @brief + * Return the default LOB prefetch buffer size for the connection + * + * @param con - Connection handle + * + * @warning + * Requires Oracle Client AND Server 11gR1 or above + * + * @note + * Prefetch size is: + * - number of bytes for BLOBs and BFILEs + * - number of characters for CLOBs. + * + * @note + * Default is 0 (prefetching disabled) + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetDefaultLobPrefetchSize +( + OCI_Connection *con +); + +/** + * @brief + * Enable or disable prefetching for all LOBs fetched in the connection + * + * @param con - Connection handle + * @param value - default prefetch buffer size + * + * @note + * If parameter 'value': + * - is == 0, it disables prefetching for all LOBs fetched in the connection. + * - is > 0, it enables prefetching for all LOBs fetched in the connection + * and the given buffer size is used for prefetching LOBs + * + * @note + * LOBs prefetching is disabled by default + * + * @warning + * Requires Oracle Client AND Server 11gR1 or above. + * + * @note + * Prefetch size is: + * - number of bytes for BLOBs and BFILEs + * - number of characters for CLOBs. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetDefaultLobPrefetchSize +( + OCI_Connection *con, + unsigned int value +); + + +/** +* @brief +* Return the maximum number of SQL statements that can be opened in one session +* +* @param con - Connection handle +* +* @warning +* Requires Oracle Client AND Server 12cR1 or above +* +* @note +* the returned value is the same as the db parameter 'open_cursors' from server's parameter file +* +* @note +* Return 0 if the client and server version are < 12cR1 +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_GetMaxCursors +( + OCI_Connection *con +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiPools Oracle Pools + * @{ + * + * OCILIB support the connections and sessions pooling features introduced + * in Oracle 9i. + * + * Let's Oracle talk about this features ! + * + * @par Connection pools (from Oracle Call Interface Programmer's Guide) + * + * Connection pooling is the use of a group (the pool) of reusable physical connections + * by several sessions, in order to balance loads. The management of the pool is done + * by OCI, not the application. Applications that can use connection pooling include + * middle-tier applications for Web application servers and e-mail servers. + * + * @par Session Pools (from Oracle Call Interface Programmer's Guide) + * + * Session pooling means that the application will create and maintain a group of stateless + * sessions to the database. These sessions will be handed over to thin clients as requested. + * If no sessions are available, a new one may be created. When the client is done with + * the session, the client will release it to the pool. Thus, the number of sessions in + * the pool can increase dynamically. + * + * @note + * OCILIB implements homogeneous session pools only. + * + * @par When using Pools (from Oracle Call Interface Programmer's Guide) + * + * If database sessions are not reusable by mid-tier threads (that is, they are stateful) + * and the number of back-end server processes may cause scaling problems on the database, + * use OCI connection pooling. + * + * If database sessions are reusable by mid-tier threads (that is, they are stateless) + * and the number of back-end server processes may cause scaling problems on the database, + * use OCI session pooling. + * + * If database sessions are not reusable by mid-tier threads (that is, they are stateful) + * and the number of back-end server processes will never be large enough to potentially + * cause any scaling issue on the database, there is no need to use any pooling mechanism. + * + * @par Oracle 8i support + * + * Pooling has bee introduced in : + * - 9iR1 for connection pools + * - 9iR2 for session pools + * For Oracle 8i, OCILIB implements its own pooling mechanism in order to remain compatible + * with older versions. But sessions pools then are handled as connection pools + * + * @par Example + * @include pool.c + * + */ + +/** + * @brief + * Create an Oracle pool of connections or sessions + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param type - Type of pool + * @param mode - Session mode + * @param min_con - minimum number of connections/sessions that can be opened. + * @param max_con - maximum number of connections/sessions that can be opened. + * @param incr_con - next increment for connections/sessions to be opened + * + * Possible values for parameter 'type': + * - OCI_POOL_CONNECTION + * - OCI_POOL_SESSION + * + * Possible values for parameter 'mode': + * - OCI_SESSION_DEFAULT + * - OCI_SESSION_SYSDAB + * - OCI_SESSION_SYSOPER + * + * @note + * External credentials are supported by supplying a null value for the 'user' + * and 'pwd' parameters + * If the param 'db' is NULL then a connection to the default local DB is done + * + * @return + * Connection or session pool handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Pool * OCI_API OCI_PoolCreate +( + const otext *db, + const otext *user, + const otext *pwd, + unsigned int type, + unsigned int mode, + unsigned int min_con, + unsigned int max_con, + unsigned int incr_con +); + +/** + * @brief + * Destroy a pool object + * + * @param pool - Pool handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolFree +( + OCI_Pool *pool +); + +/** + * @brief + * Get a connection from the pool + * + * @param pool - Pool handle + * @param tag - user tag string + * + * @par Session tagging + * + * Session pools have a nice feature that is 'session tagging' + * It's possible to tag a session with a string identifier + * when the session is returned to the pool, it keeps its tags. + * When requesting a connection from the session pool, it's + * possible to request a session that has the given 'tag' parameter + * If one exists, it is returned. If not and if an untagged session + * is available, it is then returned. So check the connection tag + * property with OCI_GetSessionTag() to find out if the returned + * connection is tagged or not. + * + * This features is described in the OCI developer guide as the following : + * + * "The tags provide a way for users to customize sessions in the pool. + * A client may get a default or untagged session from a pool, set certain + * attributes on the session (such as NLS settings), and return the session + * to the pool, labeling it with an appropriate tag. + * The user may request a session with the same tags in order to have a + * session with the same attributes" + * + * @return + * Connection handle otherwise NULL on failure + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_PoolGetConnection +( + OCI_Pool *pool, + const otext *tag +); + +/** + * @brief + * Get the idle timeout for connections/sessions in the pool + * + * @param pool - Pool handle + * + * @note + * Connections/sessions idle for more than this time value (in seconds) is terminated + * + * @note + * Timeout is not available for internal pooling implementation (client < 9i) + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetTimeout +( + OCI_Pool *pool +); + +/** + * @brief + * Set the connections/sessions idle timeout + * + * @param pool - Pool handle + * @param value - Timeout value + * + * @note + * connections/sessions idle for more than this time value (in seconds) is terminated + * + * @note + * This call has no effect if pooling is internally implemented (client < 9i) + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolSetTimeout +( + OCI_Pool *pool, + unsigned int value +); + +/** + * @brief + * Get the waiting mode used when no more connections/sessions are available + * from the pool + * + * @param pool - Pool handle + * + * @return + * - FALSE to wait for an available object if the pool is saturated + * - TRUE to not wait for an available object + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolGetNoWait +( + OCI_Pool *pool +); + +/** + * @brief + * Set the waiting mode used when no more connections/sessions are available + * from the pool + * + * @param pool - Pool handle + * @param value - wait for object + * + * @note + * Pass : + * - FALSE to wait for an available object if the pool is saturated + * - TRUE to not wait for an available object + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolSetNoWait +( + OCI_Pool *pool, + boolean value +); + +/** + * @brief + * Return the current number of busy connections/sessions + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetBusyCount +( + OCI_Pool *pool +); + +/** + * @brief + * Return the current number of opened connections/sessions + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetOpenedCount +( + OCI_Pool *pool +); + +/** + * @brief + * Return the minimum number of connections/sessions that can be opened to the database + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetMin +( + OCI_Pool *pool +); + +/** + * @brief + * Return the maximum number of connections/sessions that can be opened to the database + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetMax +( + OCI_Pool *pool +); + +/** + * @brief + * Return the increment for connections/sessions to be opened to the database when the pool is + * not full + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetIncrement +( + OCI_Pool *pool +); + +/** + * @brief + * Return the maximum number of statements to keep in the pool statement cache + * + * @param pool - Pool handle + * + * @note + * Default value is 20 (value from Oracle Documentation) + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetStatementCacheSize +( + OCI_Pool *pool +); + +/** + * @brief + * Set the maximum number of statements to keep in the pool statement cache + * + * @param pool - Pool handle + * @param value - maximum number of statements in the cache + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolSetStatementCacheSize +( + OCI_Pool *pool, + unsigned int value +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiTransactions Managing transactions + * @{ + * + * OCILIB supports local and global transactions. + * + * Local transactions are implicit within connection objects and there is no + * specific call or programming step for using it. + * + * In order to control changes made in the database: + * + * - OCI_Commit() validates current pending modifications + * - OCI_Rollback() discards current pending modifications + * + * OCILIB supports a feature called 'Auto Commit' that performs an implicit and + * automatic commit call after every execute call + * + * @note + * Those actions are executed within a connection context and not directly to a transaction. + * + * @warning + * Global transactions are optional and are designed for distributed or global + * transaction environments. + * + * OCILIB supports them by : + * + * - Creating/Destroying explicitly a transaction object + * - Starting/Stopping/Resuming explicitly the transaction + * - Preparing the transaction for specific calls + * + */ + +/** + * @brief + * Commit current pending changes + * + * @param con - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_Commit +( + OCI_Connection *con +); + +/** + * @brief + * Cancel current pending changes + * + * @param con - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_Rollback +( + OCI_Connection *con +); + +/** + * @brief + * Enable / disable auto commit mode + * + * The auto commit mode allows commit changes after every executed SQL order + * + * @param con - Connection handle + * @param enable - Enable (TRUE) or disable (FALSE) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetAutoCommit +( + OCI_Connection *con, + boolean enable +); + +/** + * @brief + * Get current auto commit mode status + * + * @param con - Connection handle + * + * @return + * TRUE if auto commit mode is activated otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_GetAutoCommit +( + OCI_Connection *con +); + +/** + * @brief + * Create a new global transaction or a serializable/read-only local transaction + * + * @param con - Connection handle + * @param timeout - Time that a transaction stays inactive after being stopped + * @param mode - Transaction mode + * @param pxid - pointer to a global transaction identifier structure + * + * + * @note + * The parameter 'mode' can be one of the following values : + * + * - Global transactions: + * - OCI_TRS_NEW : By default starts a new, tightly coupled and + * migratable branch. + * - OCI_TRS_TIGHT : explicitly specifies a tightly coupled branch + * - OCI_TRS_LOOSE : specifies a loosely coupled branch + * + * - Global and local transactions : + * - OCI_TRS_READONLY - start a read-only transaction + * - OCI_TRS_READWRITE - start a read-write transaction + * - OCI_TRS_SERIALIZABLE : start a serializable transaction + * + * @note + * For local transaction: + * - pass a NULL value for pxid + * + */ + +OCI_EXPORT OCI_Transaction * OCI_API OCI_TransactionCreate +( + OCI_Connection *con, + unsigned int timeout, + unsigned int mode, + OCI_XID *pxid +); + +/** + * @brief + * Free current transaction + * + * @param trans - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionFree +( + OCI_Transaction *trans +); + +/** + * @brief + * Start global transaction + * + * @param trans - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionStart +( + OCI_Transaction *trans +); + +/** + * @brief + * Stop current global transaction + * + * @param trans - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionStop +( + OCI_Transaction *trans +); + +/** + * @brief + * Resume a stopped global transaction + * + * @param trans - Global transaction handle + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionResume +( + OCI_Transaction *trans +); + +/** + * @brief + * Prepare a global transaction validation + * + * @param trans - Global transaction handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionPrepare +( + OCI_Transaction *trans +); + +/** + * @brief + * Cancel the prepared global transaction validation + * + * @param trans - Global transaction handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionForget +( + OCI_Transaction *trans +); + +/** + * @brief + * Return global transaction mode. + * + * @note: + * see OCI_TransactionCreate() for possible values + * + * @param trans - Global transaction handle + * + * @return + * Transaction mode or OCI_UNKNOW if trans is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TransactionGetMode +( + OCI_Transaction *trans +); + +/** + * @brief + * Return global transaction Timeout + * + * @param trans - Global transaction handle + * + * @return + * Transaction timeout or 0 if trans is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TransactionGetTimeout +( + OCI_Transaction *trans +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiStatements Executing statements + * @{ + * + * Executing SQL statements or PL/SQL blocks is really simple with OCILIB. + * + * First, call OCI_StatementCreate() to allocate a statement handle. Then : + * + * - Prepare the SQL with OCI_Prepare() + * - Parse and execute it with OCI_Execute() + * + * These two steps can be done together by calling OCI_ExecuteStmt() that + * prepares and executes in one go. + * + * To find out if the statement has affected any rows, call OCI_GetAffectedRows() + * + * Finally, release the statement and its resources with OCI_StatementFree() + * + * @note + * A statement can be prepared once and executed as many times as needed (see + * Binding variables section) + * + * @note + * An OCI_Statement can be used to prepare and/or execute different SQL and PL/SQL + * statements as many times as needed. + * For example, if the SQL processing of an application is sequential, only + * one statement handle is required + * + * @note + * OCILIB supports nested levels of SQL statement processing. + * An application can loop through the resultset of the statement handle A, + * executing statement B and fetching statement C at every loop, and so on ... + * + * @par Example + * @include exec.c + * + */ + +/** + * @brief + * Create a statement object and return its handle + * + * @param con - Connection handle + * + * @return + * A statement handle on success otherwise NULL + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_StatementCreate +( + OCI_Connection *con +); + +/** + * @brief + * Free a statement and all resources associated to it (resultsets ...) + * + * @param stmt - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_StatementFree +( + OCI_Statement *stmt +); + +/** + * @brief + * Prepare a SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL order or PL/SQL block + * + * @note + * Do not call this function for fetched statements (REF cursors) + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_Prepare +( + OCI_Statement *stmt, + const otext *sql +); + +/** + * @brief + * Execute a prepared SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * + * @return + * TRUE on success otherwise FALSE + * + * @warning + * If a SQL warning occurs: + * - the function returns TRUE + * - the SQL warning triggers the global error handler with an OCI_Error having its OCI_ErrorGetType() + * attribute set to OCI_ERR_WARNING + * - If OCILIB is initialized with the OCI_ENV_CONTEXT mode, OCI_GetLastError() will return the OCI_Error + * object corresponding to the warning + * + */ + +OCI_EXPORT boolean OCI_API OCI_Execute +( + OCI_Statement *stmt +); + +/** + * @brief + * Prepare and Execute a SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL order - PL/SQL block + * + * @return + * TRUE on success otherwise FALSE + * + * @warning + * If a SQL warning occurs: + * - the function returns TRUE + * - the SQL warning triggers the global error handler with an OCI_Error having its OCI_ErrorGetType() + * attribute set to OCI_ERR_WARNING + * - If OCILIB is initialized with the OCI_ENV_CONTEXT mode, OCI_GetLastError() will return the OCI_Error + * object corresponding to the warning + * + */ + +OCI_EXPORT boolean OCI_API OCI_ExecuteStmt +( + OCI_Statement *stmt, + const otext *sql +); + +/** + * @brief + * Parse a SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL order - PL/SQL block + * + * @note + * This call sends the SQL or PL/SQL command to the server for parsing only. + * The command is not executed. + * This call is only useful to check is a command is valid or not. + * + * @note + * This call prepares the statement (internal call to OCI_Prepare()) and ask + * the Oracle server to parse its SQL or PL/SQL command. + * OCI_Execute() can be call after OCI_Parse() in order to execute the + * statement, which means that the server will re-parse again the command. + * + * @warning + * Do not use OCI_Parse() unless you're only interested in the parsing result + * because the statement will be parsed again when executed and thus leading to + * unnecessary server round-trips and less performance + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_Parse +( + OCI_Statement *stmt, + const otext *sql +); + +/** + * @brief + * Describe the select list of a SQL select statement. + * + * @param stmt - Statement handle + * @param sql - SELECT sql statement + * + * @note + * This call sends the SELECT SQL order to the server for retrieving the + * description of the select order only. + * The command is not executed. + * This call is only useful to retrieve information on the associated resultset + * Call OCI_GetResultet() after OCI_Describe() to access to SELECT list + * information + * + * @note + * This call prepares the statement (internal call to OCI_Prepare()) and ask + * the Oracle server to describe the output SELECT list. + * OCI_Execute() can be called after OCI_Desbribe() in order to execute the + * statement, which means that the server will parse, and describe again the SQL + * order. + * + * @warning + * Do not use OCI_Desbribe() unless you're only interested in the resultset + * information because the statement will be parsed again when executed and thus + * leading to unnecessary server round-trips and less performance + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_Describe +( + OCI_Statement *stmt, + const otext *sql +); + +/** + * @brief + * Return the last SQL or PL/SQL statement prepared or executed by the statement + * + * @param stmt - Statement handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetSql +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the error position (in terms of characters) in the SQL statement + * where the error occurred in case of SQL parsing error + * + * @param stmt - Statement handle + * + * @note + * Positions start at 1. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetSqlErrorPos +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the number of rows affected by the SQL statement + * + * @param stmt - Statement handle + * + * The returned value is : + * - For UPDATEs : number of rows updated + * - For INSERTs : number of rows inserted + * - For DELETEs : number of rows deleted + * + * @note + * For SELECTs statements, use OCI_GetRowCount() instead + * + * @note + * For PL/SQL blocks performing "select into :": + * - it returns the number of rows selected from PL/SQL + * - Up to version 4.3.0, OCI_Execute() returned FALSE and generated an error ORA-01403 - "No Data Found" + * - From version 4.3.1, OCI_Execute() returns 0 if no data found, otherwise the number of selected rows + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetAffectedRows +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the Oracle SQL code the command held by the statement handle + * + * @param stmt - Statement handle + * + * @warning + * OCI_GetSQLCommand() must be called after the statement has be executed + * because that's the server engine that computes the SQL command code + * + * @return + * The SQL command code of the statement otherwise OCI_UNKOWN + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetSQLCommand +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the verb of the SQL command held by the statement handle + * + * @param stmt - Statement handle + * + * @warning + * OCI_GetSQLVerb() must be called after the statement has been executed + * because that's the server engine that computes the SQL verb + * + * @note + * The SQL verb list is available in Oracle documentations and guides + * + * @return + * The SQL command verb of the statement otherwise NULL + */ + +OCI_EXPORT const otext * OCI_API OCI_GetSQLVerb +( + OCI_Statement *stmt +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiBinding Binding variables and arrays + * @{ + * + * OCILIB supports OCI data binding APIs + * + * Programs variables can be binded to an Oracle SQL PL/SQL statement in order to : + * + * - Provide input data for SQL statement + * - Provide input/output data for PL/SQL blocks + * + * OCILIB provides a set of binding functions to use with: + * + * - Basic data types: string (char/wchar_t *), int, float, double, raw + * - Object data types: lobs, files,longs, dates, cursors, statements, + * timestamps, intervals, objects + * + * To use binding: + * + * - Prepare a statement with OCI_Prepare() (see Executing statements) + * - Bind variables by calling one if the OCI_Bindxxxxx() function for every + * input variable referenced by the SQL statement + * - Setup up values of the program variables + * - Call OCI_Execute() as many times as needed + * - Each OCI_Execute() call may be preceded by an update of the program + * variables (for INSERTs for example) + * + * Bindings can be: + * - IN (host variable are not used anymore after statement execution) + * - OUT (host variable are set during statement execution) + * - IN/OUT (default) + * Use OCI_BindSetDirectionTo() to change a host variable bind direction mode after the binding call but before statement execution. + * Note that each direction mode may have a little overhead depending on the SQL type as OCILIB may have to do checks/conversions/mappings between host variable and buffers. + * Thus, to maximize performances: + * - set direction mode to OCI_BDM_IN if host variable is not updated by statement execution + * - set direction mode to OCI_BDM_OUT if host variable value does not matter prior to statement execution + * - set direction mode to OCI_BDM_IN_OUT when host variable value is used for execution and updated by statement execution + * + * OCILIB supports the OCI array Interface by binding arrays of C scalar types + * and OCILIB object types. + * + * - all types supported the library can be used for array binding except + * OCI_Statement and OCI_Long + * - Array binding is really fast for massive DML operations + * - For string/RAW arrays, the input array MUST BE a contiguous block of data + * and not an array of pointers. So to bind an array of 10 elements for a + * varchar2(30) column, binded variable must be a like array[10][31] + * + * OCILIB does not pre-parse statements (like other frameworks such as JDBC, ...) + * and lets Oracle recognize input variables embedded within the SQL statements. + * + * Bind variables must be preceded in the SQL code by the character ':'. + * + * Oracle and OCILIB supports two ways of binding: + * + * - by name (default mode in OCILIB): Oracle looks for variables in the SQL + * statement by searching their names provided to the binding function. + * So a variable can be binded once and used many times in the statement + * - by position: Oracle binds variables by position, so every variable is + * binded with a position number + * + * OCILIB Default binding mode is OCI_BIND_BY_NAME. + * + * When using binding by position, provide the position to OCI_BindXXXX() call + * through the name parameter. Within this mode the bind name must be the + * position preceded by a semicolon like ':1', ':2', .... + * + * @par Internal Bind allocation mode + * + * Bind variables or arrays can be internally allocated by OCILIB. + * That means that instead of allocating variables or arrays on the stack/heap + * in the user program, bind contents can be allocated internally and thus : + * - minimize the amount of program variables + * - optimize internal memory management for arrays + * + * To do so : + * - Call OCI_SetBindAllocation() with the mode OCI_BAM_INTERNAL + * - pass a NULL variable or array to OCI_BindXXX() calls + * - Retrieve the bind content allocated by OCILIB with OCI_BindGetData() + * + * Internal Bind allocation mode IS compatible with ALL array binding OCI_BindArrayOfxxx() methods. + * + * Internal Bind allocation mode IS NOT compatible with some single variable bind calls : + * - OCI_BindTimestamp() + * - OCI_BindInterval() + * - OCI_BindLob() + * - OCI_BindFile() + * - OCI_BindObject() + * - OCI_BindColl() + * - OCI_BindRef() + * - OCI_BindStatement() + * - OCI_BindLong() + * + * These methods need to know the data sub type (like OCI_CLOB/OCI_BLOB for lobs) in order + * to internally create variables. As these methods prototypes are not passing the sub type, + * calling them with the statement bind mode set to OCI_BAM_INTERNAL will raise + * an OCILIB error of type OCI_ERR_NULL_POINTER + * + * @note + * Rebinding is disabled by default (see OCI_AllowRebinding()) + * When using rebinding feature, host variable re-binded to a previously allocated + * bind MUST be of the SAME data type ! + * + * @par Basic input bind Example + * @include bind.c + * + * @par Array interface Example + * @include array.c + * + * @par Internal Array interface Example + * @include array_internal.c + * + * */ + +/** + * @brief + * Set the input array size for bulk operations + * + * @param stmt - Statement handle + * @param size - Array size + * + * @warning + * Do not use OCI_BindArraySetSize() for PL/SQL tables binding + * + * @note + * OCI_BindArraySetSize() is used to set the size of input bind array when using + * arrays for DML statements. + * OCI_BindArraySetSize() MUST be called to set the maximum size of the arrays + * to bind to the statement before any of its execution. This initial call must + * be bone AFTER OCI_Prepare() and BEFORE any OCI_BindArrayOfxxx() call. + * + * @note + * OCI_BindArraySetSize() can optionally be called before any later OCI_Execute() + * call in order to notify the statement of the exact number of elements + * populating the input arrays for the next execution. The array size passed to + * later OCI_BindArraySetSize() calls cannot be greater than the initial size + * otherwise an exception will be thrown. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArraySetSize +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the current input array size for bulk operations + * + * @param stmt - Statement handle + * + * @return + * Array size value or 0 if OCI_BindArraySetSize() has not been called + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindArrayGetSize +( + OCI_Statement *stmt +); + +/** + * @brief + * Allow different host variables to be binded using the same bind name or + * position between executions of a prepared statement + * + * @param stmt - Statement handle + * @param value - Rebinding mode allowed + * + * @note + * Default value is FALSE + * + * @warning + * When using rebinding feature, host variable re-binded to a previously allocated + * bind MUST be of the same data type ! + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_AllowRebinding +( + OCI_Statement *stmt, + boolean value +); + +/** + * @brief + * Indicate if rebinding is allowed on the given statement + * + * @param stmt - Statement handle + * + * @note + * See OCI_AllowRebinding() for more details + * + * @return + * TRUE if allowed otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_IsRebindingAllowed +( + OCI_Statement *stmt +); + +/** +* @brief +* Bind a boolean variable (PL/SQL ONLY) +* +* @param stmt - Statement handle +* @param name - Variable name +* @param data - Pointer to boolean variable +* +* @note +* parameter 'data' can NULL if the statement bind allocation mode +* has been set to OCI_BAM_INTERNAL +* +* @warning +* - OCI_BindBoolean() CAN ONLY BE USED for PL/SQL boolean type when calling PL/SQL procedures/function +* - ONLY supported by Oracle 12c and above ! +* +* @return +* TRUE on success otherwise FALSE +*/ +OCI_EXPORT boolean OCI_API OCI_BindBoolean +( + OCI_Statement *stmt, + const otext *name, + boolean *data +); + +/** +* @brief +* Bind an Number variable +* +* @param stmt - Statement handle +* @param name - Variable name +* @param data - Pointer to short variable +* +* @note +* parameter 'data' can NULL if the statement bind allocation mode +* has been set to OCI_BAM_INTERNAL +* +* @return +* TRUE on success otherwise FALSE +*/ + +OCI_EXPORT boolean OCI_API OCI_BindNumber +( + OCI_Statement *stmt, + const otext *name, + OCI_Number *data +); + +/** +* @brief +* Bind an array of Number +* +* @param stmt - Statement handle +* @param name - Variable name +* @param data - Array of numbers +* @param nbelem - Number of element in the array (PL/SQL table only) +* +* @warning +* Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. +* For regular DML array operations, pass the value 0. +* +* @note +* parameter 'data' can NULL if the statement bind allocation mode +* has been set to OCI_BAM_INTERNAL +* +* @return +* TRUE on success otherwise FALSE +*/ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfNumbers +( + OCI_Statement *stmt, + const otext *name, + OCI_Number **data, + unsigned int nbelem +); + +/** + * @brief + * Bind an short variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to short variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindShort +( + OCI_Statement *stmt, + const otext *name, + short *data +); + +/** + * @brief + * Bind an array of shorts + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of shorts + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfShorts +( + OCI_Statement *stmt, + const otext *name, + short *data, + unsigned int nbelem +); + +/** + * @brief + * Bind an unsigned short variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to unsigned short variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindUnsignedShort +( + OCI_Statement *stmt, + const otext *name, + unsigned short *data +); + +/** + * @brief + * Bind an array of unsigned shorts + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of unsigned shorts + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfUnsignedShorts +( + OCI_Statement *stmt, + const otext *name, + unsigned short *data, + unsigned int nbelem +); + +/** + * @brief + * Bind an integer variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to int variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindInt +( + OCI_Statement *stmt, + const otext *name, + int *data +); + +/** + * @brief + * Bind an array of integers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of int + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfInts +( + OCI_Statement *stmt, + const otext *name, + int *data, + unsigned int nbelem +); + +/** + * @brief + * Bind an unsigned integer variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to unsigned int variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindUnsignedInt +( + OCI_Statement *stmt, + const otext *name, + unsigned int *data +); + +/** + * @brief + * Bind an array of unsigned integers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of unsigned int + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfUnsignedInts +( + OCI_Statement *stmt, + const otext *name, + unsigned int *data, + unsigned int nbelem +); + +/** + * @brief + * Bind a big integer variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to big int variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindBigInt +( + OCI_Statement *stmt, + const otext *name, + big_int *data +); + +/** + * @brief + * Bind an array of big integers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of big int + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfBigInts +( + OCI_Statement *stmt, + const otext *name, + big_int *data, + unsigned int nbelem +); + +/** + * @brief + * Bind an unsigned big integer variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to unsigned big int variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindUnsignedBigInt +( + OCI_Statement *stmt, + const otext *name, + big_uint *data +); + +/** + * @brief + * Bind an array of unsigned big integers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of unsigned big int + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfUnsignedBigInts +( + OCI_Statement *stmt, + const otext *name, + big_uint *data, + unsigned int nbelem +); + +/** + * @brief + * Bind a string variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - String to bind + * @param len - Max length of the string (in character without + * the zero null terminal character) + * + * @note + * if len == 0, len is set to the string size + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindString +( + OCI_Statement *stmt, + const otext *name, + otext *data, + unsigned int len +); + +/** + * @brief + * Bind an array of strings + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of string + * @param len - Max length of a single string element (in character without + * the zero null terminal character) + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @warning + * if len <= 0, it returns FALSE + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfStrings +( + OCI_Statement *stmt, + const otext *name, + otext *data, + unsigned int len, + unsigned int nbelem +); + +/** + * @brief + * Bind a raw buffer + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - buffer to bind + * @param len - Max length of the buffer + * + * @note + * if len <= 0, it returns false + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindRaw +( + OCI_Statement *stmt, + const otext *name, + void *data, + unsigned int len +); + +/** + * @brief + * Bind an array of raw buffers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of buffers + * @param len - Size in bytes on a single RAW array element + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * The buffer must be a contiguous block of data elements + * + * @note + * If len <= 0, it returns FALSE + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfRaws +( + OCI_Statement *stmt, + const otext *name, + void *data, + unsigned int len, + unsigned int nbelem +); + +/** + * @brief + * Bind a double variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to double variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindDouble +( + OCI_Statement *stmt, + const otext *name, + double *data +); + +/** + * @brief + * Bind an array of doubles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of double + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfDoubles +( + OCI_Statement *stmt, + const otext *name, + double *data, + unsigned int nbelem +); + + +/** + * @brief + * Bind a float variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to float variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindFloat +( + OCI_Statement *stmt, + const otext *name, + float *data +); + +/** + * @brief + * Bind an array of floats + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of float + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfFloats +( + OCI_Statement *stmt, + const otext *name, + float *data, + unsigned int nbelem +); + +/** + * @brief + * Bind a date variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Date handle + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindDate +( + OCI_Statement *stmt, + const otext *name, + OCI_Date *data +); + +/** + * @brief + * Bind an array of dates + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of date handle + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfDates +( + OCI_Statement *stmt, + const otext *name, + OCI_Date **data, + unsigned int nbelem +); + +/** + * @brief + * Bind a timestamp variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Timestamp handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindTimestamp +( + OCI_Statement *stmt, + const otext *name, + OCI_Timestamp *data +); + +/** + * @brief + * Bind an array of timestamp handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Timestamp handle + * @param type - Timestamp type + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_TimestampCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfTimestamps +( + OCI_Statement *stmt, + const otext *name, + OCI_Timestamp **data, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Bind an interval variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Interval handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindInterval +( + OCI_Statement *stmt, + const otext *name, + OCI_Interval *data +); + +/** + * @brief + * Bind an array of interval handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Interval handle + * @param type - Interval type + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_IntervalCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfIntervals +( + OCI_Statement *stmt, + const otext *name, + OCI_Interval **data, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Bind a Lob variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Lob handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindLob +( + OCI_Statement *stmt, + const otext *name, + OCI_Lob *data +); + +/** + * @brief + * Bind an array of Lob handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Lob handle + * @param type - Lob type + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_LobCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfLobs +( + OCI_Statement *stmt, + const otext *name, + OCI_Lob **data, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Bind a File variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - File handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindFile +( + OCI_Statement *stmt, + const otext *name, + OCI_File *data +); + +/** + * @brief + * Bind an array of File handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of File handle + * @param type - File type + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_FileCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfFiles +( + OCI_Statement *stmt, + const otext *name, + OCI_File **data, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Bind an object (named type) variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Object handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindObject +( + OCI_Statement *stmt, + const otext *name, + OCI_Object *data +); + +/** + * @brief + * Bind an array of object handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of object handle + * @param typinf - type info handle + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfObjects +( + OCI_Statement *stmt, + const otext *name, + OCI_Object **data, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Bind a Collection variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Collection handle to bind + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindColl +( + OCI_Statement *stmt, + const otext *name, + OCI_Coll *data +); + +/** + * @brief + * Bind an array of Collection handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Collection handle + * @param typinf - Type info handle + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_CollCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfColls +( + OCI_Statement *stmt, + const otext *name, + OCI_Coll **data, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Bind a Ref variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Ref handle to bind + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindRef +( + OCI_Statement *stmt, + const otext *name, + OCI_Ref *data +); + +/** + * @brief + * Bind an array of Ref handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Ref handle + * @param typinf - type info handle + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfRefs +( + OCI_Statement *stmt, + const otext *name, + OCI_Ref **data, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Bind a Statement variable (PL/SQL Ref Cursor) + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Statement handle to bind + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindStatement +( + OCI_Statement *stmt, + const otext *name, + OCI_Statement *data +); + +/** + * @brief + * Bind a Long variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Long handle + * @param size - Size of the long buffer in bytes or characters + * + * @note + * Size is expressed in: + * - Bytes for BLONGs + * - Characters for CLONGs + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindLong +( + OCI_Statement *stmt, + const otext *name, + OCI_Long *data, + unsigned int size +); + +/** + * @brief + * Returns the first or next error that occurred within a DML array statement execution + * + * @param stmt - Statement handle + * + * @return + * The first or next error handle otherwise NULL + */ + +OCI_EXPORT OCI_Error * OCI_API OCI_GetBatchError +( + OCI_Statement *stmt +); + +/** + * @brief + * Returns the number of errors that occurred within the last DML array statement + * + * @param stmt - Statement handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetBatchErrorCount +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the number of binds currently associated to a statement + * + * @param stmt - Statement handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetBindCount +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the bind handle at the given index in the internal array of bind + * handle + * + * @param stmt - Statement handle + * @param index - Bind position + * + * @note + * Index starts at 1. + * + * @note + * Bind handle are created sequentially. For example, the third call to a + * OCI_BindXXX() generates a bind handle of index 3. + * + * @return + * The bind handle or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Bind * OCI_API OCI_GetBind +( + OCI_Statement *stmt, + unsigned int index +); + +/** + * @brief + * Return a bind handle from its name + * + * @param stmt - Statement handle + * @param name - Bind variable name + * + * @note + * Bind names must include a semicolon at the beginning. + * + * @return + * The bind handle or NULL if not found + * + */ + +OCI_EXPORT OCI_Bind * OCI_API OCI_GetBind2 +( + OCI_Statement *stmt, + const otext *name +); + +/** +* @brief +* Return the index of the bind from its name belonging to the given statement +* +* @param stmt - Statement handle +* @param name - Bind variable name +* +* @warning +* The bind name is case insensitive +* +* @note +* Bind indexes start with 1 in OCILIB +* +* @return +* Bind index on success or zero if the bind does not exists or if statement is NULL +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_GetBindIndex +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Return the name of the given bind + * + * @param bnd - Bind handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_BindGetName +( + OCI_Bind *bnd +); + + +/** + * @brief + * Set the direction mode of a bind handle + * + * @param bnd - Bind handle + * @param direction - direction mode + * + * @note + * Possible values for parameter 'direction' : + * - OCI_BDM_IN : input values (not modified by the server) + * - OCI_BDM_OUT : output values (modified by the server) + * - OCI_BDM_IN_OUT : input and output values + * + * @note + * Default value is OCI_BDM_IN_OUT + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetDirection +( + OCI_Bind *bnd, + unsigned int direction +); + +/** + * @brief + * Get the direction mode of a bind handle + * + * @param bnd - Bind handle + * + * @note + * see OCI_BindSetDirection() for more details + * + * return the bind direction mode on success otherwise OCI_UNKNWON + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetDirection +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the OCILIB type of the given bind + * + * @param bnd - Bind handle + * + * @note + * Possible values are : + * + * - OCI_CDT_NUMERIC : short, int, long long, float, double + * - OCI_CDT_DATETIME : OCI_Date * + * - OCI_CDT_TEXT : otext * + * - OCI_CDT_LONG : OCI_Long * + * - OCI_CDT_CURSOR : OCI_Statement * + * - OCI_CDT_LOB : OCI_Lob * + * - OCI_CDT_FILE : OCI_File * + * - OCI_CDT_TIMESTAMP : OCI_Timestamp * + * - OCI_CDT_INTERVAL : OCI_Interval * + * - OCI_CDT_RAW : void * + * - OCI_CDT_OBJECT : OCI_Object * + * - OCI_CDT_COLLECTION : OCI_Coll * + * - OCI_CDT_REF : OCI_Ref * + * - OCI_CDT_BOOLEAN : boolean + * + * @return + * The column type or OCI_CDT_UNKNOWN on error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetType +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the OCILIB object subtype of the given bind + * + * @param bnd - Bind handle + * + * @note + * * This call is valid for the following OCILIB types: + * - OCI_CDT_NUMERIC + * - OCI_CDT_LONG + * - OCI_CDT_LOB + * - OCI_CDT_FILE + * - OCI_CDT_TIMESTAMP + * - OCI_CDT_INTERVAL + * + * For numeric binds the possible values are: + * - OCI_NUM_SHORT + * - OCI_NUM_INT + * - OCI_NUM_BIGINT + * - OCI_NUM_USHORT + * - OCI_NUM_UINT + * - OCI_NUM_BIGUINT + * - OCI_NUM_DOUBLE + * - OCI_NUM_FLOAT + * - OCI_NUM_NUMBER + * + * For OCI_Long type the possible values are: + * - OCI_BLONG + * - OCI_CLONG + * + * For OCI_Lob type the possible values are: + * - OCI_BLOB + * - OCI_CLOB + * - OCI_NCLOB + * + * For OCI_File type the possible values are: + * - OCI_BFILE + * - OCI_CFILE + * + * For OCI_Timestamp type the possible values are: + * - OCI_TIMESTAMP + * - OCI_TIMESTAMP_TZ + * - OCI_TIMESTAMP_LTZ + * + * For OCI_Interval type the possible values are: + * - OCI_INTERVAL_YM + * - OCI_INTERVAL_DS + * + * @note + * For all other OCILIB types, it returns OCI_UNKNOWN + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetSubtype +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the number of elements of the bind handle + * + * @param bnd - Bind handle + * + * @return + * - For single binds, it returns 1 + * - For array binds, it returns the number of element in the array + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetDataCount +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the user defined data associated with a bind handle + * + * @param bnd - Bind handle + * + * @return + * - The pointer to variable/array passed to an OCI_BindXXX() or + * OCI_BindArrayOfXXX() call + * + */ + +OCI_EXPORT void * OCI_API OCI_BindGetData +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the statement handle associated with a bind handle + * + * @param bnd - bind handle + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_BindGetStatement +( + OCI_Bind *bnd +); + +/** + * @brief + * Set the actual size of the element held by the given bind handle + * + * @param bnd - bind handle + * @param size - data size + * + * @note + * This call is not mandatory and should ONLY be called for RAWs binds to set + * the real size of the given data if different from the expected column or + * parameter size + * + * @note + * It works as well with string based PL/SQL tables (in or in/out but NOT out) + * even if it's not necessary. + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the parameter 'size' is expressed in + * number of characters. + * + * @return + * Data size if the bind type is listed above otherwise 0. + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetDataSize +( + OCI_Bind *bnd, + unsigned int size +); + +/** + * @brief + * Set the size of the element at the given position in + * the bind input array + * + * @param bnd - bind handle + * @param position - Position in the array + * @param size - data size + * + * @note + * See OCI_BindSetDataSize() for supported data types + * + * @warning + * Before execution, it returns the max default size for the bind and not the real + * data size, unless a custom size has been set with OCI_BindSetDataSizeXXX() + * After execution, it returns the real data size. + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the parameter 'size' is expressed in + * number of characters. + * + * @return + * Data size if the bind type is listed above otherwise 0. + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetDataSizeAtPos +( + OCI_Bind *bnd, + unsigned int position, + unsigned int size +); + +/** + * @brief + * Return the actual size of the element held by the given bind handle + * + * @param bnd - bind handle + * + * @note + * See OCI_BindSetDataSize() for supported data types + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the returned value is expressed in + * number of characters. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetDataSize +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the actual size of the element at the given position in + * the bind input array + * + * @param bnd - bind handle + * @param position - Position in the array + * + * @note + * See OCI_BindSetDataSize() for supported data types + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the returned value is expressed in + * number of characters. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetDataSizeAtPos +( + OCI_Bind *bnd, + unsigned int position +); + +/** + * @brief + * Set the bind variable to null + * + * @param bnd - Bind handle + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetNull +( + OCI_Bind *bnd +); + +/** + * @brief + * Set to null the entry in the bind variable input array + * + * @param bnd - Bind handle + * @param position - Position in the array + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Position starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetNullAtPos +( + OCI_Bind *bnd, + unsigned int position +); + +/** + * @brief + * Set the bind variable to NOT null + * + * @param bnd - Bind handle + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetNotNull +( + OCI_Bind *bnd +); + +/** + * @brief + * Set to NOT null the entry in the bind variable input array + * + * @param bnd - Bind handle + * @param position - Position in the array + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Position starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetNotNullAtPos +( + OCI_Bind *bnd, + unsigned int position +); + +/** + * @brief + * Check if the current value of the binded variable is marked as NULL + * + * @param bnd - Bind handle + * + * @return + * TRUE if it's null otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindIsNull +( + OCI_Bind *bnd +); + +/** + * @brief + * Check if the current entry value at the given index of the binded array + * is marked as NULL + * + * @param bnd - Bind handle + * @param position - Position in the array + * + * @warning + * Position starts with 1 + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindIsNullAtPos +( + OCI_Bind *bnd, + unsigned int position +); + +/** + * @brief + * Set the charset form of the given character based bind variable + * + * @param bnd - Bind handle + * @param csfrm - charset form + * + * @note + * Possible values are : + * + * - OCI_CSF_DEFAULT : the column has default charset + * - OCI_CSF_NATIONAL: the column has national charset + * + * @note + * This call has to be made after OCI_Prepare() but before OCI_Execute() + * + * @warning + * This call does nothing : + * - if the csform is out of range + * - if the bind type is not OCI_CFT_TEXT or OCI_CDT_LONG + * + * @return + * TRUE on success otherwise FALSE + * + */ + +boolean OCI_API OCI_BindSetCharsetForm +( + OCI_Bind *bnd, + unsigned int csfrm +); + +/** + * @brief + * Get the allocaton mode of a bind handle + * + * @param bnd - Bind handle + * + * @note + * Possible values are : + * - OCI_BAM_EXTERNAL : bind variable is allocated by user code + * - OCI_BAM_INTERNAL : bind variable is allocated internally + * + * return the allocaton mode on success otherwise OCI_UNKNWON + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetAllocationMode +( + OCI_Bind *bnd +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiFetching Fetching data + * @{ + * + * OCILIB offers a really easy and smart mechanism to fetch data from a SQL Statement. + * It looks like what's found in JDBC and other object oriented databases frameworks. + * + * ONLY the following statements can return resultsets that can be fetched by host programs: + * - Statements executing SQL SELECT + * - Statements executing SQL UPDATE/DELETE using a RETURNING INTO clause + * - Statements binded to PL/SQL OPEN FOR argument + * - Statements binded to PL/SQL procedure OUT variables + * - Statements implicitly returned from PL/SQL procedure or blocks (new feature in Oracle 12cR1) using + * DBMS_SQL.RETURN_RESULT() + * + * These resultsets are encapsulated in OCILIB by OCI_Resultset objects. + * + * Thus, after any successful call to an OCI_Executexxx() function that executed + * a fetchable statement or filled output bind variables, the resultset can be + * retrieved by calling OCI_GetResultset() + * + * The creation of a OCI_Resultset object consists in : + * + * - Describing the output columns of the resultset + * - Allocating memory to hold the content data + * + * OCILIB supports multi-row fetching for increasing performances. Instead of + * fetching data row by row from the server (that induces lots of round-trips + * between the client and the server), the library prefetches data chunk by + * chunks (default is 20 rows). + * So, less network traffic and better performances. + * These mechanisms are completely hidden from the application which fetches the + * resultset row by row. + * + * Once the Resultset handle is retrieved : + * + * - It can be fetched by calling OCI_FetchNext() as long as it returns TRUE. + * - To retrieve the value of a column, call OCI_GetXXXX() where XXXX is the + * type of data you want to fetch. + * + * @note + * In case of a statement that has executed PL/SQL calls or blocks returning implicit resultsets: + * - OCI_GetResultset() return the first available resultset + * - OCI_GetNextResultset() return the next available resultset until no more resultset available + * + * @par Scrollable Resultsets + * + * Oracle 9i introduced scrollable cursors (resultsets in OCILIB) that can be + * fetched: + * + * - Sequentially in both directions: OCI_FetchPrev() and OCI_FetchNext() + * - To a relative position in the resultset: OCI_FetchSeek() with OCI_SFD_RELATIVE + * - To an absolute position in the resultset: OCI_FetchSeek() with OCI_SFD_ABOSLUTE + * - To the first or last row in the resultset: OCI_FetchFirst() and OCI_FetchLast() + * + * Scrollable statements uses more server and client resources and should only + * be used when necessary. + * + * Resultsets are 'forward only' by default. Call OCI_SetFetchMode() with + * OCI_SFM_SCROLLABLE to enable scrollable resultsets for a given statement. + * + * @warning + * Any use of scrollable fetching functions with a resultset that depends on a + * statement with fetch mode set to OCI_SFM_DEFAULT will fail ! + * + * @warning + * If you intend to use OCI_FetchSeek() on a scrollable statement and if any of the + * selected columns is a ref cursor or a nested table, OCILIB will internally set the + * resultset internal array size to 1 and thus ignore any values set using OCI_SetFetchSize() + * This is performed due to an Oracle bug. + * + * @note + * If the column internal data does not match the requested type, OCILIB tries + * to convert the data when it's possible and throws an error if not. + * + * The properties (columns names, types ...) of the resultset are accessible + * through a set of APIs. + * + * @par Implicit conversion to string types + * + * OCI_GetString() performs an implicit conversion from ANY Oracle types: + * + * - Numerics (based on the current connection handle numeric format) + * - Binary doubles and floats (using the standard C Library functions) + * - OCI_Date : uses OCI_DateToText() with current connection date format + * - OCI_Timestamp : uses OCI_TimestampToText() with current connection date format + * - OCI_Interval : uses OCI_IntervalToText() with Oracle default format + * - OCI_Coll : uses OCI_CollToText() + * - OCI_Object : uses OCI_ObjectToText() + * - OCI_Ref : uses OCI_RefToText() + * - OCI_File : returns "$(folder)/$(filename)" - no content returned + * - OCI_Lob : see note above for binary types + * - OCI_Long : see note above for binary types + * - RAWs : see note above for binary types + * + * @note + * For RAWs and BLOBs attributes, their binary values are converted to hexadecimal strings + * For LONG and CLOBs/NCLOBSs attributes, the whole string content is returned + * + * @note + * The following OCILIB types are not supported for implicit conversion: + * - OCI_Statement + * + * @warning + * For Dates and numerics types, OCILIB uses OCI client calls to perform + * the conversion. + * For binary double and binary floats data types, OCI client functions cannot + * handle the full double range of values. Thus, OCILIB is using the + * standard C library to convert theses data types to string + * + * @par Fetching rows into user structures + * + * It is possible to fetch a complete row into a user defined structure. + * Each column of the resultset is mapped to a structure member. + * The mapping rules are : + * - LOBs (CLOB, NCLOB, BLOB) : OCI_Lob * + * - DATE : OCI_Date * + * - TIMESTAMPS : OCI_Timestamp * + * - INTERVALS : OCI_Interval * + * - LONG, LONG RAW : OCI_Long * + * - REFs : OCI_Ref * + * - CURSOR, RESULSET : OCI_Statement * + * - OBJECTS, UDT : OCI_Object * + * - Character columns (CHAR,VARCHAR, etc..) : otext * + * - All NUMERIC types : + * - default : big_int + * - user defined (see OCI_SetStructNumericType()) + * + * See OCI_GetStruct() and OCI_SetStructNumericType() for more details + * + * @par Fetch Example + * @include fetch.c + * + * @par Fetch Rows into user structures Example + * @include fetch_struct.c + * + * @par Meta data Example + * @include meta.c + * + * @par Ref cursor Example + * @include cursor.c + * + * @par Implicit resultset Example + * @include implicit_resultset.c + * + * @par Scrollable resultset Example + * @include scroll.c + * + */ + +/** + * @brief + * Retrieve the resultset handle from an executed statement + * + * @param stmt - Statement handle + * + * @note + * See @ref OcilibCApiFetching for more details about what statements can return resultsets + * + * @warning + * If the statement has not been prepared and executed, no resultset will be returned + * + * @return + * A resultset handle on success otherwise NULL + * + */ + +OCI_EXPORT OCI_Resultset * OCI_API OCI_GetResultset +( + OCI_Statement *stmt +); + +/** + * @brief + * Free the statement resultsets + * + * @param stmt - Statement handle + * + * @note + * This call is optional. Resultsets are automatically freed when the + * statement is destroyed or when it's reused. + * + * @note + * This function has been introduced for releasing big resultsets when the + * application wants to keep the statement alive and doesn't know when it + * will be destroyed. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ReleaseResultsets +( + OCI_Statement *stmt +); + +/** + * @brief + * Fetch the next row of the resultset + * + * @param rs - Resultset handle + * + * @note + * OCI_FetchNext() works for normal and scrollable resultsets + * + * @return + * TRUE on success otherwise FALSE if : + * - Empty resultset + * - Last row already fetched + * - An error occurred + * + */ + +OCI_EXPORT boolean OCI_API OCI_FetchNext +( + OCI_Resultset *rs +); + +/** + * @brief + * Fetch the previous row of the resultset + * + * @param rs - Resultset handle + * + * @note + * OCI_FetchPrev() works ONLY for scrollable resultsets + * + * @return + * TRUE on success otherwise FALSE if : + * - Empty resultset + * - First row already fetched + * - An error occurred + * + */ + +OCI_EXPORT boolean OCI_API OCI_FetchPrev +( + OCI_Resultset *rs +); + +/** + * @brief + * Fetch the first row of the resultset + * + * @param rs - Resultset handle + * + * @note + * OCI_FetchFirst() works ONLY for scrollable resultsets + * + * @return + * TRUE on success otherwise FALSE if : + * - Empty resultset + * - An error occurred + *f + */ + +OCI_EXPORT boolean OCI_API OCI_FetchFirst +( + OCI_Resultset *rs +); + +/** + * @brief + * Fetch the last row of the resultset + * + * @param rs - Resultset handle + * + * @note + * OCI_FetchLast() works ONLY for scrollable resultsets + * + * @return + * TRUE on success otherwise FALSE if: + * - Empty resultset + * - An error occurred + * + */ + +OCI_EXPORT boolean OCI_API OCI_FetchLast +( + OCI_Resultset *rs +); + +/** + * @brief + * Custom Fetch of the resultset + * + * @param rs - Resultset handle + * @param mode - Fetch direction + * @param offset - Fetch offset + * + * @note + * Possible values for 'direction' parameter are: + * - OCI_SFD_ABSOLUTE + * - OCI_SFD_RELATIVE + * + * @note + * OCI_FetchSeek() works ONLY for scrollable resultsets + * + * @warning + * If you intend to use OCI_FetchSeek() on a scrollable statement and if any of the + * selected columns is a ref cursor or a nested table, you must set the fetching size + * to 1 using OCI_SetFetchSize() before calling OCI_GetResultset() + * Otherwise OCI_FetchSeek() will fails with a OCI-10002 error + * + * @return + * TRUE on success otherwise FALSE if: + * - Empty resultset + * - An error occurred + * - OCI_SetFetchMode() has not been called with OCI_SFM_SCROLLABLE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FetchSeek +( + OCI_Resultset *rs, + unsigned int mode, + int offset +); + +/** + * @brief + * Retrieve the number of rows fetched so far + * + * @param rs - Resultset handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetRowCount +( + OCI_Resultset *rs +); + +/** + * @brief + * Retrieve the current row number + * + * @param rs - Resultset handle + * + * @note + * - OCI_GetCurrentRow() returns the current row number starting from 1 + * - If the resultset has not been fetched or if the resultset is empty, it returns 0 + * - If the resultset has been fully fetched, it returns the last fetched row number + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetCurrentRow +( + OCI_Resultset *rs +); + +/** + * @brief + * Return the number of columns in the resultset + * + * @param rs - Resultset handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetColumnCount +( + OCI_Resultset *rs +); + +/** + * @brief + * Return the column object handle at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @return + * - Column handle on success + * - NULL if index is out of bounds or on error + * + */ + +OCI_EXPORT OCI_Column * OCI_API OCI_GetColumn +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the column object handle from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * - Column handle on success or + * - NULL if no column found with the given name or on error + * + */ + +OCI_EXPORT OCI_Column * OCI_API OCI_GetColumn2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the index of the column in the result from its name + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @note + * Column indexes start with 1 in OCILIB + * + * @return + * Column index on success or zero on error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetColumnIndex +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the name of the given column + * + * @param col - Column handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ColumnGetName +( + OCI_Column *col +); + +/** + * @brief + * Return the type of the given column + * + * @param col - Column handle + * + * @note + * Possible values are : + * + * - OCI_CDT_NUMERIC : short, int, long long, float, double + * - OCI_CDT_DATETIME : OCI_Date * + * - OCI_CDT_TEXT : otext * + * - OCI_CDT_LONG : OCI_Long * + * - OCI_CDT_CURSOR : OCI_Statement * + * - OCI_CDT_LOB : OCI_Lob * + * - OCI_CDT_FILE : OCI_File * + * - OCI_CDT_TIMESTAMP : OCI_Timestamp * + * - OCI_CDT_INTERVAL : OCI_Interval * + * - OCI_CDT_RAW : void * + * - OCI_CDT_OBJECT : OCI_Object * + * - OCI_CDT_COLLECTION : OCI_Coll * + * - OCI_CDT_REF : OCI_Ref * + * - OCI_CDT_BOOLEAN : boolean + * + * @return + * The column type or OCI_CDT_UNKNOWN if index is out of bounds + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetType +( + OCI_Column *col +); + +/** + * @brief + * Return the charset form of the given column + * + * @param col - Column handle + * + * @note + * Possible values are : + * - OCI_CSF_NONE : the column is not an character or lob column + * - OCI_CSF_DEFAULT : the column has server default charset + * - OCI_CSF_NATIONAL : the column has national server charset + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetCharsetForm +( + OCI_Column *col +); + +/** + * @brief + * Return the Oracle SQL type name of the column data type + * + * @param col - Column handle + * + * @note + * For possible values, consults Oracle Documentation + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ColumnGetSQLType +( + OCI_Column *col +); + +/** + * @brief + * Return the Oracle SQL Full name including precision and size of the + * column data type + * + * @param col - Column handle + * @param buffer - buffer to store the full column type name and size + * @param len - max size of the buffer in characters + * + * @note + * This function returns a description that matches the one given by SQL*Plus + * + * @note + * Return the number of characters written into the buffer + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetFullSQLType +( + OCI_Column *col, + otext *buffer, + unsigned int len +); + +/** + * @brief + * Return the size of the column + * + * @note + * For all types, the size is expressed is bytes, excepted for character + * based columns that were created with a character based size or of type NCHAR/NVARCHAR + * + * @param col - Column handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetSize +( + OCI_Column *col +); + +/** + * @brief + * Return the scale of the column for numeric columns + * + * @param col - Column handle + * + */ + +OCI_EXPORT int OCI_API OCI_ColumnGetScale +( + OCI_Column *col +); + +/** + * @brief + * Return the precision of the column for numeric columns + * + * @param col - Column handle + * + */ + +OCI_EXPORT int OCI_API OCI_ColumnGetPrecision +( + OCI_Column *col +); + +/** + * @brief + * Return the fractional precision of the column for timestamp and interval columns + * + * @param col - Column handle + * + */ + +OCI_EXPORT int OCI_API OCI_ColumnGetFractionalPrecision +( + OCI_Column *col +); + +/** + * @brief + * Return the leading precision of the column for interval columns + * + * @param col - Column handle + * + */ + +OCI_EXPORT int OCI_API OCI_ColumnGetLeadingPrecision +( + OCI_Column *col +); + +/** + * @brief + * Return the nullable attribute of the column + * + * @param col - Column handle + * + * @return + * Return TRUE if the column is nullable otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ColumnGetNullable +( + OCI_Column *col +); + +/** + * @brief + * Return TRUE if the length of the column is character-length or FALSE if + * it is byte-length + * + * @param col - Column handle + * + * @note + * This was introduced in Oracle 9i. So for version that are not supporting this + * property, it always return FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ColumnGetCharUsed +( + OCI_Column *col +); + +/** + * @brief + * Return the column property flags + * + * @param col - Column handle + * + * For flags are: + * - OCI_CPF_NONE : The column has no flags or the OCI client does not support this call + * - OCI_CPF_IS_IDENTITY : + * - If Set, the column is an IDENTITY column + * - Otherwise, it is not an IDENTITY column + * - OCI_CPF_IS_GEN_ALWAYS (only if OCI_CPF_IS_IDENTITY is set) : + * - If set, means that the value is "ALWAYS GENERATED" + * - Otherwise mens that the value is "GENERATED BY" + * - OCI_CPF_IS_GEN_BY_DEFAULT_ON_NULL (only if OCI_CPF_IS_IDENTITY is set): + * - If set, means that the value is generated by default on NULL + * + * @note + * This was introduced in Oracle 12cR1. + * It is currently used for identifying Identity columns. + * For earlier versions, it always return OCI_CPF_NONE + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetPropertyFlags +( + OCI_Column *col +); + +/** +* @brief +* Return the column collation ID +* +* @param col - Column handle +* +* Possible values: +* - OCI_CCI_NONE +* - OCI_CCI_NLS_COMP +* - OCI_CCI_NLS_SORT +* - OCI_CCI_NLS_SORT_CI +* - OCI_CCI_NLS_SORT_AI +* - OCI_CCI_NLS_SORT_CS +* - OCI_CCI_NLS_SORT_VAR1 +* - OCI_CCI_NLS_SORT_VAR1_CI +* - OCI_CCI_NLS_SORT_VAR1_AI +* - OCI_CCI_NLS_SORT_VAR1_CS +* - OCI_CCI_BINARY +* - OCI_CCI_BINARY_CI +* - OCI_CCI_BINARY_AI +* +* @note +* This was introduced in Oracle 12cR2. +* For earlier versions, it always return OCI_CCI_NONE +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetCollationID +( + OCI_Column *col +); + +/** + * @brief + * Return the type information object associated to the column + * + * @param col - Column handle + * + * @note + * This call is used only for Named Object typed and collection columns. + * It returns NULL if the column is not a Named Object or a collection. + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_ColumnGetTypeInfo +( + OCI_Column *col +); + +/** + * @brief + * Return the OCILIB object subtype of a column + * + * @param col - Column handle + * + * @note + * This call is valid for the following OCILIB types: + * + * - OCI_CDT_LONG + * - OCI_CDT_LOB + * - OCI_CDT_FILE + * - OCI_CDT_TIMESTAMP + * - OCI_CDT_INTERVAL + * - OCI_CDT_NUMERIC + * + * For OCI_Long type the possible values are: + * - OCI_BLONG + * - OCI_CLONG + * + * For OCI_Lob type the possible values are: + * - OCI_BLOB + * - OCI_CLOB + * - OCI_NCLOB + * + * For OCI_File type the possible values are: + * - OCI_BFILE + * - OCI_CFILE + * + * For OCI_Timestamp type the possible values are: + * - OCI_TIMESTAMP + * - OCI_TIMESTAMP_TZ + * - OCI_TIMESTAMP_LTZ + * + * For OCI_Interval type the possible values are: + * - OCI_INTERVAL_YM + * - OCI_INTERVAL_DS + * + * For numeric columns the possible values are: + * - OCI_NUM_SHORT + * - OCI_NUM_INT + * - OCI_NUM_BIGINT + * - OCI_NUM_USHORT + * - OCI_NUM_UINT + * - OCI_NUM_BIGUINT + * - OCI_NUM_DOUBLE + * - OCI_NUM_FLOAT + * - OCI_NUM_NUMBER + * + * @warning + * For numeric columns, the value may be not accurate at all! + * OCI does not allow to find out the real SQL precise type of an numeric column (int, real, ...). + * OCI based libraries can only 'guess' some types in some situations : float, binary_float, binary_float, number. + * For example: + * - with the statement 'select 101 from dual', OCI would report numeric type NUMBER. + * - if a column is declared as "INT", OCI would report also NUMBER. + * + * + * @note + * For all other OCILIB types, it returns OCI_UNKNOWN + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetSubType +( + OCI_Column *col +); + +/** + * @brief + * set the numeric data type of the given structure member (identified from position in the + * resultset) to retrieve when calling OCI_GetStruct() + * + * @param rs - Resultset handle + * @param index - Column position + * @param type - Numeric type + * + * @note + * Possible values for parameter 'type' : + * - OCI_NUM_SHORT + * - OCI_NUM_USHORT + * - OCI_NUM_INT + * - OCI_NUM_UINT + * - OCI_NUM_BIGINT + * - OCI_NUM_BIGUINT + * - OCI_NUM_DOUBLE + * - OCI_NUM_FLOAT + * - OCI_NUM_NUMBER + * + * @return + * Return TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetStructNumericType +( + OCI_Resultset *rs, + unsigned int index, + unsigned int type +); + +/** + * @brief + * set the numeric data type of the given structure member (identified from column name in the + * resultset) to retrieve when calling OCI_GetStruct() + * + * @param rs - Resultset handle + * @param name - Column name + * @param type - Numeric type + * + * @note + * Possible values for parameter 'type' : + * - OCI_NUM_SHORT + * - OCI_NUM_USHORT + * - OCI_NUM_INT + * - OCI_NUM_UINT + * - OCI_NUM_BIGINT + * - OCI_NUM_BIGUINT + * - OCI_NUM_DOUBLE + * - OCI_NUM_FLOAT + * - OCI_NUM_NUMBER + * + * @return + * Return TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetStructNumericType2 +( + OCI_Resultset *rs, + const otext *name, + unsigned int type +); + +/** + * @brief + * Return the row columns values into a single structure + * + * @param rs - Resultset handle + * @param row_struct - pointer to user row structure + * @param row_struct_ind - pointer to user indicator structure + * + * @note + * Structure members values are contextual to the current row. + * The returned values can get out of scope when the current row + * changes when calling any OCI_FecthXXX() calls + * + * @par User row structure + * + * The user structure must have the same members than the resultset. + * Each column in the resultset must have its equivalent in the structure. + * Fields must be in the same order. + * + * The mapping rules are : + * + * - LOBs (CLOB, NCLOB, BLOB) : OCI_Lob * + * - DATE : OCI_Date * + * - TIMESTAMPS : OCI_Timestamp * + * - INTERVALS : OCI_Interval * + * - LONG, LONG RAW : OCI_Long * + * - REFs : OCI_Ref * + * - CURSOR, RESULSET : OCI_Statement * + * - OBJECTS, UDT : OCI_Object * + * - Character columns (CHAR,VARCHAR, etc..) : otext * + * - All NUMERIC types : + * - default : big_int + * - user defined (see OCI_SetStructNumericType()) + * + * The user structure pointer is not mandatory + * + * @par User row indicator structure + + * This structure must have one boolean field per column in + * the resultset and respect in the same member order. + * + * If the value of the given member is TRUE, it means the value in + * the user row structure is NOT NULL, otherwise its NULL + * + * The user indicator structure pointer is mandatory + * + * @return + * Return TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_GetStruct +( + OCI_Resultset *rs, + void *row_struct, + void *row_struct_ind +); + +/** +* @brief +* Return the current Number value of the column at the given index in the resultset +* +* @param rs - Resultset handle +* @param index - Column position +* +* @note +* Column position starts at 1. +* +* @return +* The column current row value or 0 if index is out of bounds +* +*/ +OCI_EXPORT OCI_Number * OCI_API OCI_GetNumber +( + OCI_Resultset *rs, + unsigned int index +); + +/** +* @brief +* Return the current number value of the column from its name in the resultset +* +* @param rs - Resultset handle +* @param name - Column name +* +* @note +* The column name is case insensitive +* +* @return +* The column current row value or 0 if no column found with the given name +* +*/ + +OCI_EXPORT OCI_Number * OCI_API OCI_GetNumber2 +( + OCI_Resultset *rs, + const otext *name +); + + +/** + * @brief + * Return the current short value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT short OCI_API OCI_GetShort +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current short value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT short OCI_API OCI_GetShort2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current unsigned short value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT unsigned short OCI_API OCI_GetUnsignedShort +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current unsigned short value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT unsigned short OCI_API OCI_GetUnsignedShort2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current integer value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT int OCI_API OCI_GetInt +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current integer value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT int OCI_API OCI_GetInt2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current unsigned integer value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetUnsignedInt +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current unsigned integer value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetUnsignedInt2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current big integer value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT big_int OCI_API OCI_GetBigInt +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current big integer value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT big_int OCI_API OCI_GetBigInt2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current unsigned big integer value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT big_uint OCI_API OCI_GetUnsignedBigInt +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current unsigned big integer value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT big_uint OCI_API OCI_GetUnsignedBigInt2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current string value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @note + * OCI_GetString() performs an implicit conversion from the + * following data types: + * + * - Numerics (based on the current connection handle numeric format) + * - Binary doubles and floats (using the standard C Library functions) + * - OCI_Number (based on the current connection handle numeric format) + * - OCI_Date (based on the current connection handle date format) + * - OCI_Timestamp (based on the current connection handle date format) + * - OCI_Interval (based on Oracle default conversion) + * - OCI_Lob (for BLOBs, output is expressed in hexadecimal) + * - OCI_Long (for BLONGs, output is expressed in hexadecimal) + * - OCI_File ("[directory]/[name]" will be output) + * - OCI_Object (Textual SQL string representation) + * - OCI_Coll (Textual SQL string representation) + * - RAW buffer (expressed in hexadecimal) + * - OCI_Statement (SQL statement string or cursor name) + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetString +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current string value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetString2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Copy the current raw value of the column at the given index into the specified buffer + * + * @param rs - Resultset handle + * @param index - Column position + * @param buffer - Buffer that receive the raw value + * @param len - Max size of the input buffer in bytes + * + * @note + * Column position starts at 1. + * + * @return + * Number of bytes copied into the buffer on SUCCESS otherwise 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetRaw +( + OCI_Resultset *rs, + unsigned int index, + void *buffer, + unsigned int len +); + +/** + * @brief + * Copy the current raw value of the column from its name into the specified buffer + * + * @param rs - Resultset handle + * @param name - Column name + * @param buffer - Buffer that receive the raw value + * @param len - Max size of the input buffer + * + * @note + * The column name is case insensitive + * + * @return + * Number of bytes copied into the buffer on SUCCESS otherwise 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetRaw2 +( + OCI_Resultset *rs, + const otext *name, + void *buffer, + unsigned int len +); + +/** + * @brief + * Return the current double value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0.O if index is out of bounds + * + */ + +OCI_EXPORT double OCI_API OCI_GetDouble +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current double value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0.0 if no column found with the given name + * + */ + +OCI_EXPORT double OCI_API OCI_GetDouble2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current float value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0.O if index is out of bounds + * + */ + +OCI_EXPORT float OCI_API OCI_GetFloat +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current float value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0.0 if no column found with the given name + * + */ + +OCI_EXPORT float OCI_API OCI_GetFloat2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current date value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_GetDate +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current date value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_GetDate2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current timestamp value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_GetTimestamp +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current timestamp value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_GetTimestamp2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current interval value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_GetInterval +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current interval value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_GetInterval2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current cursor value (Nested table) of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_GetStatement +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current cursor value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_GetStatement2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current lob value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_GetLob +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current lob value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_GetLob2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current File value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_GetFile +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current File value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_GetFile2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current Object value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_GetObject +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current Object value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_GetObject2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current Collection value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_GetColl +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current Collection value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_GetColl2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current Ref value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_GetRef +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current Ref value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_GetRef2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current Long value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Long * OCI_API OCI_GetLong +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current Long value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Long * OCI_API OCI_GetLong2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Check if the current row value is null for the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * TRUE if it's null otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IsNull +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the size of the value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the returned value is expressed in + * number of characters. + * + * @return value size of 0 if the value is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetDataSize +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the size of the value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the returned value is expressed in + * number of characters. + * + * @return value size of 0 if the value is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetDataSize2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Check if the current row value is null for the column of the given name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * TRUE if it's null otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IsNull2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the statement handle associated with a resultset handle + * + * @param rs - resultset handle + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_ResultsetGetStatement +( + OCI_Resultset *rs +); + +/** + * @brief + * Return the current row data length of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row data length or 0 if index is out of bounds + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetDataLength +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiPlSql PL/SQL Support + * @{ + * + * OCILIB has a strong PL/SQL support : + * + * - Blocks, procedures and function can be used with OCILIB statements. + * - Ref cursors + * - Nested tables + * - Tables (indexed by integer types) + * - Access to the server side output generated by the DBMS_OUTPUT package + * + * Stored procedures/functions calls, blocks declarations are done like regular + * SQL calls using OCI_Prepare(), OCI_Execute(), OCI_ExecuteStmt() and + * OCI_ExecuteStmtFmt() functions. + * + * All PL/SQL statements must: + * + * - start with a 'begin' or 'declare' keyword + * - end with a 'end;' keyword + * + * Binding Host arrays to PL/SQL tables is done with OCI_BindArrayXXX() calls + * + * @par Using a PL/SQL block with OCILIB + * @include plsql_block.c + * + * @par Binding host arrays to PL/SQL tables parameters of a stored procedure + * @include plsql_table.c + * + * @par Retrieve the output generated by the dbms_output package on the server + * @include output.c + * + */ + +/** + * @brief + * Enable the server output + * + * @param con - Connection handle + * @param bufsize - server buffer max size (server side) + * @param arrsize - number of lines to retrieve per server round-trip + * @param lnsize - maximum size of one line + * + * @note + * This call is equivalent to the command 'set serveroutput on' in SQL*PLUS + * + * @note + * 'bufsize' minimum value is 2000, maximum 1000000 with Oracle < 10.2g and can be unlimited above + * + * @note + * 'lnsize' maximum value is 255 with Oracle < 10g R2 and 32767 above + * + * @warning + * If OCI_ServerEnableOutput() is not called, OCI_ServerGetOutput() will return NULL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ServerEnableOutput +( + OCI_Connection *con, + unsigned int bufsize, + unsigned int arrsize, + unsigned int lnsize +); + +/** + * @brief + * Disable the server output + * + * @param con - Connection handle + * + * @note + * After this call, OCI_ServerGetOutput() will return NULL. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ServerDisableOutput +( + OCI_Connection *con +); + +/** + * @brief + * Retrieve one line of the server buffer + * + * @param con - Connection handle + * + * @note + * Internally, OCILIB gets the server buffer through an array of lines in + * order to minimize round-trips with the server + * + * @return + * return a server output buffer line or NULL if the server buffer is empty + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ServerGetOutput +( + OCI_Connection *con +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiCollections Oracle collections (VARRAYS and Nested Tables) + * @{ + * + * OCILIB supports all Oracle collections: + * + * - PL/SQL Tables: only available in PL/SQL, unbounded, sparse arrays of + homogeneous elements. + * - VARRAYS : available in SQL and PL/SQL, they are bounded arrays of + * homogeneous elements + * - Nested Tables: available in SQL and PL/SQL, they are unbounded arrays of + * homogeneous elements and can become sparse through deletions + * + * PL/SQL tables are implemented by binding regular C arrays with the array + * interface (using OCI_BindArrayOfXXX() calls) + * + * VARRAYS and Nested tables are implemented in OCILIB with the type OCI_Coll. + * It's possible to bind and fetch VARRAYS and Nested tables using OCI_Coll handle. + * + * It's also possible to declare local collections based on some database type without using queries + * + * OCI (and thus OCILIB) offers the possibility to access collection elements : + * + * - directly by index (OCI_CollGetElem() and OCI_CollSetElem()) + * - using an iterator (OCI_Iter) to iterate through the collection + * (OCI_IterGetNext(), OCI_IterGetPrev()) + * + * Collection Items are implemented through the type OCI_Elem and use the series + * of calls OCI_ElemGetXXX() and OCI_ElemSetXXX() to manipulate elements + * content values + * + * @par Example + * @include coll.c + * + */ + +/** + * @brief + * Create a local collection instance + * + * @param typinf - Type info handle of the collection type descriptor + * + * @return + * Return the collection object handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_CollCreate +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a local collection + * + * @param coll - Collection handle + * + * @warning + * Only collection created with OCI_CollCreate() should be freed + * by OCI_CollFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollFree +( + OCI_Coll *coll +); + +/** + * @brief + * Create an array of Collection object + * + * @param con - Connection handle + * @param typinf - Object type (type info handle) + * @param nbelem - number of elements in the array + * + * @note + * see OCI_ObjectCreate() for more details + * + * @return + * Return the Collection handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Coll ** OCI_API OCI_CollArrayCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Free an array of Collection objects + * + * @param colls - Array of Collection objects + * + * @warning + * Only arrays of Collection created with OCI_CollArrayCreate() + * should be freed by OCI_CollArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollArrayFree +( + OCI_Coll **colls +); + +/** + * @brief + * Assign a collection to another one + * + * @param coll - Destination Collection handle + * @param coll_src - Source Collection handle + * + * @note + * Oracle proceeds to a deep copy of the collection content + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollAssign +( + OCI_Coll *coll, + OCI_Coll *coll_src +); + +/** + * @brief + * Return the type info object associated to the collection + * + * @param coll - Collection handle + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_CollGetTypeInfo +( + OCI_Coll *coll +); + +/** + * @brief + * Return the collection type + * + * @param coll - Collection handle + * + * @note + * Current collection types are: + * + * - OCI_COLL_VARRAY: Oracle VARRAY + * - OCI_COLL_NESTED_TABLE: Oracle Nested Table + * + * @return + * Collection type or OCI_UNKNOWN if the collection handle is null + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_CollGetType +( + OCI_Coll *coll +); + +/** + * @brief + * Returns the maximum number of elements of the given collection. + * + * @param coll - Collection handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_CollGetMax +( + OCI_Coll *coll +); + +/** + * @brief + * Returns the total number of elements of the given collection. + * + * @param coll - Collection handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_CollGetSize +( + OCI_Coll *coll +); + +/** + * @brief + * Returns the current number of elements of the given collection. + * + * @note + * - For VARRAYs, it returns the same value than OCI_CollGetSize() as VARRAYs cannot contains holes + * - For Nested Tables that are spare collections that can have holes, it returns the total number + * of elements minus the total of deleted elements + * + * @param coll - Collection handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_CollGetCount +( + OCI_Coll *coll +); + +/** + * @brief + * Trims the given number of elements from the end of the collection + * + * @param coll - Collection handle + * @param nb_elem - Number of elements to trim + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollTrim +( + OCI_Coll *coll, + unsigned int nb_elem +); + +/** + * @brief + * clear all items of the given collection + * + * @param coll - Collection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollClear +( + OCI_Coll *coll +); + +/** + * @brief + * Return the element at the given position in the collection + * + * @param coll - Collection handle + * @param index - Index of the destination element + * + * @note + * Collection indexes start at position 1. + * + * @return + * Element handle on success otherwise FALSE + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_CollGetElem +( + OCI_Coll *coll, + unsigned int index +); + +/** + * @brief + * Return the element at the given position in the collection + * + * @param coll - Collection handle + * @param index - Index of the destination element + * @param elem - Element handle to hold the collection item data + * + * @note + * Collection indexes start at position 1. + * + * @return + * Element handle on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollGetElem2 +( + OCI_Coll *coll, + unsigned int index, + OCI_Elem *elem +); + +/** + * @brief + * Assign the given element value to the element at the given position in + * the collection + * + * @param coll - Collection handle + * @param index - Index of the destination element + * @param elem - Source element handle to assign + * + * @note + * Collection indexes start at position 1. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollSetElem +( + OCI_Coll *coll, + unsigned int index, + OCI_Elem *elem +); + +/** + * @brief + * Append the given element at the end of the collection + * + * @param coll - Collection handle + * @param elem - Element handle to add + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollAppend +( + OCI_Coll *coll, + OCI_Elem *elem +); + +/** + * @brief + * Convert a collection handle value to a string + * + * @param coll - Collection handle + * @param size - Destination string length pointer in characters + * @param str - Destination string + * + * @note + * In order to compute the needed string length, call the method with a NULL string + * Then call the method again with a valid buffer + * + * @note + * The resulting string is similar to the SQL*PLUS output for collections + * For RAWs and BLOBs attributes, their binary values are converted to hexadecimal strings + * + * @warning + * This convenient method shall not be used when performance matters. It is usually called twice (buffer length + * computation) and must also care about quotes within strings. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollToText +( + OCI_Coll *coll, + unsigned int *size, + otext *str +); + +/** + * @brief + * Delete the element at the given position in the Nested Table Collection + * + * @param coll - Collection handle + * @param index - Index of the element to delete + * + * @note + * Collection indexes start at position 1. + * + * @warning + * OCI_CollDeleteElem() is only valid for nested tables. + * + * @return + * - if the input collection is a nested table, it returns TRUE if the element + * is successfully deleted otherwise FALSE on error + * - if the input collection is a VARRAY, it always returns FALSE without spawning an exception + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollDeleteElem +( + OCI_Coll *coll, + unsigned int index +); + +/** + * @brief + * Create an iterator handle to iterate through a collection + * + * @param coll - Collection handle + * + * @return + * Return the iterator handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Iter * OCI_API OCI_IterCreate +( + OCI_Coll *coll +); + +/** + * @brief + * Free an iterator handle + * + * @param iter - Iterator handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IterFree +( + OCI_Iter *iter +); + +/** + * @brief + * Get the next element in the collection + * + * @param iter - Iterator handle + * + * @return + * Element handle on success otherwise NULL if: + * - Empty collection + * - Iterator already positioned on the last collection element + * - An error occurred + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_IterGetNext +( + OCI_Iter *iter +); + +/** + * @brief + * Get the previous element in the collection + * + * @param iter - Iterator handle + * + * @return + * Element handle on success otherwise NULL if: + * - Empty collection + * - Iterator already positioned on the last collection element + * - An error occurred + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_IterGetPrev +( + OCI_Iter *iter +); + +/** + * @brief + * Get the current element in the collection + * + * @param iter - Iterator handle + * + * @return + * Element handle on success otherwise NULL if: + * - Empty collection + * - Iterator already positioned on the last collection element + * - An error occurred + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_IterGetCurrent +( + OCI_Iter *iter +); + +/** + * @brief + * Create a local collection element instance based on a collection type + * descriptor + * + * @param typinf - Type info handle + * + * @return + * Return the collection element handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_ElemCreate +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a local collection element + * + * @param elem - Element handle + * + * @warning + * Only element created with OCI_ElemCreate() should be freed + * by OCI_ElemFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemFree +( + OCI_Elem *elem +); + +/** +* @brief +* Return the boolean value of the given collection element +* +* @param elem - Element handle +* +* @warning +* OCI_ElemGetBoolean() returns a valid value only for collection elements of PL/SQL boolean type +* +* @return +* boolean value or FALSE on failure +* +*/ + +OCI_EXPORT boolean OCI_API OCI_ElemGetBoolean +( + OCI_Elem *elem +); + +/** +* @brief +* Return the number value of the given collection element +* +* @param elem - Element handle +* +* @return +* number handle or NULL on failure +* +*/ + +OCI_EXPORT OCI_Number* OCI_API OCI_ElemGetNumber +( + OCI_Elem *elem +); + +/** + * @brief + * Return the short value of the given collection element + * + * @param elem - Element handle + * + * @return + * Short value or 0 on failure + * + */ + +OCI_EXPORT short OCI_API OCI_ElemGetShort +( + OCI_Elem *elem +); + +/** + * @brief + * Return the unsigned short value of the given collection element + * + * @param elem - Element handle + * + * @return + * Unsigned short value or 0 on failure + * + */ + +OCI_EXPORT unsigned short OCI_API OCI_ElemGetUnsignedShort +( + OCI_Elem *elem +); + +/** + * @brief + * Return the int value of the given collection element + * + * @param elem - Element handle + * + * @return + * Int value or 0 on failure + * + */ + +OCI_EXPORT int OCI_API OCI_ElemGetInt +( + OCI_Elem *elem +); + +/** + * @brief + * Return the unsigned int value of the given collection element + * + * @param elem - Element handle + * + * @return + * Unsigned int value or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ElemGetUnsignedInt +( + OCI_Elem *elem +); + +/** + * @brief + * Return the big int value of the given collection element + * + * @param elem - Element handle + * + * @return + * Big int value or 0 on failure + * + */ + +OCI_EXPORT big_int OCI_API OCI_ElemGetBigInt +( + OCI_Elem *elem +); + +/** + * @brief + * Return the unsigned big int value of the given collection element + * + * @param elem - Element handle + * + * @return + * Unsigned big int value or 0 on failure + * + */ + +OCI_EXPORT big_uint OCI_API OCI_ElemGetUnsignedBigInt +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Double value of the given collection element + * + * @param elem - Element handle + * + * @return + * Double value or 0 on failure + * + */ + +OCI_EXPORT double OCI_API OCI_ElemGetDouble +( + OCI_Elem *elem +); + +/** + * @brief + * Return the float value of the given collection element + * + * @param elem - Element handle + * + * @return + * Double value or 0 on failure + * + */ + +OCI_EXPORT float OCI_API OCI_ElemGetFloat +( + OCI_Elem *elem +); + +/** + * @brief + * Return the String value of the given collection element + * + * @param elem - Element handle + * + * @return + * String value or NULL on failure + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ElemGetString +( + OCI_Elem *elem +); + +/** + * @brief + * Read the RAW value of the collection element into the given buffer + * + * @param elem - Element handle + * @param value - Buffer to store the RAW value + * @param len - Size of the buffer + * + * @return + * Number of bytes read from the RAW value or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ElemGetRaw +( + OCI_Elem *elem, + void *value, + unsigned int len +); + +/** +* @brief +* Return the raw attribute value size of the given element handle +* +* @param elem - Element handle +* +* @return +* size in bytes of the RAW value or 0 on failure or wrong attribute type +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_ElemGetRawSize +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Date value of the given collection element + * + * @param elem - Element handle + * + * @return + * Date handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_ElemGetDate +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Timestamp value of the given collection element + * + * @param elem - Element handle + * + * @return + * Timestamp handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_ElemGetTimestamp +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Interval value of the given collection element + * + * @param elem - Element handle + * + * @return + * Interval handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_ElemGetInterval +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Lob value of the given collection element + * + * @param elem - Element handle + * + * @return + * Lob handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_ElemGetLob +( + OCI_Elem *elem +); + +/** + * @brief + * Return the File value of the given collection element + * + * @param elem - Element handle + * + * @return + * File handle or NULL on failure + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_ElemGetFile +( + OCI_Elem *elem +); + +/** + * @brief + * Return the object value of the given collection element + * + * @param elem - Element handle + * + * @return + * Object handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_ElemGetObject +( + OCI_Elem *elem +); + +/** + * @brief + * Return the collection value of the given collection element + * + * @param elem - Element handle + * + * @return + * Collection handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_ElemGetColl +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Ref value of the given collection element + * + * @param elem - Element handle + * + * @return + * Ref handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_ElemGetRef +( + OCI_Elem *elem +); + +/** +* @brief +* Set a boolean value to a collection element +* +* @param elem - Element handle +* @param value - Short value +* +*@warning +* OCI_ElemSetBoolean() is only valid value only for collection elements of PL / SQL boolean type +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_ElemSetBoolean +( + OCI_Elem *elem, + boolean value +); + +/** +* @brief +* Set a number value to a collection element +* +* @param elem - Element handle +* @param value - number value +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_ElemSetNumber +( + OCI_Elem *elem, + OCI_Number *value +); + +/** + * @brief + * Set a short value to a collection element + * + * @param elem - Element handle + * @param value - Short value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetShort +( + OCI_Elem *elem, + short value +); + +/** + * @brief + * Set a unsigned short value to a collection element + * + * @param elem - Element handle + * @param value - Unsigned short value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetUnsignedShort +( + OCI_Elem *elem, + unsigned short value +); + +/** + * @brief + * Set a int value to a collection element + * + * @param elem - Element handle + * @param value - Int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetInt +( + OCI_Elem *elem, + int value +); + +/** + * @brief + * Set a unsigned int value to a collection element + * + * @param elem - Element handle + * @param value - Unsigned int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetUnsignedInt +( + OCI_Elem *elem, + unsigned int value +); + +/** + * @brief + * Set a big int value to a collection element + * + * @param elem - Element handle + * @param value - big int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetBigInt +( + OCI_Elem *elem, + big_int value +); + +/** + * @brief + * Set a unsigned big_int value to a collection element + * + * @param elem - Element handle + * @param value - Unsigned big int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetUnsignedBigInt +( + OCI_Elem *elem, + big_uint value +); + +/** + * @brief + * Set a double value to a collection element + * + * @param elem - Element handle + * @param value - Double value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetDouble +( + OCI_Elem *elem, + double value +); + +/** + * @brief + * Set a float value to a collection element + * + * @param elem - Element handle + * @param value - float value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetFloat +( + OCI_Elem *elem, + float value +); + +/** + * @brief + * Set a string value to a collection element + * + * @param elem - Element handle + * @param value - String value + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetString +( + OCI_Elem *elem, + const otext *value +); + +/** + * @brief + * Set a RAW value to a collection element + * + * @param elem - Element handle + * @param value - Raw value + * @param len - Size of the raw value + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetRaw +( + OCI_Elem *elem, + void *value, + unsigned int len +); + +/** + * @brief + * Assign a Date handle to a collection element + * + * @param elem - Element handle + * @param value - Date Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetDate +( + OCI_Elem *elem, + OCI_Date *value +); + +/** + * @brief + * Assign a Timestamp handle to a collection element + * + * @param elem - Element handle + * @param value - Timestamp Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetTimestamp +( + OCI_Elem *elem, + OCI_Timestamp *value +); + +/** + * @brief + * Assign an Interval handle to a collection element + * + * @param elem - Element handle + * @param value - Interval Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetInterval +( + OCI_Elem *elem, + OCI_Interval *value +); + +/** + * @brief + * Assign a Collection handle to a collection element + * + * @param elem - Element handle + * @param value - Collection Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetColl +( + OCI_Elem *elem, + OCI_Coll *value +); + +/** + * @brief + * Assign an Object handle to a collection element + * + * @param elem - Element handle + * @param value - Object Handle + * + * @warning + * This function assigns a copy of the object to the given attribute. + * Any further modifications of the object passed as the parameter 'value' + * will not be reflected to object 's attribute set with this call + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetObject +( + OCI_Elem *elem, + OCI_Object *value +); + +/** + * @brief + * Assign a Lob handle to a collection element + * + * @param elem - Element handle + * @param value - Lob Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetLob +( + OCI_Elem *elem, + OCI_Lob *value +); + +/** + * @brief + * Assign a File handle to a collection element + * + * @param elem - Element handle + * @param value - File Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetFile +( + OCI_Elem *elem, + OCI_File *value +); + +/** + * @brief + * Assign a Ref handle to a collection element + * + * @param elem - Element handle + * @param value - Ref Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetRef +( + OCI_Elem *elem, + OCI_Ref *value +); + +/** + * @brief + * Check if the collection element value is null + * + * @param elem - Element handle + * + * @return + * TRUE if it's null otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemIsNull +( + OCI_Elem *elem +); + +/** + * @brief + * Set a collection element value to null + * + * @param elem - Element handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetNull +( + OCI_Elem *elem +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiFeatureReturningInto Oracle Returning feature + * @{ + * + * OCILIB supports the Oracle feature 'Returning into' for DML statements. + * + * Let's Oracle talk about this features: + * + * @par + * 'Using the RETURNING clause with a DML statement allows you to essentially + * combine two SQL statements into one, possibly saving you a server round-trip. + * This is accomplished by adding an extra clause to the traditional UPDATE, + * INSERT, and DELETE statements. The extra clause effectively adds a query to + * the DML statement. In the OCI, the values are returned to the application + * through the use of OUT bind variables.' + * + * OCILIB implements this features by providing a set of functions that allows + * to register output placeholders for the returned values. + * Once the DML is executed with OCI_Execute(), the output returned data is + * available through a regular resultset object that can be fetched. + * + * @note + * Array binding interface is also supported with 'returning into' DML statement. + * Every iteration (or row of given arrays) generates an resultset object. + * Once a resultset is fetched, the next on can be retrieved with OCI_GetNextResultset() + * + * @par + * + * @note + * OCI_Long are not supported for 'returning into' clause .This is a limitation imposed by Oracle. + * + * @note + * OCI_Column objects retrieved from output OCI_Resultset have the following + * particularities: + * + * - their names are the provided bind names to the DML statement + * (by example, ':out1'). So any call to the functions OCI_GetXXX2() + * should be aware of it + * - The columns detailed SQL attributes might be not all set or accurate. By + * example, the scale and precision are not set, the SQL type is the one + * chosen by OCILIB regarding the OCILIB object data type and might be + * slightly different from the real one. + * + * @par Example + * @include returning.c + * + */ + +/** + * @brief + * Retrieve the next available resultset + * + * @param stmt - Statement handle + * + * @note + * it is only valid for the following statements: + * - Statements executing SQL UPDATE/DELETE using a RETURNING INTO clause + * - Statements implicitly returned from PL/SQL procedure or blocks (new feature in Oracle 12cR1) using + * DBMS_SQL.RETURN_RESULT() + * + * @note + * SQL statements with a 'returning' clause can return multiple resultsets. + * When arrays of program variables are binded to the statement, Oracle will + * execute the statement for every row (iteration). + * Each iteration generates a resultset that can be fetched like regular ones. + * + * @note + * Starting withOracle 12cR1, PL/SQ procedure and blocks ca return multiple implicit resultsets + * Refer to Oracle documentation for more information. + * + * @return + * A resultset handle on success otherwise NULL + * + */ + +OCI_EXPORT OCI_Resultset * OCI_API OCI_GetNextResultset +( + OCI_Statement *stmt +); + +/** +* @brief +* Register a register output bind placeholder +* +* @param stmt - Statement handle +* @param name - Output bind name +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_RegisterNumber +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a short output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterShort +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register an unsigned short output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterUnsignedShort +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register an integer output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterInt +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register an unsigned integer output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterUnsignedInt +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a big integer output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterBigInt +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register an unsigned big integer output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterUnsignedBigInt +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a string output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param len - Max length of single string (in characters) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterString +( + OCI_Statement *stmt, + const otext *name, + unsigned int len +); + +/** + * @brief + * Register an raw output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param len - Max length of the buffer (in bytes) + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterRaw +( + OCI_Statement *stmt, + const otext *name, + unsigned int len +); + +/** + * @brief + * Register a double output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterDouble +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a float output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterFloat +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a date output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterDate +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a timestamp output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param type - Timestamp type + * + * @note + * See OCI_TimestampCreate() for possible values of parameter 'type' + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterTimestamp +( + OCI_Statement *stmt, + const otext *name, + unsigned int type +); + +/** + * @brief + * Register an interval output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param type - Interval type + * + * @note + * See OCI_IntervalCreate() for possible values of parameter 'type' + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterInterval +( + OCI_Statement *stmt, + const otext *name, + unsigned int type +); + +/** + * @brief + * Register an object output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param typinf - Type info handle + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterObject +( + OCI_Statement *stmt, + const otext *name, + OCI_TypeInfo *typinf +); + +/** + * @brief + * Register a lob output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param type - Lob type + * + * @note + * See OCI_LobCreate() for possible values of parameter 'type' + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterLob +( + OCI_Statement *stmt, + const otext *name, + unsigned int type +); + +/** + * @brief + * Register a file output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param type - File type + * + * @note + * See OCI_FileCreate() for possible values of parameter 'type' + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterFile +( + OCI_Statement *stmt, + const otext *name, + unsigned int type +); + +/** + * @brief + * Register a Ref output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param typinf - Type info handle + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterRef +( + OCI_Statement *stmt, + const otext *name, + OCI_TypeInfo *typinf +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiRowIds Oracle Rowids + * @{ + * + * OCILIB supports the Oracle ROWID type through C scalar string types (otext). + * + * - ROWIDs can be retrieved from resultset with OCI_GetString() + * - ROWIDs can be binded to statements with OCI_BindString() + * + * The maximum size of an ROWID buffer is defined by the constant OCI_SIZE_ROWID + * + * @par Example + * @include rowid.c + * + * @} + */ + +/** + * @defgroup OcilibCApiStatementControl Statements control + * @{ + * + * Those functions give extra information about OCILIB statements and can modify their behavior. + * + */ + +/** + * @brief + * Return the type of a SQL statement + * + * @param stmt - Statement handle + * + * @note + * Possible values are : + * + * - OCI_CST_SELECT : select statement + * - OCI_CST_UPDATE : update statement + * - OCI_CST_DELETE : delete statement + * - OCI_CST_INSERT : insert statement + * - OCI_CST_CREATE : create statement + * - OCI_CST_DROP : drop statement + * - OCI_CST_ALTER : alter statement + * - OCI_CST_BEGIN : begin (pl/sql) statement + * - OCI_CST_DECLARE : declare (pl/sql) statement + * - OCI_CST_CALL : kpu call + * + * @return + * The statement type on success or OCI_UNKOWN on error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetStatementType +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the fetch mode of a SQL statement + * + * @param stmt - Statement handle + * @param mode - fetch mode value + * + * @warning + * OCI_SetFetchMode() MUST be called before any OCI_ExecuteXXX() call + * + * @note + * Possible values are : + * - OCI_SFM_DEFAULT + * - OCI_SFM_SCROLLABLE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetFetchMode +( + OCI_Statement *stmt, + unsigned int mode +); + +/** + * @brief + * Return the fetch mode of a SQL statement + * + * @param stmt - Statement handle + * + * @note + * See OCI_SetFetchMode() for possible values + * Default value is OCI_SFM_DEFAULT + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetFetchMode +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the binding mode of a SQL statement + * + * @param stmt - Statement handle + * @param mode - binding mode value + * + * @note + * Possible values are : + * - OCI_BIND_BY_POS : position binding + * - OCI_BIND_BY_NAME : name binding + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetBindMode +( + OCI_Statement *stmt, + unsigned int mode +); + +/** + * @brief + * Return the binding mode of a SQL statement + * + * @param stmt - Statement handle + * + * @note + * See OCI_SetBindMode() for possible values + * Default value is OCI_BIND_BY_NAME + * + * @note + * if stmt is NULL, the return value is OCI_UNKNOWN + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetBindMode +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the current bind allocation mode that will be used for subsequent binding calls + * + * @param stmt - Statement handle + * @param mode - bind allocation mode value + * + * @note + * Possible values are : + * - OCI_BAM_EXTERNAL : bind variable are allocated by user code + * - OCI_BAM_INTERNAL : bind variable are allocated internally + * + * @warning + * This call has to be made after preparing a statement as OCI_Prepare() reset it by default to OCI_BAM_EXTERNAL. + * When calling an OCI_BindXXXX() call, this value is used and stored in the OCI_Bind object created during the bind call. + * Each bind can have is own allocation mode that is returned by OCI_BindGetAllocationMode() + * OCI_SetBindAllocation() can be called before each binding call if needed, resulting having some bind allocated externally and other ones internally. + * + * @note + * Refer to the section "Binding variables and arrays" of the documention about allocation mode as OCI_BAM_INTERNAL is not compatible with all bind calls + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetBindAllocation +( + OCI_Statement *stmt, + unsigned int mode +); + +/** + * @brief + * Return the current bind allocation mode used for subsequent binding calls + * + * @param stmt - Statement handle + * + * @note + * See OCI_SetBindAllocation() for possible values + * Default value is OCI_BAM_EXTERNAL + * + * @warning + * Each OCI_Bind object has its own allocation mode that may differ from the one returned by OCI_GetBindAllocation() + * The return value of OCI_GetBindAllocation() is the mode that will be used for any subsequent OCI_BindXXXX() calls + * + * @note + * if stmt is NULL, the return value is OCI_UNKNOWN + * + */ +OCI_EXPORT unsigned int OCI_API OCI_GetBindAllocation +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the number of rows fetched per internal server fetch call + * + * @param stmt - Statement handle + * @param size - number of rows to fetch + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetFetchSize +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the number of rows fetched per internal server fetch call + * + * @param stmt - Statement handle + * + * @note + * Default value is set to constant OCI_FETCH_SIZE + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetFetchSize +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the number of rows pre-fetched by OCI Client + * + * @param stmt - Statement handle + * @param size - number of rows to pre-fetch + * + * @note + * To turn off pre-fetching, set both attributes (size and memory) to 0. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetPrefetchSize +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the number of rows pre-fetched by OCI Client + * + * @param stmt - Statement handle + * + * @note + * Default value is set to constant OCI_PREFETCH_SIZE + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetPrefetchSize +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the amount of memory pre-fetched by OCI Client + * + * @param stmt - Statement handle + * @param size - amount of memory to fetch + * + * @note + * Default value is 0 and the pre-fetch size attribute is used instead. + * When both attributes are set (pre-fetch size and memory) and pre-fetch memory + * value can hold more rows than specified by pre-fetch size, OCI uses pre-fetch + * size instead. + * + * @note + * OCILIB set pre-fetch attribute to OCI_PREFETCH_SIZE when a statement is created. + * To setup a big value for OCI_SetPrefetchMemory(), you must call + * OCI_SetPrefetchSize() to 0 to make OCI consider this attribute. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetPrefetchMemory +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the amount of memory used to retrieve rows pre-fetched by OCI Client + * + * @param stmt - Statement handle + * + * @note + * Default value is 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetPrefetchMemory +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the LONG data type piece buffer size + * + * @param stmt - Statement handle + * @param size - maximum size for long buffer + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetLongMaxSize +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the LONG data type piece buffer size + * + * @param stmt - Statement handle + * + * @note + * Default value is set to constant OCI_SIZE_LONG + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetLongMaxSize +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the long data type handling mode of a SQL statement + * + * @param stmt - Statement handle + * @param mode - long mode value + * + * @note + * Possible values are : + * + * - OCI_LONG_EXPLICIT : LONGs are explicitly handled by OCI_Long type + * - OCI_LONG_IMPLICIT : LONGs are implicitly mapped to string type in the + * limits of VARCHAR2 size capacity + * + * LONG RAWs can't be handled with OCI_LONG_IMPLICIT + */ + +OCI_EXPORT boolean OCI_API OCI_SetLongMode +( + OCI_Statement *stmt, + unsigned int mode +); + +/** + * @brief + * Return the long data type handling mode of a SQL statement + * + * @param stmt - Statement handle + * + * @note + * See OCI_SetLongMode() for possible values + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetLongMode +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the connection handle associated with a statement handle + * + * @param stmt - Statement handle + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_StatementGetConnection +( + OCI_Statement *stmt +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiLobs Internal Large Objects (LOBs) + * @{ + * + * Large Objects (LOBs) were introduced with Oracle 8i to replace LONGs + * + * Oracle OCI supplies a set APIs to manipulate this data type. + * + * OCILIB encapsulates this API by supplying: + * + * - An OCI_Lob C type + * - A set of really easy APIs to manipulate OCI_Lob objects + * + * OCILIB currently supports 3 types of Lobs : + * + * - BLOB : Binary LOBs (replacement for LONG RAW data type) + * - CLOB : Character LOBs (replacement for LONG data type) + * - NCLOB : National Character LOBs + * + * OCI_Lob objects can be : + * + * - Created as standalone instances + * - Used for in/out binding + * - Retrieved from select statements + * - Manipulated (copy, append, ...) + * + * @par Lobs > 4 Go + * + * Oracle 10g extended lobs by increasing maximum size from 4Go to 128 To. + * + * OCILIB, with version 2.1.0, supports now this new limit. + * For handling sizes and offsets up to 128 To, 64 bit integers are requested. + * + * So, A new scalar integer type has been introduced: big_uint (elderly lobsize_t). + * This type can be a 32 bits or 64 bits integer depending on : + * - Compiler support for 64 bits integers (C99 compiler, MS compilers) + * - Oracle client version + * + * big_uint will be a 64 bits integer : + * - if the compiler supports it + * - if OCILIB is build with option OCI_IMPORT_LINKAGE and the Oracle version is >= 10.1 + * - or OCILIB is build with option OCI_IMPORT_RUNTIME (oracle version is not known at + * compilation stage) + * + * @par Example + * @include lob.c + * + */ + +/** + * @brief + * Create a local temporary Lob instance + * + * @param con - Connection handle + * @param type - Lob type + * + * Supported lob types : + * + * - OCI_BLOB : Binary Lob + * - OCI_CLOB : Character Lob + * - OCI_NCLOB ! National Character Lob + * + * @return + * Return the lob handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_LobCreate +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Free a local temporary lob + * + * @param lob - Lob handle + * + * @warning + * Only lobs created with OCI_LobCreate() should be freed by OCI_LobFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobFree +( + OCI_Lob *lob +); + +/** + * @brief + * Create an array of lob object + * + * @param con - Connection handle + * @param type - Lob type + * @param nbelem - number of elements in the array + * + * @note + * see OCI_LobCreate() for more details + * + * @return + * Return the lob handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Lob ** OCI_API OCI_LobArrayCreate +( + OCI_Connection *con, + unsigned int type, + unsigned int nbelem +); + +/** +* @brief +* Free an array of lob objects +* +* @param lobs - Array of lob objects +* +* @warning +* Only arrays of lobs created with OCI_LobArrayCreate() should be freed +* by OCI_LobArrayFree() +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_LobArrayFree +( + OCI_Lob **lobs +); + +/** + * @brief + * Return the type of the given Lob object + * + * @param lob - Lob handle + * + * @note + * For possible values, see OCI_LobCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobGetType +( + OCI_Lob *lob +); + +/** + * @brief + * Perform a seek operation on the OCI_lob content buffer + * + * @param lob - Lob handle + * @param offset - Offset from current position (bytes or characters) + * @param mode - Seek mode + * + * Parameter 'mode' can be one of the following value : + * + * - OCI_SEEK_SET : set the lob current offset to the given absolute offset + * - OCI_SEEK_END : set the lob current offset to the end of the lob + * - OCI_SEEK_CUR : move the lob current offset to the number of bytes or + * characters given by parameter 'offset' + * + * @note + * - For CLOB and CLOB, offset in characters + * - For BLOB and BFILE, offset is in bytes + * + * @note + * Position in the Lob buffer starts at 0. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobSeek +( + OCI_Lob *lob, + big_uint offset, + unsigned int mode +); + +/** + * @brief + * Return the current position in the Lob content buffer + * + * @param lob - Lob handle + * + * @return + * Lob position (starting with 0) or 0 on failure + */ + +OCI_EXPORT big_uint OCI_API OCI_LobGetOffset +( + OCI_Lob *lob +); + +/** + * @brief + * [OBSOLETE] Read a portion of a lob into the given buffer + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer (in bytes or characters) + * + * @note + * Length is expressed in : + * - Bytes for BLOBs + * - Characters for CLOBs/NCLOBS + * + * @warning + * This call is obsolete ! Use OCI_LobRead2() instead. + * + * @return + * Number of bytes/characters read on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobRead +( + OCI_Lob *lob, + void *buffer, + unsigned int len +); + +/** + * @brief + * Read a portion of a lob into the given buffer + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param char_count - [in/out] Pointer to maximum number of characters + * @param byte_count - [in/out] Pointer to maximum number of bytes + * + * @note + * In input, 'char_count' and 'byte_count' are values to read into the buffer + * In output, 'char_count' and 'byte_count' are values read into the buffer + * + * @note + * For BLOBs, only the parameter 'byte_count' is used + * For CLOBs, both parameters can be used : + * In input : + * - if 'byte_count' is set to zero, it is computed from 'char_count' + * - if 'char_count' is set to zero, it is computed from 'byte_count' + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobRead2 +( + OCI_Lob *lob, + void *buffer, + unsigned int *char_count, + unsigned int *byte_count +); + +/** + * @brief + * [OBSOLETE] Write a buffer into a LOB + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer (in bytes or characters) + * + * @note + * Length is expressed in : + * - Bytes for BLOBs + * - Characters for CLOBs/NCLOBs + * + * @warning + * This call is obsolete ! Use OCI_LobWrite2() instead. + * + * @return + * Number of bytes / characters written on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobWrite +( + OCI_Lob *lob, + void *buffer, + unsigned int len +); + +/** + * @brief + * Write a buffer into a LOB + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param char_count - [in/out] Pointer to maximum number of characters + * @param byte_count - [in/out] Pointer to maximum number of bytes + * + * @note + * In input, 'char_count' and 'byte_count' are values to write from the buffer + * In output, 'char_count' and 'byte_count' are values written from the buffer + * + * @note + * For BLOBs, only the parameter 'byte_count' is used + * For CLOBs, both parameters can be used : + * In input : + * - if 'byte_count' is set to zero, it is computed from 'char_count' + * - if 'char_count' is set to zero, it is computed from 'byte_count' + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobWrite2 +( + OCI_Lob *lob, + void *buffer, + unsigned int *char_count, + unsigned int *byte_count +); + +/** + * @brief + * Truncate the given lob to a shorter length + * + * @param lob - Lob handle + * @param size - New length (in bytes or characters) + * + * @note + * Length is expressed in : + * - Bytes for BLOBs + * - Characters for CLOBs/NCLOBs + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobTruncate +( + OCI_Lob *lob, + big_uint size +); + +/** + * @brief + * Return the actual length of a lob + * + * @param lob - Lob handle + * + * @note + * The returned value is in bytes for BLOBS and characters for CLOBS/NCLOBs + * + */ + +OCI_EXPORT big_uint OCI_API OCI_LobGetLength +( + OCI_Lob *lob +); + +/** + * @brief + * Returns the chunk size of a LOB + * + * @param lob - Lob handle + * + * @note + * This chunk size corresponds to the chunk size used by the LOB data layer + * when accessing and modifying the LOB value. According to Oracle + * documentation, performance will be improved if the application issues + * read or write requests using a multiple of this chunk size + * + * @note + * The returned value is in bytes for BLOBS and characters for CLOBS/NCLOBs + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobGetChunkSize +( + OCI_Lob *lob +); + +/** + * @brief + * Erase a portion of the lob at a given position + * + * @param lob - Lob handle + * @param offset - Absolute position in source lob + * @param len - Number of bytes or characters to erase + * + * @note + * Absolute position starts at 0. + * Erasing means that spaces overwrite the existing LOB value. + * + * @return + * Number of bytes (BLOB) or characters (CLOB/NCLOB) erased on success + * otherwise 0 on failure + * + */ + +OCI_EXPORT big_uint OCI_API OCI_LobErase +( + OCI_Lob *lob, + big_uint offset, + big_uint len +); + +/** + * @brief + * Append a buffer at the end of a LOB + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer (in bytes or characters) + * + * @note + * Length is expressed in : + * - Bytes for BLOBs + * - Characters for CLOBs + * + * @return + * Number of bytes / characters written on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobAppend +( + OCI_Lob *lob, + void *buffer, + unsigned int len +); + +/** + * @brief + * Append a buffer at the end of a LOB + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param char_count - [in/out] Pointer to maximum number of characters + * @param byte_count - [in/out] Pointer to maximum number of bytes + * + * @note + * In input, 'char_count' and 'byte_count' are values to write from the buffer + * In output, 'char_count' and 'byte_count' are values written from the buffer + * + * @note + * For BLOBs, only the parameter 'byte_count' is used + * For CLOBs, both parameters can be used : + * In input : + * - if 'byte_count' is set to zero, it is computed from 'char_count' + * - if 'char_count' is set to zero, it is computed from 'byte_count' + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobAppend2 +( + OCI_Lob *lob, + void *buffer, + unsigned int *char_count, + unsigned int *byte_count +); + +/** + * @brief + * Append a source LOB at the end of a destination LOB + * + * @param lob - Destination Lob handle + * @param lob_src - Source Lob handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobAppendLob +( + OCI_Lob *lob, + OCI_Lob *lob_src +); + +/** + * @brief + * Check if the given lob is a temporary lob + * + * @param lob - Lob handle + * + * @return + * TRUE if it's a temporary lob otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobIsTemporary +( + OCI_Lob *lob +); + +/** + * @brief + * Copy a portion of a source LOB into a destination LOB + * + * @param lob - Destination Lob handle + * @param lob_src - Source Lob handle + * @param offset_dst - Absolute position in destination lob + * @param offset_src - Absolute position in source lob + * @param count - Number of bytes or character to copy + * + * @note + * For character LOB (CLOB/NCLOBS) the parameters count, offset_dst and + * offset_src are expressed in characters and not in bytes. + * + * @note + * Absolute position starts at 0. + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobCopy +( + OCI_Lob *lob, + OCI_Lob *lob_src, + big_uint offset_dst, + big_uint offset_src, + big_uint count +); + +/** + * @brief + * Copy a portion of a source FILE into a destination LOB + * + * @param lob - Destination Lob handle + * @param file - Source File handle + * @param offset_dst - Absolute position in destination lob + * @param offset_src - Absolute position in source file + * @param count - Number of bytes to copy + * + * @note + * - For character LOB (CLOB/NCLOB) the parameter offset_src are expressed in + * characters and not in bytes. + * - Offset_src is always in bytes + * + * @note + * Absolute position starts at 0. + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobCopyFromFile +( + OCI_Lob *lob, + OCI_File *file, + big_uint offset_dst, + big_uint offset_src, + big_uint count +); + +/** + * @brief + * Open explicitly a Lob + * + * @param lob - Lob handle + * @param mode - open mode + * + * Possible values for mode are : + * + * - OCI_LOB_READONLY : read only access + * - OCI_LOB_READWRITE : read/write access + * + * @note + * - A call to OCI_LobOpen is not necessary to manipulate a Lob. + * - If a lob hasn't been opened explicitly, triggers are fired and + * indexes updated at every read/write/append operation + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobOpen +( + OCI_Lob *lob, + unsigned int mode +); + +/** + * @brief + * Close explicitly a Lob + * + * @param lob - Lob handle + * + * @note + * - A call to OCI_LobClose is not necessary to manipulate a Lob. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobClose +( + OCI_Lob *lob +); + +/** + * @brief + * Compare two lob handles for equality + * + * @param lob - Lob handle + * @param lob2 - Lob2 handle + * + * @return + * TRUE is the lobs are not null and equal otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobIsEqual +( + OCI_Lob *lob, + OCI_Lob *lob2 +); + +/** + * @brief + * Assign a lob to another one + * + * @param lob - Destination Lob handle + * @param lob_src - Source Lob handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobAssign +( + OCI_Lob *lob, + OCI_Lob *lob_src +); + +/** + * @brief + * Return the maximum size that the lob can contain + * + * @param lob - Lob handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT big_uint OCI_API OCI_LobGetMaxSize +( + OCI_Lob *lob +); + +/** + * @brief + * Flush Lob content to the server + * + * @param lob - Lob handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobFlush +( + OCI_Lob *lob +); + +/** + * @brief + * Enable / disable buffering mode on the given lob handle + * + * @param lob - Lob handle + * @param value - Enable/disable buffering mode + * + * @note + * Oracle "LOB Buffering Subsystem" allows client applications + * to speedup read/write of small buffers on Lobs Objects. + * Check Oracle Documentation for more details on "LOB Buffering Subsystem". + * This reduces the number of network round trips and LOB versions, thereby + * improving LOB performance significantly. + * + * @warning + * According to Oracle documentation the following operations are not permitted + * on Lobs when buffering is on : OCI_LobCopy(), OCI_LobAppend, OCI_LobErase(), + * OCI_LobGetLength(), OCI_LobTruncate() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobEnableBuffering +( + OCI_Lob *lob, + boolean value +); + +/** +* @brief +* Retrieve connection handle from the lob handle +* +* @param lob - lob handle +* +*/ + +OCI_EXPORT OCI_Connection * OCI_API OCI_LobGetConnection +( + OCI_Lob *lob +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiFiles External Large Objects (FILEs) + * @{ + * + * External Large Objects (FILEs) were introduced with Oracle 8i + * + * Oracle OCI supplies a set APIs to manipulate this data type. + * + * OCILIB encapsulates this API by supplying: + * + * - An OCI_File C type + * - A set of really easy APIs to manipulate OCI_File objects + * + * OCILIB currently supports 2 types of Lobs : + * + * - BFILE : Binary files + * - CFILE : Character files + * + * @warning + * FILEs are read-only. + * + * OCI_Lob objects can be : + * + * - Created as standalone instances + * - Used for in/out binding + * - Retrieved from select statements + * - Used for reading server files content + * + * @par Files > 4 Go + * + * - New maximum file size limit (128 To) applies to OCI_Files objects. + * - See Internal Large Objects (LOBs) section for Files > 4 Go information + * + * @par Example + * @include file.c + * + */ + +/** + * @brief + * Create a file object instance + * + * @param con - Connection handle + * @param type - File type + * + * Supported file types : + * + * - OCI_BFILE : Binary file + * - OCI_CFILE : Character file + * + * @return + * Return the lob handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_FileCreate +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Free a local File object + * + * @param file - File handle + * + * @warning + * Only Files created with OCI_FileCreate() should be freed by OCI_FileFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileFree +( + OCI_File *file +); + +/** + * @brief + * Create an array of file object + * + * @param con - Connection handle + * @param type - File type + * @param nbelem - number of elements in the array + * + * @note + * see OCI_FileCreate() for more details + * + * @return + * Return the file handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_File ** OCI_API OCI_FileArrayCreate +( + OCI_Connection *con, + unsigned int type, + unsigned int nbelem +); + +/** +* @brief +* Free an array of file objects +* +* @param files - Array of file objects +* +* @warning +* Only arrays of lobs created with OCI_FileArrayCreate() should be freed by OCI_FileArrayFree() +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_FileArrayFree +( + OCI_File **files +); + +/** + * @brief + * Return the type of the given File object + * + * @param file - File handle + * + * @note + * For possible values, see OCI_FileCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_FileGetType +( + OCI_File *file +); + +/** + * @brief + * Perform a seek operation on the OCI_File content buffer + * + * @param file - File handle + * @param offset - Offset from current position + * @param mode - Seek mode + * + * Mode parameter can be one of the following value : + * + * - OCI_SEEK_SET : set the file current offset to the given absolute offset + * - OCI_SEEK_END : set the file current offset to the end of the lob + * - OCI_SEEK_CUR : move the file current offset to the number of bytes given by + * parameter 'offset' + * + * @note + * Position in the File buffer starts at 0. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileSeek +( + OCI_File *file, + big_uint offset, + unsigned int mode +); + +/** + * @brief + * Return the current position in the file + * + * @param file - File handle + * + * @return + * File position (starting with 0) or 0 on failure + */ + +OCI_EXPORT big_uint OCI_API OCI_FileGetOffset +( + OCI_File *file +); + +/** + * @brief + * Read a portion of a file into the given buffer + * + * @param file - File handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer in bytes + * + * @return + * Number of bytes read on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_FileRead +( + OCI_File *file, + void *buffer, + unsigned int len +); + +/** + * @brief + * Return the size in bytes of a file + * + * @param file - File handle + * + */ + +OCI_EXPORT big_uint OCI_API OCI_FileGetSize +( + OCI_File *file +); + +/** + * @brief + * Check if the given file exists on server + * + * @param file - File handle + * + * @note + * For local FILEs object, OCI_LobFileSetName() must be called before to set the filename to check + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileExists +( + OCI_File *file +); + +/** + * @brief + * Set the directory and file name of FILE handle + * + * @param file - File handle + * @param dir - File directory + * @param name - File name + *in + * @note + * - For local FILEs only + * - Files fetched from resultset can't be assigned a new directory and name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileSetName +( + OCI_File *file, + const otext *dir, + const otext *name +); + +/** + * @brief + * Return the directory of the given file + * + * @param file - File handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_FileGetDirectory +( + OCI_File *file +); + +/** + * @brief + * Return the name of the given file + * + * @param file - File handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_FileGetName +( + OCI_File *file +); + +/** + * @brief + * Open a file for reading + * + * @param file - File handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileOpen +( + OCI_File *file +); + +/** + * @brief + * Check if the specified file is opened within the file handle + * + * @param file - File handle + * + * @return + * TRUE if the file was opened with this handle otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileIsOpen +( + OCI_File *file +); + +/** + * @brief + * Close a file + * + * @param file - File handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileClose +( + OCI_File *file +); + +/** + * @brief + * Compare two file handle for equality + * + * @param file - File handle + * @param file2 - File2 handle + * + * @return + * TRUE is the lobs are not null and equal otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileIsEqual +( + OCI_File *file, + OCI_File *file2 +); + +/** + * @brief + * Assign a file to another one + * + * @param file - Destination File handle + * @param file_src - Source File handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileAssign +( + OCI_File *file, + OCI_File *file_src +); + +/** +* @brief +* Retrieve connection handle from the file handle +* +* @param file - file handle +* +*/ + +OCI_EXPORT OCI_Connection * OCI_API OCI_FileGetConnection +( + OCI_File *file +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiLongs Long objects + * @{ + * + * Long Objects encapsulate Oracle LONGs data types and were used to store large + * buffers in Oracle database. + * + * They're still supported but are depreciated. Oracle now provides a + * newer and better way to deal with data that needs large storage : LOBs + * + * OCILIB supports this data type because it was and still is widely used + * + * OCILIB provides a set of API for manipulating LONGs that is really close to + * the one provided for LOBs. + * + * OCILIB currently supports 3 types of Long Objects: + * + * - OCI_BLONG : LONG RAW columns + * - OCI_CLONG : LONG columns + * + * OCI_Lob objects can be : + * + * - Created as standalone instances + * - Used for in/out binding + * - Retrieved from select statement + * + * @par Example + * @include long.c + * + */ + +/** + * @brief + * Create a local temporary Long instance + * + * @param stmt - Statement handle + * @param type - Long type + * + * Supported lob types : + * + * - OCI_BLONG : Binary Long + * - OCI_CLONG : Character Long + * + * @return + * Return the long handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Long * OCI_API OCI_LongCreate +( + OCI_Statement *stmt, + unsigned int type +); + +/** + * @brief + * Free a local temporary long + * + * @param lg - Long handle + * + * @warning + * Only lobs created with OCI_LongCreate() should be freed by OCI_LongFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LongFree +( + OCI_Long *lg +); + +/** + * @brief + * Return the type of the given Long object + * + * @param lg - Long handle + * + * @note + * For possible values, see OCI_LobCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LongGetType +( + OCI_Long *lg +); + +/** + * @brief + * Read a portion of a long into the given buffer [Obsolete] + * + * @param lg - Long handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer in bytes / characters + * + * @note + * - From version 2.0.0, this function is obsolete because OCILIB fetches now + * all data during OCIFetchNext() call + * - So, this call reads now the internal OCI_Long object allocated buffer + * - The internal buffer can be directly accessed with OCI_LongGetBuffer() + * + * @note + * - For OCI_CLONG, parameter 'len' and returned value are expressed in characters + * - For OCI_BLONG, parameter 'len' and returned value are expressed in bytes + * + * @return + * - Number of bytes/characters read on success + * - 0 if there is nothing more to read + * - 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LongRead +( + OCI_Long *lg, + void *buffer, + unsigned int len +); + +/** + * @brief + * Write a buffer into a Long + * + * @param lg - Long handle + * @param buffer - the pointer to a buffer + * @param len - the length of the buffer in bytes (OCI_BLONG) or + * character (OCI_CLONG) + * + * @return + * Number of bytes (OCI_BLONG) / character (OCI_CLONG) written on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LongWrite +( + OCI_Long *lg, + void *buffer, + unsigned int len +); + +/** + * @brief + * Return the buffer size of a long object in bytes (OCI_BLONG) or character (OCI_CLONG) + * + * @param lg - Long handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LongGetSize +( + OCI_Long *lg +); + +/** + * @brief + * Return the internal buffer of an OCI_Long object read from a fetch sequence + * + * @param lg - Long handle + * + */ + +OCI_EXPORT void * OCI_API OCI_LongGetBuffer +( + OCI_Long *lg +); + +/** +* @} +*/ + +/** +* @defgroup OcilibCApiOracleNumber Oracle NUMBER manipulation (optional) +* @{ +* +* OCILIB encapsulates Oracle SQL all Numeric types using C native data types. +* But it also provides an optional OCI_Number handle for manipulating and accessing Oracle NUMBER type. +* OCI_Number provides management for some special value that cannot be addressed in C such as positive +* and negative infinity. +* +* @par Example +* @include number.c +* +*/ + +/** +* @brief +* Create a local number object +* +* @param con - Connection handle +* +* @note +* Parameter 'con' can be NULL in order to manipulate numbers +* independently from database connections +* +* @return +* Return the number handle on success otherwise NULL on failure +* +*/ + +OCI_EXPORT OCI_Number * OCI_API OCI_NumberCreate +( + OCI_Connection *con +); + +/** +* @brief +* Free a number object +* +* @param number - Number handle +* +* @warning +* Only Numbers created with OCI_NumberCreate() should be freed by OCI_NumberFree() +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberFree +( + OCI_Number *number +); + +/** +* @brief +* Create an array of number object +* +* @param con - Connection handle +* @param nbelem - number of elements in the array +* +* @note +* see OCI_NumberCreate() for more details +* +* @return +* Return the number handle array on success otherwise NULL on failure +* +*/ + +OCI_EXPORT OCI_Number ** OCI_API OCI_NumberArrayCreate +( + OCI_Connection *con, + unsigned int nbelem +); + +/** +* @brief +* Free an array of number objects +* +* @param numbers - Array of number objects +* +* @warning +* Only arrays of numbers created with OCI_NumberArrayCreate() should be freed by OCI_NumberArrayFree() +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberArrayFree +( + OCI_Number **numbers +); + +/** +* @brief +* Assign the value of a number handle to another one +* +* @param number - Destination number handle +* @param number_src - Source number handle +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT int OCI_API OCI_NumberAssign +( + OCI_Number *number, + OCI_Number *number_src +); + +/** +* @brief +* Convert a number value from the given number handle to a string +* +* @param number - source number handle +* @param fmt - Number format +* @param size - Destination string size in characters +* @param str - Destination date string +* +* @note +* Output string can be one the following 'magic strings': +* - '~' for positive infinity +* - '-~' for negative infinity +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberToText +( + OCI_Number *number, + const otext *fmt, + int size, + otext *str +); + +/** +* @brief +* Convert a string to a number and store it in the given number handle +* +* @param number - Destination number handle +* @param str - Source number string +* @param fmt - Number format +* +* @note +* Input string can be one the following 'magic strings': +* - '~' for positive infinity +* - '-~' for negative infinity +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberFromText +( + OCI_Number *number, + const otext *str, + const otext *fmt +); + +/** +* @brief +* Return the number value content +* +* @param number - number handle +* +* @note +* Returned content is a buffer of 22 bytes corresponding to Oracle C native +* representation of NUMBER values +* See oracle Documentation of its layout +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT unsigned char * OCI_API OCI_NumberGetContent +( + OCI_Number *number +); + +/** +* @brief +* Assign the number value content +* +* @param number - number handle +* @param content - raw number content +* +* @note +* See OCI_NumberSetContent() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberSetContent +( + OCI_Number *number, + unsigned char *content +); + +/** +* @brief +* Assign the number value with the value of a native C numeric type +* +* @param number - number handle +* @param type - native C type to assign +* @param value - pointer to value to set +* +* @note +* Argument @param type can be : +* +* - OCI_NUM_SHORT : value is a pointer to a signed short +* - OCI_NUM_USHORT : value is a pointer to an unsigned short +* - OCI_NUM_INT : value is a pointer to a signed int +* - OCI_NUM_UINT : value is a pointer to an unsigned short +* - OCI_NUM_BIGINT : value is a pointer to a signed big_int +* - OCI_NUM_BIGUINT : value is a pointer to an unsigned big_uint +* - OCI_NUM_FLOAT : value is a pointer to an float +* - OCI_NUM_DOUBLE : value is a pointer to a double +* - OCI_NUM_NUMBER : value is a pointer to a OCI_Number +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberSetValue +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Assign the number value to a native C numeric type +* +* @param number - number handle +* @param type - native C type to assign +* @param value - pointer to a native C variable +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberGetValue +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Add the value of a native C numeric type to the given number +* +* @param number - number handle +* @param type - native C type of the variable +* @param value - pointer to a native C variable to add +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberAdd +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Subtract the value of a native C numeric type to the given number +* +* @param number - number handle +* @param type - native C type of the variable +* @param value - pointer to a native C variable to subtract +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberSub +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Multiply the given number with the value of a native C numeric +* +* @param number - number handle +* @param type - native C type of the variable +* @param value - pointer to a native C variable to multiply by +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberMultiply +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Divide the given number with the value of a native C numeric +* +* @param number - number handle +* @param type - native C type of the variable +* @param value - pointer to a native C variable to divide by +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberDivide +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** + * @brief + * Compares two number handles + * + * @param number1 - number1 handle + * @param number2 - number2 handle + * + * @return + * - -1 if number1 is smaller than number2, + * - 0 if they are equal + * - 1 if number1 is greater than number2. + * + */ + +OCI_EXPORT int OCI_API OCI_NumberCompare +( + OCI_Number *number1, + OCI_Number *number2 +); + +/** +* @} +*/ + +/** + * @} + */ + +/** + * @defgroup OcilibCApiDatetimes Date/time manipulation + * @{ + * + * OCILIB encapsulates Oracle SQL Date data type within OCI_Date structure + * + * Basically, the OCI_Date routines are wrappers around the Oracle OCIDate APIs + * + * @par Example + * @include date.c + * + */ + +/** + * @brief + * Create a local date object + * + * @param con - Connection handle + * + * @note + * From version 2.5.0, parameter 'con' can be NULL in order to manipulate dates + * independently from database connections + * + * @return + * Return the date handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_DateCreate +( + OCI_Connection *con +); + +/** + * @brief + * Free a date object + * + * @param date - Date handle + * + * @warning + * Only dates created with OCI_DateCreate() should be freed by OCI_DateFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateFree +( + OCI_Date *date +); + +/** + * @brief + * Create an array of date object + * + * @param con - Connection handle + * @param nbelem - number of elements in the array + * + * @note + * see OCI_DateCreate() for more details + * + * @return + * Return the date handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Date ** OCI_API OCI_DateArrayCreate +( + OCI_Connection *con, + unsigned int nbelem +); + +/** + * @brief + * Free an array of date objects + * + * @param dates - Array of date objects + * + * @warning + * Only arrays of dates created with OCI_DateArrayCreate() should be freed by OCI_DateArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateArrayFree +( + OCI_Date **dates +); + +/** + * @brief + * Add or subtract days to a date handle + * + * @param date - Date handle + * @param nb - Number of days to add/remove + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateAddDays +( + OCI_Date *date, + int nb +); + +/** + * @brief + * Add or subtract months to a date handle + * + * @param date - Date handle + * @param nb - Number of months to add/remove + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateAddMonths +( + OCI_Date *date, + int nb +); + +/** + * @brief + * Assign the value of a date handle to another one + * + * @param date - Destination Date handle + * @param date_src - Source Date handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT int OCI_API OCI_DateAssign +( + OCI_Date *date, + OCI_Date *date_src +); + +/** + * @brief + * Check if the given date is valid + * + * @param date - Date handle + * + * @return + * - Zero if date is valid + * - Any other value means the date is invalid + * + */ + +OCI_EXPORT int OCI_API OCI_DateCheck +( + OCI_Date *date +); + +/** + * @brief + * Compares two date handles + * + * @param date - Date1 handle + * @param date2 - Date2 handle + * + * @return + * - -1 if date1 is smaller than date2, + * - 0 if they are equal + * - 1 if date1 is greater than date2. + * + */ + +OCI_EXPORT int OCI_API OCI_DateCompare +( + OCI_Date *date, + OCI_Date *date2 +); + +/** + * @brief + * Return the number of days betWeen two dates + * + * @param date - Date1 handle + * @param date2 - Date2 handle + * + * @return + * Number of days on success otherwise OCI_ERROR on failure + * + */ + +OCI_EXPORT int OCI_API OCI_DateDaysBetween +( + OCI_Date *date, + OCI_Date *date2 +); + +/** + * @brief + * Convert a string to a date and store it in the given date handle + * + * @param date - Destination Date handle + * @param str - Source date string + * @param fmt - Date format + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateFromText +( + OCI_Date *date, + const otext *str, + const otext *fmt +); + +/** + * @brief + * Convert a Date value from the given date handle to a string + * + * @param date - source Date handle + * @param fmt - Date format + * @param size - Destination string size in characters + * @param str - Destination date string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateToText +( + OCI_Date *date, + const otext *fmt, + int size, + otext *str +); + +/** + * @brief + * Extract the date part from a date handle + * + * @param date - Date handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * @param day - Place holder for day value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateGetDate +( + OCI_Date *date, + int *year, + int *month, + int *day +); + +/** + * @brief + * Extract the time part from a date handle + * + * @param date - Date handle + * @param hour - Place holder for hour value + * @param min - Place holder for minute value + * @param sec - Place holder for second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateGetTime +( + OCI_Date *date, + int *hour, + int *min, + int *sec +); + +/** + * @brief + * Extract the date and time parts from a date handle + * + * @param date - Date handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * @param day - Place holder for day value + * @param hour - Place holder for hour value + * @param min - Place holder for minute value + * @param sec - Place holder for second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateGetDateTime +( + OCI_Date *date, + int *year, + int *month, + int *day, + int *hour, + int *min, + int *sec +); + +/** + * @brief + * Set the date portion if the given date handle + * + * @param date - Date handle + * @param year - Year value + * @param month - Month value + * @param day - Day value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateSetDate +( + OCI_Date *date, + int year, + int month, + int day +); + +/** + * @brief + * Set the time portion if the given date handle + * + * @param date - Date handle + * @param hour - Hour value + * @param min - Minute value + * @param sec - Second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateSetTime +( + OCI_Date *date, + int hour, + int min, + int sec +); + +/** + * @brief + * Set the date and time portions if the given date handle + * + * @param date - Date handle + * @param year - Year value + * @param month - Month value + * @param day - Day value + * @param hour - Hour value + * @param min - Minute value + * @param sec - Second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateSetDateTime +( + OCI_Date *date, + int year, + int month, + int day, + int hour, + int min, + int sec +); + +/** + * @brief + * Place the last day of month (from the given date) into the given date + * + * @param date - Date handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateLastDay +( + OCI_Date *date +); + +/** + * @brief + * Gets the date of next day of the week, after a given date + * + * @param date - Date handle + * @param day - Day of the week + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateNextDay +( + OCI_Date *date, + const otext *day +); + +/** + * @brief + * Return the current system date/time into the date handle + * + * @param date - Date handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateSysDate +( + OCI_Date *date +); + +/** + * @brief + * Convert a date from one zone to another zone + * + * @param date - Date handle + * @param zone1 - Source zone + * @param zone2 - Destination zone + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateZoneToZone +( + OCI_Date *date, + const otext *zone1, + const otext *zone2 +); + +/** + * @brief + * Affect an OCI_Date handle value to ISO C time data types + * + * @param date - Date handle + * @param ptm - Pointer to a structure tm to receive date/time values + * @param pt - Pointer to a time_t to hold the date/time in the time_t format + * + * @note + * Both parameters 'ptm' and 'p' are optional but one of them has to be provided. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateToCTime +( + OCI_Date *date, + struct tm *ptm, + time_t *pt +); + +/** + * @brief + * Affect ISO C time data types values to an OCI_Date handle + * + * @param date - Date handle + * @param ptm - Pointer to a structure tm that hold the date/time value + * @param t - Value (time_t) that hold the date/time in the time_t format + * + * @note + * Both parameters 'ptm' and 'p' are optional but one of them has to be provided. + * If 'ptm' is not null, its value is affected to the OCI_Timestamp handle, + * otherwise the value of 't' is used. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateFromCTime +( + OCI_Date *date, + struct tm *ptm, + time_t t +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiTimestamps Timestamps and intervals manipulation + * @{ + * + * OCILIB encapsulates Oracle : + * + * - SQL timestamp data type within OCI_Timestamp structure + * - SQL interval data type within OCI_Interval structure + * + * Basically, the OCI_Timestamp and OCI_Interval routines are wrappers around + * the Oracle OCIDatetime and OCIInterval APIs + * + * @par Examples + * @include timestamp.c + * + */ + +/** + * @brief + * Create a local Timestamp instance + * + * @param con - Connection handle + * @param type - Timestamp type + * + * @note + * From version 2.5.0, parameter 'con' can be NULL in order to manipulate + * timestamps independently from database connections + * + * @note + * Timestamp type can be : + * + * - OCI_TIMESTAMP : timestamp + * - OCI_TIMESTAMP_TZ : timestamp with time zone + * - OCI_TIMESTAMP_LTZ : timestamp with local time zone + * + * @return + * Return the Timestamp handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_TimestampCreate +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Free an OCI_Timestamp handle + * + * @param tmsp - Timestamp handle + * + * @warning + * Only Timestamp created with OCI_TimestampCreate() should be freed by OCI_IntervalFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampFree +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Create an array of timestamp object + * + * @param con - Connection handle + * @param type - Timestamp type + * @param nbelem - number of elements in the array + * + * @note + * see OCI_TimestampCreate() for more details + * + * @return + * Return the timestamp handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Timestamp ** OCI_API OCI_TimestampArrayCreate +( + OCI_Connection *con, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Free an array of timestamp objects + * + * @param tmsps - Array of timestamp objects + * + * @warning + * Only arrays of timestamp created with OCI_TimestampArrayCreate() + * should be freed by OCI_TimestampArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampArrayFree +( + OCI_Timestamp **tmsps +); + +/** + * @brief + * Return the type of the given Timestamp object + * + * @param tmsp - Timestamp handle + * + * @note + * For possible values, see OCI_TimestampCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TimestampGetType +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Assign the value of a timestamp handle to another one + * + * @param tmsp - Destination Timestamp handle + * @param tmsp_src - Source Timestamp handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampAssign +( + OCI_Timestamp *tmsp, + OCI_Timestamp *tmsp_src +); + +/** + * @brief + * Check if the given timestamp is valid + * + * @param tmsp - Timestamp handle + * + * @return + * - Zero if the timestamp value is valid + * - Any other value means the timestamp value is invalid + * + */ + +OCI_EXPORT int OCI_API OCI_TimestampCheck +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Compares two timestamp handles + * + * @param tmsp - Timestamp1 handle + * @param tmsp2 - Timestamp2 handle + * + * @return + * - -1 if Timestamp1 is smaller than Timestamp2, + * - 0 if they are equal + * - 1 if Timestamp1 is greater than Timestamp2. + * + */ + +OCI_EXPORT int OCI_API OCI_TimestampCompare +( + OCI_Timestamp *tmsp, + OCI_Timestamp *tmsp2 +); + +/** + * @brief + * Set a timestamp handle value + * + * @param tmsp - Timestamp handle + * @param year - Year value + * @param month - Month value + * @param day - Day value + * @param hour - hour value + * @param min - minutes value + * @param sec - seconds value + * @param fsec - fractional part of seconds value + * @param time_zone - name of a time zone to use [optional] + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampConstruct +( + OCI_Timestamp *tmsp, + int year, + int month, + int day, + int hour, + int min, + int sec, + int fsec, + const otext *time_zone +); + +/** + * @brief + * Convert one timestamp value from one type to another. + * + * @param tmsp - Timestamp handle to convert + * @param tmsp_src - Timestamp handle to use for the type conversion + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampConvert +( + OCI_Timestamp *tmsp, + OCI_Timestamp *tmsp_src +); + +/** + * @brief + * Convert a string to a timestamp and store it in the given timestamp handle + * + * @param tmsp - Destination Timestamp handle + * @param str - Source date string + * @param fmt - Date format + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampFromText +( + OCI_Timestamp *tmsp, + const otext *str, + const otext *fmt +); + +/** + * @brief + * Convert a timestamp value from the given timestamp handle to a string + * + * @param tmsp - source Timestamp handle + * @param fmt - Timestamp format + * @param size - Destination string size in characters + * @param str - Destination date string + * @param precision - Precision for fractional part of the seconds + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampToText +( + OCI_Timestamp *tmsp, + const otext *fmt, + int size, + otext *str, + int precision +); + +/** + * @brief + * Extract the date part from a timestamp handle + * + * @param tmsp - Timestamp handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * @param day - Place holder for day value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetDate +( + OCI_Timestamp *tmsp, + int *year, + int *month, + int *day +); + +/** + * @brief + * Extract the time portion from a timestamp handle + * + * @param tmsp - Timestamp handle + * @param hour - Place holder for hour value + * @param min - Place holder for minute value + * @param sec - Place holder for second value + * @param fsec - Place holder for fractional part of second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetTime +( + OCI_Timestamp *tmsp, + int *hour, + int *min, + int *sec, + int *fsec +); + +/** + * @brief + * Extract the date and time parts from a date handle + * + * @param tmsp - Date handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * @param day - Place holder for day value + * @param hour - Place holder for hour value + * @param min - Place holder for minute value + * @param sec - Place holder for second value + * @param fsec - Place holder for fractional part of seconds value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetDateTime +( + OCI_Timestamp *tmsp, + int *year, + int *month, + int *day, + int *hour, + int *min, + int *sec, + int *fsec +); + +/** + * @brief + * Return the time zone name of a timestamp handle + * + * @param tmsp - Timestamp handle + * @param size - Destination string size in characters + * @param str - Destination zone name string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetTimeZoneName +( + OCI_Timestamp *tmsp, + int size, + otext *str +); + +/** + * @brief + * Return the time zone (hour, minute) portion of a timestamp handle + * + * @param tmsp - Timestamp handle + * @param hour - Place holder for hour value + * @param min - Place holder for min value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetTimeZoneOffset +( + OCI_Timestamp *tmsp, + int *hour, + int *min +); + +/** + * @brief + * Add an interval value to a timestamp value of a timestamp handle + * + * @param tmsp - Timestamp handle + * @param itv - Interval handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampIntervalAdd +( + OCI_Timestamp *tmsp, + OCI_Interval *itv +); + +/** + * @brief + * Subtract an interval value from a timestamp value of a timestamp handle + * + * @param tmsp - Timestamp handle + * @param itv - Interval handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampIntervalSub +( + OCI_Timestamp *tmsp, + OCI_Interval *itv +); + +/** + * @brief + * Store the difference of two timestamp handles into an interval handle + * + * @param tmsp - Timestamp handle (subtrahend) + * @param tmsp2 - Timestamp2 handle (minuend) + * @param itv - Interval handle + * + * @note + * The function acts like tmsp - tmsp2 = itv + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampSubtract +( + OCI_Timestamp *tmsp, + OCI_Timestamp *tmsp2, + OCI_Interval *itv +); + +/** + * @brief + * Stores the system current date and time as a timestamp value with time zone + * into the timestamp handle. + * + * @param tmsp - Timestamp handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampSysTimestamp +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Affect an OCI_Timestamp handle value to ISO C time data types + * + * @param tmsp - Timestamp handle + * @param ptm - Pointer to a structure tm to receive date/time values + * @param pt - Pointer to a time_t to hold the date/time in the time_t format + * + * @note + * Both parameters 'ptm' and 'p' are optional but one of them has to be provided. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampToCTime +( + OCI_Timestamp *tmsp, + struct tm *ptm, + time_t *pt +); + +/** + * @brief + * Affect ISO C time data types values to an OCI_Timestamp handle + * + * @param tmsp - Timestamp handle + * @param ptm - Pointer to a structure tm that hold the date/time value + * @param t - Value (time_t) that hold the date/time in the time_t format + * + * @note + * Both parameters 'ptm' and 'p' are optional but one of them has to be provided. + * If 'ptm' is not null, its value is affected to the OCI_Timestamp handle, + * otherwise the value of 't' is used. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampFromCTime +( + OCI_Timestamp *tmsp, + struct tm *ptm, + time_t t +); + +/** + * @brief + * Create a local interval object + * + * @param con - Connection handle + * @param type - Type of Interval + * + * @note + * From version 2.5.0, parameter 'con' can be NULL in order to manipulate + * intervals independently from database connections + * + * @note + * Interval type can be : + * - OCI_INTERVAL_YM : year / month interval + * - OCI_INTERVAL_DS : date/ time interval + * + * @return + * Return the Interval handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_IntervalCreate +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Free an OCI_Interval handle + * + * @param itv - Interval handle + * + * @warning + * Only Intervals created with OCI_IntervalCreate() should be freed by + * OCI_IntervalFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalFree +( + OCI_Interval *itv +); + +/** + * @brief + * Create an array of Interval object + * + * @param con - Connection handle + * @param type - Type of Interval + * @param nbelem - number of elements in the array + * + * @note + * see OCI_IntervalCreate() for more details + * + * @return + * Return the Interval handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Interval ** OCI_API OCI_IntervalArrayCreate +( + OCI_Connection *con, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Free an array of Interval objects + * + * @param itvs - Array of Interval objects + * + * @warning + * Only arrays of Interval created with OCI_IntervalArrayCreate() should be freed by + * OCI_IntervalArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalArrayFree +( + OCI_Interval **itvs +); + +/** + * @brief + * Return the type of the given Interval object + * + * @param itv - Interval handle + * + * @note + * For possible values, see OCI_IntervalCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_IntervalGetType +( + OCI_Interval *itv +); + +/** + * @brief + * Assign the value of a interval handle to another one + * + * @param itv - Destination interval handle + * @param itv_src - Source interval handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalAssign +( + OCI_Interval *itv, + OCI_Interval *itv_src +); + +/** + * @brief + * Check if the given interval is valid + * + * @param itv - Interval handle + * + * @return + * - Zero if the interval value is valid + * - Any other value means the interval value is invalid + * + */ + +OCI_EXPORT int OCI_API OCI_IntervalCheck +( + OCI_Interval *itv +); + +/** + * @brief + * Compares two interval handles + * + * @param itv - Interval1 handle + * @param itv2 - Interval2 handle + * + * @return + * - -1 if interval1 is smaller than interval2, + * - 0 if they are equal + * - 1 if interval1 is greater than interval2. + * + */ + +OCI_EXPORT int OCI_API OCI_IntervalCompare +( + OCI_Interval *itv, + OCI_Interval *itv2 +); + +/** + * @brief + * Convert a string to an interval and store it in the given interval handle + * + * @param itv - Destination interval handle + * @param str - Source date string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalFromText +( + OCI_Interval *itv, + const otext *str +); + +/** + * @brief + * Convert an interval value from the given interval handle to a string + * + * @param itv - source Interval handle + * @param leading_prec - Precision of the leading part + * @param fraction_prec - Precision of the fractional part + * @param size - Destination string size in characters + * @param str - Destination date string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalToText +( + OCI_Interval *itv, + int leading_prec, + int fraction_prec, + int size, + otext *str +); + +/** + * @brief + * Correct an interval handle value with the given time zone + * + * @param itv - Interval handle + * @param str - Time zone name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalFromTimeZone +( + OCI_Interval *itv, + const otext *str +); + +/** + * @brief + * Return the day / time portion of an interval handle + * + * @param itv - Interval handle + * @param day - Place holder for day value + * @param hour - Place holder for hours value + * @param min - Place holder for minutes value + * @param sec - Place holder for seconds value + * @param fsec - Place holder for fractional part of seconds value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalGetDaySecond +( + OCI_Interval *itv, + int *day, + int *hour, + int *min, + int *sec, + int *fsec +); + +/** + * @brief + * Return the year / month portion of an interval handle + * + * @param itv - Interval handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalGetYearMonth +( + OCI_Interval *itv, + int *year, + int *month +); + +/** + * @brief + * Set the day / time portion if the given interval handle + * + * @param itv - Interval handle + * @param day - day value + * @param hour - Hour value + * @param min - Minute value + * @param sec - Second value + * @param fsec - Fractional part of the seconds + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalSetDaySecond +( + OCI_Interval *itv, + int day, + int hour, + int min, + int sec, + int fsec +); + +/** + * @brief + * Set the year / month portion if the given Interval handle + * + * @param itv - Interval handle + * @param year - Year value + * @param month - Month value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalSetYearMonth +( + OCI_Interval *itv, + int year, + int month +); + +/** + * @brief + * Adds an interval handle value to another + * + * @param itv - Interval handle from witch to add + * @param itv2 - Interval handle to add + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalAdd +( + OCI_Interval *itv, + OCI_Interval *itv2 +); + +/** + * @brief + * Subtract an interval handle value from another + * + * @param itv - Interval handle from witch to remove + * @param itv2 - Interval handle to remove + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalSubtract +( + OCI_Interval *itv, + OCI_Interval *itv2 +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiUserTypes Oracle Named Types (Oracle OBJECTs) + * @{ + * + * OCILIB implements Oracle Named types (user types and built-in types) through + * the OCI_Object type. + * + * OTT and C structures are not required to use objects in OCILIB. + * + * In order to manipulate objects attributes, OCILIB proposes a set of functions + * to get/set properties for various supported types. + * + * Objects can be: + * - Created as standalone instances (transient objects) + * - Used for binding (persistent / transient objects) + * - Retrieved from select statements (persistent / embedded objects) + * + * References (Oracle type REF) are identifiers (smart pointers) to objects and + * are implemented in OCILIB with the type OCI_Ref. + * + * OCILIB implements Oracle REFs as strong typed Reference (underlying OCI REFs + * are weaker in terms of typing). + * It means it's mandatory to provide type information to: + * - create a local OCI_Ref handle. + * - register an OCI_Ref handle for a 'returning into' clause. + * + * @note + * See Oracle Database SQL Language Reference for more details about REF data type + * + * @warning + * Prior to v3.5.0, OCILIB relied on some OCI routines to set/get objects + * attributes. these OCI calls had known bugs in Unicode mode that has been fixed in Oracle 11gR2. + * From v3.5.0, OCILIB directly sets objects attributes and thus OCILIB objects + * can now be used in Unicode mode. + * + * @par Example : Inserting a local object into a table + * @include object.c + * + * @par Example : Using Object References + * @include ref.c + * + */ + +/** + * @brief + * Create a local object instance + * + * @param con - Connection handle + * @param typinf - Object type (type info handle) + * + * @return + * Return the object handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_ObjectCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a local object + * + * @param obj - Object handle + * + * @warning + * Only object created with OCI_ObjectCreate() should be freed + * by OCI_ObjectFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectFree +( + OCI_Object *obj +); + +/** + * @brief + * Create an array of Object objects + * + * @param con - Connection handle + * @param typinf - Object type (type info handle) + * @param nbelem - number of elements in the array + * + * @note + * see OCI_ObjectCreate() for more details + * + * @return + * Return the Object handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Object ** OCI_API OCI_ObjectArrayCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Free an array of Object objects + * + * @param objs - Array of Object objects + * + * @warning + * Only arrays of Object created with OCI_ObjectArrayCreate() + * should be freed by OCI_ObjectArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectArrayFree +( + OCI_Object **objs +); + +/** + * @brief + * Assign an object to another one + * + * @param obj - Destination Object handle + * @param obj_src - Source Object handle + * + * @note + * Oracle proceeds to a deep copy of the object content + * + * @note + * The two object handles must have the same type otherwise an exception is thrown + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectAssign +( + OCI_Object *obj, + OCI_Object *obj_src +); + +/** + * @brief + * Return the type of an object instance + * + * @param obj - Object handle + * + * @note + * Possibles values are : + * + * - OCI_OBJ_PERSISTENT: persistent object from the DB + * - OCI_OBJ_TRANSIENT : local temporary object + * - OCI_OBJ_VALUE : embedded object + * + * @return + * Instance type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ObjectGetType +( + OCI_Object *obj +); + +/** + * @brief + * Retrieve an Oracle Ref handle from an object and assign it to the given + * OCILIB OCI_Ref handle + * + * @param obj - Object handle + * @param ref - Ref handle + * + * @note + * The type information of the object and the ref must be the same, otherwise + * an exception is thrown + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectGetSelfRef +( + OCI_Object *obj, + OCI_Ref *ref +); + +/** + * @brief + * Return the type info object associated to the object + * + * @param obj - Object handle + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_ObjectGetTypeInfo +( + OCI_Object *obj +); + +/** + * @brief + * Return the boolean value of the given object attribute (ONLY for PL/SQL records) + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetBoolean() returns a valid value only for PL/SQL boolean based attributes + * + * @warning + * - ONLY supported by Oracle 12c and above ! + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectGetBoolean +( + OCI_Object *obj, + const otext *attr +); + +/** +* @brief +* Return the number value of the given object attribute +* +* @param obj - Object handle +* @param attr - Attribute name +* +* @note +* If the attribute is found in the object descriptor attributes list, then a +* data type check is performed for integrity. +* OCI_ObjectGetNumber() returns a valid value only for number based attributes +* +* @return +* Attribute value or NULL on failure or wrong attribute type +* +*/ + +OCI_EXPORT OCI_Number* OCI_API OCI_ObjectGetNumber +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the short value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetShort() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT short OCI_API OCI_ObjectGetShort +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the unsigned short value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetUnsignedShort() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT unsigned short OCI_API OCI_ObjectGetUnsignedShort +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the integer value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetInt() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT int OCI_API OCI_ObjectGetInt +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the unsigned integer value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetUnsignedInt() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ObjectGetUnsignedInt +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the big integer value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetBigInt() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT big_int OCI_API OCI_ObjectGetBigInt +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the unsigned big integer value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetUnsignedBigInt() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT big_uint OCI_API OCI_ObjectGetUnsignedBigInt +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the double value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetDouble() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0.0 on failure or wrong attribute type + * + */ + +OCI_EXPORT double OCI_API OCI_ObjectGetDouble +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the float value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetFloat() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0.0 on failure or wrong attribute type + * + */ + +OCI_EXPORT float OCI_API OCI_ObjectGetFloat +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the string value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * The method can return a string value for any attributes types. + * It performs implicit string conversions using the same + * mechanisms than OCI_GetString(). See its documentation for more details. + * + * @return + * Attribute value or NULL on failure + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ObjectGetString +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the raw attribute value of the given object attribute into the + * given buffer + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Destination buffer + * @param len - Max size to write into buffer + + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetRaw() copies data into the buffer only for raw based attributes + * + * @return + * Number of bytes written to the buffer or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT int OCI_API OCI_ObjectGetRaw +( + OCI_Object *obj, + const otext *attr, + void *value, + unsigned int len +); + +/** +* @brief +* Return the raw attribute value size of the given object attribute into the +* given buffer +* +* @param obj - Object handle +* @param attr - Attribute name +* +* @note +* If the attribute is found in the object descriptor attributes list, then a +* data type check is performed for integrity. +* +* @return +* size in bytes of the RAW value or 0 on failure or wrong attribute type +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_ObjectGetRawSize +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the date value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetDate() returns a valid value only for date based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_ObjectGetDate +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the timestamp value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetTimestamp() returns a valid value only for timestamps based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_ObjectGetTimestamp +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the interval value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetInterval() returns a valid value only for intervals based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_ObjectGetInterval +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the collection value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetColl() returns a valid value only for intervals based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_ObjectGetColl +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the Ref value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetRef() returns a valid value only for Refs based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_ObjectGetRef +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the object value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetObject() returns a valid value only for object based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_ObjectGetObject +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the lob value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetLob() returns a valid value only for lobs based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_ObjectGetLob +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the file value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetFile() returns a valid value only for files based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_ObjectGetFile +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Set an object attribute of type boolean (ONLY for PL/SQL records) + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - boolean value + * + * @warning + * - ONLY supported by Oracle 12c and above ! + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetBoolean +( + OCI_Object *obj, + const otext *attr, + boolean value +); + +/** +* @brief +* Set an object attribute of type number +* +* @param obj - Object handle +* @param attr - Attribute name +* @param value - number value +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetNumber +( + OCI_Object *obj, + const otext *attr, + OCI_Number *value +); + +/** + * @brief + * Set an object attribute of type short + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Short value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetShort +( + OCI_Object *obj, + const otext *attr, + short value +); + +/** + * @brief + * Set an object attribute of type unsigned short + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Unsigned short value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedShort +( + OCI_Object *obj, + const otext *attr, + unsigned short value +); + +/** + * @brief + * Set an object attribute of type int + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetInt +( + OCI_Object *obj, + const otext *attr, + int value +); + +/** + * @brief + * Set an object attribute of type unsigned int + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Unsigned int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedInt +( + OCI_Object *obj, + const otext *attr, + unsigned int value +); + +/** + * @brief + * Set an object attribute of type big int + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Big int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetBigInt +( + OCI_Object *obj, + const otext *attr, + big_int value +); + +/** + * @brief + * Set an object attribute of type unsigned big int + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Unsigned big int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedBigInt +( + OCI_Object *obj, + const otext *attr, + big_uint value +); + +/** + * @brief + * Set an object attribute of type double + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Double value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetDouble +( + OCI_Object *obj, + const otext *attr, + double value +); + +/** + * @brief + * Set an object attribute of type float + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Float value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetFloat +( + OCI_Object *obj, + const otext *attr, + float value +); + +/** + * @brief + * Set an object attribute of type string + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - String value + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetString +( + OCI_Object *obj, + const otext *attr, + const otext *value +); + +/** + * @brief + * Set an object attribute of type RAW + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Raw value + * @param len - Size of the raw value + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetRaw +( + OCI_Object *obj, + const otext *attr, + void *value, + unsigned int len +); + +/** + * @brief + * Set an object attribute of type Date + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Date Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetDate +( + OCI_Object *obj, + const otext *attr, + OCI_Date *value +); + +/** + * @brief + * Set an object attribute of type Timestamp + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Timestamp Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetTimestamp +( + OCI_Object *obj, + const otext *attr, + OCI_Timestamp *value +); + +/** + * @brief + * Set an object attribute of type Interval + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Interval Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetInterval +( + OCI_Object *obj, + const otext *attr, + OCI_Interval *value +); + +/** + * @brief + * Set an object attribute of type Collection + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Collection Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetColl +( + OCI_Object *obj, + const otext *attr, + OCI_Coll *value +); + +/** + * @brief + * Set an object attribute of type Object + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Object Handle + * + * @warning + * This function assigns a copy of the object to the given attribute. + * Any further modifications of the object passed as the parameter 'value' + * will not be reflected to object 's attribute set with this call + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetObject +( + OCI_Object *obj, + const otext *attr, + OCI_Object *value +); + +/** + * @brief + * Set an object attribute of type Lob + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Lob Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetLob +( + OCI_Object *obj, + const otext *attr, + OCI_Lob *value +); + +/** + * @brief + * Set an object attribute of type File + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - File Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetFile +( + OCI_Object *obj, + const otext *attr, + OCI_File *value +); + +/** + * @brief + * Set an object attribute of type Ref + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Ref Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetRef +( + OCI_Object *obj, + const otext *attr, + OCI_Ref *value +); + +/** + * @brief + * Check if an object attribute is null + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @return + * FALSE if the attribute is not null otherwise TRUE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectIsNull +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Set an object attribute to null + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetNull +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Retrieve the underlying C (OTT/OCI style) structure of an OCI_Object handle + * + * @param obj - Object handle + * @param pp_struct - Address of a pointer that retrieve the C structure of data + * @param pp_ind - Address of a pointer that retrieve the C structure of indicators + * + * @note + * See Oracle OCI programming guide for more details about OTT structures. + * The members of these structures are OCI data types like OCINumber, OCIString + * that requires mixing OCILIB code and raw OCI code. + * OCI Object API headers have to be included to handle this data types using OCI object functions + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectGetStruct +( + OCI_Object *obj, + void **pp_struct, + void **pp_ind +); + +/** + * @brief + * Convert an object handle value to a string + * + * @param obj - Object handle + * @param size - Destination string length pointer in characters + * @param str - Destination string + * + * @note + * In order to compute the needed string length, call the method with a NULL string + * Then call the method again with a valid buffer + * + * @note + * The resulting string is similar to the SQL*PLUS output for UDTs (user types and objects) + * For RAWs and BLOBs attributes, their binary values are converted to hexadecimal strings + * + * @warning + * This convenient method shall not be used when performance matters. It is usually called twice (buffer length + * computation) and must also care about quotes within strings. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectToText +( + OCI_Object *obj, + unsigned int *size, + otext *str +); + +/** + * @brief + * Create a local Ref instance + * + * @param con - Connection handle + * @param typinf - Ref type + * + * @return + * Return the Ref handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_RefCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a local Ref + * + * @param ref - Ref handle + * + * @warning + * Only Refs created with OCI_RefCreate() should be freed + * by OCI_RefFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefFree +( + OCI_Ref *ref +); + +/** + * @brief + * Create an array of Ref object + * + * @param con - Connection handle + * @param typinf - Object type (type info handle) + * @param nbelem - number of elements in the array + * + * @note + * see OCI_RefCreate() for more details + * + * @return + * Return the Ref handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Ref ** OCI_API OCI_RefArrayCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Free an array of Ref objects + * + * @param refs - Array of Ref objects + * + * @warning + * Only arrays of Ref created with OCI_RefArrayCreate() + * should be freed by OCI_RefArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefArrayFree +( + OCI_Ref **refs +); + +/** + * @brief + * Assign a Ref to another one + * + * @param ref - Destination Ref handle + * @param ref_src - Source Ref handle + * + * @note + * The two Ref handles must have the same type otherwise an exception is thrown + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefAssign +( + OCI_Ref *ref, + OCI_Ref *ref_src +); + +/** + * @brief + * Return the type info object associated to the Ref + * + * @param ref - Ref handle + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_RefGetTypeInfo +( + OCI_Ref *ref +); + +/** + * @brief + * Returns the object pointed by the Ref handle. + * + * @param ref - Ref handle + * + * @return + * The object handle is the ref is not null otherwise NULL + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_RefGetObject +( + OCI_Ref *ref +); + +/** + * @brief + * Check if the Ref points to an object or not. + * + * @param ref - Ref handle + * + * @return + * TRUE if it does not point to a valid object otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefIsNull +( + OCI_Ref *ref +); + +/** + * @brief + * Nullify the given Ref handle + * + * @param ref - Ref handle + * + * @note + * this call clears the reference to object pointed by the Ref handle. + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RefSetNull +( + OCI_Ref *ref +); + +/** + * @brief + * Returns the size of the hex representation of the given Ref handle + * + * @param ref - Ref handle + * + * @note + * the returned size is the number of character needed to store the + * hex representation of the Ref that can be retrieved with OCI_RefToText() + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_RefGetHexSize +( + OCI_Ref *ref +); + +/** + * @brief + * Converts a Ref handle value to a hexadecimal string. + * + * @param ref - Ref handle + * @param size - Destination string size in characters + * @param str - Destination string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefToText +( + OCI_Ref *ref, + unsigned int size, + otext *str +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiAbort Aborting long operations + * @{ + * + * The Oracle OCI provides the ability to establish a server connection in : + * + * - blocking mode: each call to an OCI function returns control to the + * application when the call completes + * - non-blocking mode (based on polling paradigm) : the application have to + * call each function until its has completed its job + * + * OCILIB implements OCI in blocking mode. The application has to wait for OCI + * calls to complete to continue. + * + * Some operations can be long to be processed by the server. + * + * In order to cancel the current pending call, OCILIB provides OCI_Break() that + * cancel the last internal OCI Call and then raise an OCI abortion error code. + * + * @note + * Any call to OCI_Break() has to be done from a separate thread because the + * thread that has executed a long OCI call is waiting for its OCI call to complete. + * + * @par Example + * @include abort.c + * + */ + +/** + * @brief + * Perform an immediate abort of any currently Oracle OCI call + * + * @param con - connection handle + * + * @note + * The current call will abort and generate an error + * + * @return + * Returns FALSE if connection handle is NULL otherwise TRUE + */ + +OCI_EXPORT boolean OCI_API OCI_Break +( + OCI_Connection *con +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiMetadata Describing Schema Meta data and Objects + * @{ + * + * + * @par Example + * @include desc.c + * + */ + +/** + * @brief + * Retrieve the available type info information + * + * @param con - Connection handle + * @param name - Table/view name to query for + * @param type - Type of object + * + * @note + * Possible values for parameter type are : + * + * - OCI_UNKNOWN + * - OCI_TIF_TABLE + * - OCI_TIF_VIEW + * - OCI_TIF_TYPE + * + * @return + * - Type info handle on success + = - NULL if the object does not exist + * - NULL on failure + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_TypeInfoGet +( + OCI_Connection *con, + const otext *name, + unsigned int type +); + +/** + * @brief + * Return the type of the type info object + * + * @param typinf - Type info handle + * + * @note + * Possible values for parameter type are : + * + * - OCI_UNKNOWM + * - OCI_TIF_TABLE + * - OCI_TIF_VIEW + * - OCI_TIF_TYPE + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TypeInfoGetType +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Retrieve connection handle from the type info handle + * + * @param typinf - Type info handle + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_TypeInfoGetConnection +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a type info object + * + * @param typinf - Type info handle + * + * @note + * this call is optional. + * OCI_TypeInfo object are internally tracked and + * automatically freed when their related connection is freed + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TypeInfoFree +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Return the number of columns of a table/view/object + * + * @param typinf - Type info handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TypeInfoGetColumnCount +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Return the column object handle at the given index in the table + * + * @param typinf - Type info handle + * @param index - Column position + * + * @return + * - Column handle on success + * - NULL if index is out of bounds or on error + * + */ + +OCI_EXPORT OCI_Column * OCI_API OCI_TypeInfoGetColumn +( + OCI_TypeInfo *typinf, + unsigned int index +); + +/** + * @brief + * Return the name described by the type info object + * + * @param typinf - Type info handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_TypeInfoGetName +( + OCI_TypeInfo *typinf +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiFormatting Formatted functions + * @{ + * + * OCILIB offers some smart routines that takes a variable number of arguments + * in order to minimize OCILIB function calls and reduce the amount of code lines + * + * On Windows platforms, the target programming language must support the __cdecl + * calling convention + * + * @note + * OCI_Immediate() and OCI_ImmediateFmt() support all OCILIB supported types + * for output result, except : + * - OCI_Long + * - OCI_Statement + * If a query output result contains one of these unsupported types, the function returns FALSE + * + * @note + * In the parameter list, every output placeholder MUST be preceded by + * an integer parameter that indicates the type of the placeholder + * in order to handle correctly the given pointer. + * + * Possible values for indicating placeholders type : + * + * - OCI_ARG_SHORT ------> short * + * - OCI_ARG_USHORT -----> unsigned short * + * - OCI_ARG_INT --------> int * + * - OCI_ARG_UINT -------> unsigned int* + * - OCI_ARG_BIGINT -----> big_int * + * - OCI_ARG_BIGUINT ----> unsigned big_int * + * - OCI_ARG_DOUBLE ----> double * + * - OCI_ARG_FLOAT ------> float * + * - OCI_ARG_NUMBER -----> OCI_Number * + * - OCI_ARG_TEXT -------> otext * + * - OCI_ARG_RAW --------> void * + * - OCI_ARG_DATETIME ---> OCI_Date * + * - OCI_ARG_LOB --------> OCI_Lob * + * - OCI_ARG_FILE -------> OCI_File * + * - OCI_ARG_TIMESTAMP --> OCI_Timestamp * + * - OCI_ARG_INTERVAL ---> OCI_Interval * + * - OCI_ARG_OBJECT -----> OCI_Object * + * - OCI_ARG_COLLECTION -> OCI_Coll * + * - OCI_ARG_REF --------> OCI_Ref * + * + * @note + * For output strings and Raws, returned data is copied to the given buffer + * instead of returning a pointer the real data. + * So these buffers must be big enough to hold the column content. No size check is performed. + * + * - For strings, only the real string is copied. + * - For Raws, the number of bytes copied is the column size + * + * @warning + * Input parameters for formatted function only support a restricted set of data types ! + * + * Supported input identifiers : + * + * - '%s' : (otext *) ----------> input string (quotes are added) + * - '%m' : (otext *) ----------> meta data string (no quotes added) + * - '%t' : (OCI_Date *) -------> Date + * - '%p' : (OCI_Timestamp *) --> timestamp + * - '%v' : (OCI_Interval *) ---> Interval + * - '%i' : (int) --------------> signed 32 bits integer + * - '%u' : (unsigned int) -----> unsigned 32 bits integer + * - '%li' : (big_int) ----------> signed 64 bits integer + * - '%lu' : (big_uint) ---------> unsigned 64 bits integer + * - '%hi' : (short) ------------> signed 16 bits integer + * - '%hu' : (unsigned short) ---> unsigned 16 bits integer + * - '%g' : (double, float ) ---> Numerics + * - '%n' : (OCI_Number *) -----> Number + * - '%r' : (OCI_Ref *) --------> Reference + * - '%o' : (OCI_Object *) -----> Object (not implemented yet) + * - '%c' : (OCI_Coll *) -------> collection (not implemented yet) + * + * @par Example + * @include format.c + * + */ + +/** + * @brief + * Perform 3 calls (prepare+execute+fetch) in 1 call + * + * @param con - Connection handle + * @param sql - SQL statement + * @param ... - List of program variables address to store the result of fetch operation + * + * @note + * Every output parameter MUST be preceded by an integer parameter that indicates the type + * of the placeholder in order to handle correctly the given pointer. + * + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_Immediate +( + OCI_Connection *con, + const otext *sql, + ... +); + +/** + * @brief + * Performs 4 call (prepare+bind+execute+fetch) in 1 call + * + * @param con - Connection handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL followed by the + * output variables addresses for the fetch operation + * + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_ImmediateFmt +( + OCI_Connection *con, + const otext *sql, + ... +); + +/** + * @brief + * Prepare a formatted SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_PrepareFmt +( + OCI_Statement *stmt, + const otext *sql, + ... +); + +/** + * @brief + * Execute a formatted SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL + * + * @return + * TRUE on success otherwise FALSE + * + * @warning + * If a SQL warning occurs: + * - the function returns TRUE + * - the SQL warning triggers the global error handler with an OCI_Error having its OCI_ErrorGetType() + * attribute set to OCI_ERR_WARNING + * - If OCILIB is initialized with the OCI_ENV_CONTEXT mode, OCI_GetLastError() will return the OCI_Error + * object corresponding to the warning + * + */ + +OCI_EXPORT boolean OCI_ExecuteStmtFmt +( + OCI_Statement *stmt, + const otext *sql, + ... +); + +/** + * @brief + * Parse a formatted SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL + * + * @note + * This call sends the SQL or PL/SQL command to the server for parsing only. + * The command is not executed. + * This call is only useful to check is a command is valid or not. + * + * @note + * This call prepares the statement (internal call to OCI_Prepare()) and ask + * the Oracle server to parse its SQL or PL/SQL command. + * OCI_Execute() can be call after OCI_ParseFmt() in order to execute the + * statement, which means that the server will re-parse again the command. + * + * @warning + * Do not use OCI_ParseFmt() unless you're only interested in the parsing result + * because the statement will be parsed again when executed and thus leading to + * unnecessary server round-trips and less performance + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_ParseFmt +( + OCI_Statement *stmt, + const otext *sql, + ... +); + +/** + * @brief + * Describe the select list of a formatted SQL select statement. + * + * @param stmt - Statement handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL + * + * @note + * This call sends the SELECT SQL order to the server for retrieving the + * description of the select order only. + * The command is not executed. + * This call is only useful to retrieve information on the associated resultset + * Call OCI_GetResultet() after OCI_Describe() to access to SELECT list + * information + * + * @note + * This call prepares the statement (internal call to OCI_Prepare()) and ask + * the Oracle server to describe the output SELECT list. + * OCI_Execute() can be call after OCI_Desbribe() in order to execute the + * statement, which means that the server will parse, and describe again the SQL + * order. + * + * @warning + * Do not use OCI_Desbribe() unless you're only interested in the resultset + * information because the statement will be parsed again when executed and thus + * leading to unnecessary server round-trips and less performance + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_DescribeFmt +( + OCI_Statement *stmt, + const otext *sql, + ... +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiHashTables Hash tables + * @{ + * + * OCILIB uses hash tables internally for index/name columns mapping. + * + * OCILIB makes public its hash table’s implementation public for general purpose + * uses. + * + * OCI_HashTable objects manage string keys / values that can be : + * + * - integers + * - strings + * - pointers + * + * This hash table implementation : + * + * - handle collisions + * - allows multiple values per key + * + * @par Internal conception + * + * - The hash table is composed of an array of slots. + * - Each slot can hold a linked list of entries (one per key) + * - Each entry can hold a linked list of values + * + * @note + * - The internal hash function computes the index in the array where the entry + * has to be inserted/looked up. + * + * + * @note + * Collisions are handled by chaining method. + * + * @include hash.c + * + */ + +/** + * @brief + * Create a hash table + * + * @param size - size of the hash table + * @param type - type of the hash table + * + * @note + * Parameter can be one of the following values : + * + * - OCI_HASH_STRING : string values + * - OCI_HASH_INTEGER : integer values + * - OCI_HASH_POINTER : pointer values + * + * @return + * Hash handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_HashTable * OCI_API OCI_HashCreate +( + unsigned int size, + unsigned int type +); + +/** + * @brief + * Destroy a hash table + * + * @param table - Table handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_HashFree +( + OCI_HashTable *table +); + +/** + * @brief + * Return the size of the hash table + * + * @param table - Table handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_HashGetSize +( + OCI_HashTable *table +); + +/** + * @brief + * Return the type of the hash table + * + * @param table - Table handle + * + * @note + * the return value can be one of the following values : + * + * - OCI_HASH_STRING : string values + * - OCI_HASH_INTEGER : integer values + * - OCI_HASH_POINTER : pointer values + * + * @return + * Hash table data type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_HashGetType +( + OCI_HashTable *table +); + +/** + * @brief + * Add a pair string key / string value to the hash table + * + * @param table - Table handle + * @param key - String key + * @param value - string value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_HashAddString +( + OCI_HashTable *table, + const otext *key, + const otext *value +); + +/** + * @brief + * Return the string value associated to the given key + * + * @param table - Table handle + * @param key - String key + * + * @return + * Stored string associated with the key otherwise NULL + * + */ + +OCI_EXPORT const otext * OCI_API OCI_HashGetString +( + OCI_HashTable *table, + const otext *key +); + +/** + * @brief + * Adds a pair string key / integer value to the hash table + * + * @param table - Table handle + * @param key - String key + * @param value - Integer value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_HashAddInt +( + OCI_HashTable *table, + const otext *key, + int value +); + +/** + * @brief + * Return the integer value associated to the given key + * + * @param table - Table handle + * @param key - String key + * + * @return + * Stored integer associated with the key otherwise 0 + * + */ + +OCI_EXPORT int OCI_API OCI_HashGetInt +( + OCI_HashTable *table, + const otext *key +); + +/** + * @brief + * Adds a pair string key / pointer value to the hash table + * + * @param table - Table handle + * @param key - String key + * @param value - Pointer value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_HashAddPointer +( + OCI_HashTable *table, + const otext *key, + void *value +); + +/** + * @brief + * Return a pointer associated with the given key + * + * @param table - Table handle + * @param key - String key + * + * @return + * Stored pointer associated with the key otherwise NULL + * + */ + +OCI_EXPORT void * OCI_API OCI_HashGetPointer +( + OCI_HashTable *table, + const otext *key +); + +/** + * @brief + * Lookup for an entry matching the key in the table + * + * @param table - Table handle + * @param key - String key + * @param create - Do create the entry if not exists + * + * @return + * Entry handle if key found/added otherwise NULL + * + */ + +OCI_EXPORT OCI_HashEntry * OCI_API OCI_HashLookup +( + OCI_HashTable *table, + const otext *key, + boolean create +); + +/** + * @brief + * Return the first hash slot that matches the key + * + * @param table - Table handle + * @param key - String key + * + * @return + * Slot handle if key found otherwise NULL + * + */ + +OCI_EXPORT OCI_HashValue * OCI_API OCI_HashGetValue +( + OCI_HashTable *table, + const otext *key +); + +/** + * @brief + * Return the entry slot of the hash table internal list at the given position + * + * @param table - Table handle + * @param index - index + * + * @warning + * Index start at at + * + * @return + * Slot handle otherwise NULL + * + */ + +OCI_EXPORT OCI_HashEntry * OCI_API OCI_HashGetEntry +( + OCI_HashTable *table, + unsigned int index +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiThreading Threads and mutexes + * @{ + * + * Oracle proposes a portable implementation of Mutex and Thread objects + * + * OCILIB implements these OCI features for portable multi-threading support. + * + * Mutexes are designed for mutual exclusion between thread in order to lock resources temporarily + * + * Thread keys can be seen as process-wide variables that have a thread-specific + * values. It allows to create a unique key identified by a name (string) that + * can store values specific to each thread. + * + * OCILIB exposes the types OCI_Mutex, OCI_Thread + * + * @warning + * OCILIB MUST be initialized with OCI_ENV_THREADED to enable threads support + * + * @warning + * OCI_Thread relies on Oracle API which uses natives threading capabilities of + * the supported platform + * + * @warning + * Using OCI_Mutex : + * - On Microsoft Windows, a thread can call OCI_MutexAcquire() more than once + * without any blocking. Just be sure that there is an OCI_MutexRelease() for + * every OCI_MutexAcquire() call + * - On Unix systems, a thread MUST call OCI_MutexRelease() after every call to + * OCI_MutexAcquire() in order to be able to call OCI_MutexAcquire() again. If + * not, it will be blocked... + * + * @par Example + * @include thread.c + * + */ + +/** + * @brief + * Create a Mutex object + * + * @return + * Mutex handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Mutex * OCI_API OCI_MutexCreate +( + void +); + +/** + * @brief + * Destroy a mutex object + * + * @param mutex - Mutex handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MutexFree +( + OCI_Mutex *mutex +); + +/** + * @brief + * Acquire a mutex lock + * + * @param mutex - Mutex handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MutexAcquire +( + OCI_Mutex *mutex +); + +/** + * @brief + * Release a mutex lock + * + * @param mutex - Mutex handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MutexRelease +( + OCI_Mutex *mutex +); + +/** + * @brief + * Create a Thread object + * + * @return + * Thread handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Thread * OCI_API OCI_ThreadCreate +( + void +); + +/** + * @brief + * Destroy a thread object + * + * @param thread - Thread handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadFree +( + OCI_Thread *thread +); + +/** + * @brief + * Execute the given routine within the given thread object + * + * @param thread - Thread handle + * @param proc - routine to execute + * @param arg - parameter to pass to the routine + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadRun +( + OCI_Thread *thread, + POCI_THREAD proc, + void *arg +); + +/** + * @brief + * Join the given thread + * + * @param thread - Thread handle + * + * @note + * This function waits for the given thread to finish + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadJoin +( + OCI_Thread *thread +); + +/** + * @brief + * Create a thread key object + * + * @param name - Thread key name + * @param destfunc - Thread key value destructor function + * + * @note + * Parameter proc is optional. It's called when the thread terminates to allow + * the program to deal with the thread specific value of the key + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadKeyCreate +( + const otext *name, + POCI_THREADKEYDEST destfunc +); + +/** + * @brief + * Set a thread key value + * + * @param name - Thread key name + * @param value - user value to set + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadKeySetValue +( + const otext *name, + void *value +); + +/** + * @brief + * Get a thread key value + * + * @param name - Thread key name + * + * @return + * Thread key value on success otherwise FALSE + * + */ + +OCI_EXPORT void * OCI_API OCI_ThreadKeyGetValue +( + const otext *name +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApidirectPath Direct Path loading + * @{ + * + * OCILIB (from version 3.2.0) support the OCI direct Path API. + * + * Actual implementation of direct path API does not support the following + * elements : + * - Objects data types (User Defined Types and Object References) + * - Object tables + * - Nested tables + * - SQL String functions + * + * All scalar data types (numerics, characters and date/time), including LOBs + * and LONG types are supported + * + * @par Oracle direct API features (from Oracle Documentation) + * + * The direct path load interface allows an application to access the direct path + * load engine of the Oracle database server to perform the functions of the + * Oracle SQL*Loader utility. + * This functionality provides the ability to load data from external files + * into Oracle database objects, either a table or a partition of a partitioned + * table. + * The OCI direct path load interface has the ability to load multiple rows by + * loading a direct path stream which contains data for multiple rows. + * + * @par Oracle direct API limitation (from Oracle Documentation) + * The direct path load interface has the following limitations which are the + * same as SQL*Loader: + * - triggers are not supported + * - check constraints are not supported + * - referential integrity constraints are not supported + * - clustered tables are not supported + * - loading of remote objects is not supported + * - user-defined types are not supported + * - LOBs must be specified after all scalar columns + * - LONGs must be specified last + * + * @warning + * + * Its recommended to use direct path interface with an Oracle client that is + * the same version than the database. With version < 10g, it is mandatory + * regarding that it causes segmentation faults and it's known from Oracle that + * advices to use the same version for client and server (see metalink KB) + * + * @par How to use direct path + * + * - 1 : Create a direct path handle with OCI_DirPathCreate() + * - 2 : Set (optional) some direct path load attributes + * - 3 : Describe the columns to load with OCI_DirPathSetColumn() + * - 4 : Populate data with OCI_DirPathSetEntry() + * - 5 : Convert the data with OCI_DirPathConvert() + * - 6 : Load the data into the database with OCI_DirPathLoad() + * - 7 : Repeat step 4,5,6 + reset the stream with OCI_DirPathReset() until all + * rows has been loaded + * - 8 : Commit the load with OCI_DirPathFinish() + * - 9 : Free the direct path handle with OCI_DirPathFree() + * + * @par Example + * @include dirpath.c + * + */ + +/** + * @brief + * Create a direct path object + * + * @param typinf - Table type info handle + * @param partition - Partition name + * @param nb_cols - Number of columns to load + * @param nb_rows - Maximum of rows to handle per load operation + * + * @note + * Retrieve the table type info handle with OCI_TypeInfoGet(). + * The partition name is not mandatory + * + * @note + * Parameter 'nb_rows' is ignored for Oracle 8i. Prior to Oracle 9i, it's the + * OCI client that decides of the number of rows to process per convert/load calls. + * From Oracle 9i, OCI allows application to specify this value. Note that, the + * OCI client might not accept the input value. After OCI_DirPathPrepare() has + * been successfully called, OCI_DirPathGetMaxRows() returns the final number + * of rows used for the given direct path operation. + * + * @return + * Return the direct path handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_DirPath * OCI_API OCI_DirPathCreate +( + OCI_TypeInfo *typinf, + const otext *partition, + unsigned int nb_cols, + unsigned int nb_rows +); + +/** + * @brief + * Free an OCI_DirPath handle + * + * @param dp - Direct path Handle + * + * @return + * TRUE on success otherwise FALSE + * + */ +OCI_EXPORT boolean OCI_API OCI_DirPathFree +( + OCI_DirPath *dp +); + +/** + * @brief + * Describe a column to load into the given table + * + * @param dp - Direct path Handle + * @param index - Column index + * @param name - Column name + * @param maxsize - Maximum input value size for a column entry + * @param format - Date or numeric format to use + * + * @note + * An error is thrown if : + * - If the column specified by the 'name' parameter is not found in the table + * referenced by the type info handle passed to OCI_DirPathCreate() + * - the index is out of bounds (= 0 or >= number of columns) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetColumn +( + OCI_DirPath *dp, + unsigned int index, + const otext *name, + unsigned int maxsize, + const otext *format +); + +/** + * @brief + * Prepares the OCI direct path load interface before any rows can be converted + * or loaded + * + * @param dp - Direct path Handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathPrepare +( + OCI_DirPath *dp +); + +/** + * @brief + * Set the value of the given row/column array entry + * + * @param dp - Direct path Handle + * @param row - Row index + * @param index - Column index + * @param value - Value to set + * @param size - Size of the input value + * @param complete - Is the entry content fully provided ? + * + * @note + * Rows and columns indexes start at 1. + * + * @note + * The 'size' parameter is expressed in number of : + * - bytes for binary columns + * - characters for other columns + * + * @note + * Direct path support piece loading for LONGs and LOBs columns. When filling + * these columns, it's possible to provide input buffer piece by piece. In order + * to do so : + * - set the 'complete' parameter to FALSE + * - set the 'size' parameter to the piece size + * - Repeat calls to OCI_DirPathSetEntry() until the data is totally provided + * - The last call that set the last piece or an entry must specify the value + * TRUE for the 'complete' parameter + * + * @warning + * Current Direct Path OCILIB implementation DOES NOT support setting entry + * content piece by piece as mentioned above. It was planned in the original design + * but not supported yet. So, always set the complete parameter to TRUE. + * Setting entries content piece by piece may be supported in future releases + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetEntry +( + OCI_DirPath *dp, + unsigned int row, + unsigned int index, + void *value, + unsigned size, + boolean complete +); + +/** + * @brief + * Convert provided user data to the direct path stream format + * + * @param dp - Direct path Handle + * + * @return + * Possible return values : + * - OCI_DPR_COMPLETE : load has been successful + * - OCI_DPR_ERROR : an error happened while loading data + * - OCI_DPR_FULL : the internal stream is full + * - OCI_DPR_PARTIAL : a column hasn't been fully filled yet + * - OCI_DPR_EMPTY : no data was found to convert + * + * @note + * - When using conversion mode OCI_DCM_DEFAULT, OCI_DirPathConvert() stops when + * any error is encountered and returns OCI_DPR_ERROR + * - When using conversion mode OCI_DCM_FORCE, OCI_DirPathConvert() does not stop + * on errors. Instead it discards any erred rows and returns OCI_DPR_COMPLETE once + * all rows are processed. + * + * @note + * List of faulted rows and columns can be retrieved using OCI_DirPathGetErrorRow() and + * OCI_DirPathGetErrorColumn() + * + * @note + * OCI_DirPathGetAffectedRows() returns the number of rows converted in the last call. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathConvert +( + OCI_DirPath *dp +); + +/** + * @brief + * Loads the data converted to direct path stream format + * + * @param dp - Direct path Handle + * + * @return + * Possible return values : + * - OCI_DPR_COMPLETE : conversion has been successful + * - OCI_DPR_ERROR : an error happened while converting data + * - OCI_DPR_FULL : the internal stream is full + * - OCI_DPR_PARTIAL : a column hasn't been fully filled yet + * - OCI_DPR_EMPTY : no data was found to load + * + * @note + * List of faulted rows can be retrieved using OCI_DirPathGetErrorRow() + * + * @note + * OCI_DirPathGetAffectedRows() returns the number of rows successfully loaded in the last call. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathLoad +( + OCI_DirPath *dp +); + +/** + * @brief + * Reset internal arrays and streams to prepare another load + * + * @param dp - Direct path Handle + * + * @note + * Once some data have been converted or loaded, OCI_DirPathReset() resets + * internal OCI structures in order to prepare another load operation + * (set entries, convert and load) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathReset +( + OCI_DirPath *dp +); + +/** + * @brief + * Terminate a direct path operation and commit changes into the database + * + * @param dp - Direct path Handle + * + * @warning + * The direct path handle cannot be used anymore after this call for any more + * loading operations and must be freed with OCI_DirPathFree(). + * + * @note + * Some properties functions of the direct path handle, such as + * OCI_DirPathGetRowCount() can be called on a terminated direct path handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathFinish +( + OCI_DirPath *dp +); + +/** + * @brief + * Terminate a direct path operation without committing changes + * + * @param dp - Direct path Handle + * + * @note + * Any pending loaded data are canceled. + * Any load completion operations, such as index maintenance operations, are not performed. + * + * @warning + * The direct path handle cannot be used anymore after this call for any more + * loading operations and must be freed with OCI_DirPathFree(). + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathAbort +( + OCI_DirPath *dp +); + +/** + * @brief + * Execute a data save-point (server side) + * + * @param dp - Direct path Handle + * + * @note + * Executing a data save-point is not allowed for LOBs + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSave +( + OCI_DirPath *dp +); + +/** + * @brief + * Flushes a partially loaded row from server + * + * @param dp - Direct path Handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathFlushRow +( + OCI_DirPath *dp +); + +/** + * @brief + * Set the current number of rows to convert and load + * + * @param dp - Direct path Handle + * @param nb_rows - Number of row to process + * + * @warning + * An OCILIB error will be thrown if the value exceeds the maximum number of + * rows in the internals arrays + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetCurrentRows +( + OCI_DirPath *dp, + unsigned int nb_rows +); + +/** + * @brief + * Return the current number of rows used in the OCILIB internal + * arrays of rows + * + * @param dp - Direct path Handle + * + * @return + * Internal current array size on SUCCESS otherwise 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetCurrentRows +( + OCI_DirPath *dp +); + +/** + * @brief + * Return the maximum number of rows allocated in the OCI and OCILIB + * internal arrays of rows + * + * @param dp - Direct path Handle + * + * @return + * Internal maximum array size on SUCCESS otherwise 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetMaxRows +( + OCI_DirPath *dp +); + +/** + * @brief + * Set the default date format string for input conversion + * + * @param dp - Direct path Handle + * @param format - date format + * + * @note + * For string to date conversion, Oracle uses : + * - Column date format + * - Default date format (modified by this call) + * - Default global support environment setting + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetDateFormat +( + OCI_DirPath *dp, + const otext *format +); + +/** + * @brief + * Set the parallel loading mode + * + * @param dp - Direct path Handle + * @param value - enable/disable parallel mode + * + * @note + * Default value is FALSE. + * + * @note + * Setting the value to TRUE allows multiple load sessions to load the same + * segment concurrently + * + * @par Parallel loading mode (From Oracle documentation) + * + * A direct load operation requires that the object being loaded is locked to + * prevent DML on the object. + * Note that queries are lock-free and are allowed while the object is being loaded. + * - For a table load, if the option is set to: + * - FALSE, then the table DML X-Lock is acquired. + * - TRUE, then the table DML S-Lock is acquired. + * - For a partition load, if the option is set to: + * - FALSE, then the table DML SX-Lock and partition DML X-Lock is acquired. + * - TRUE, then the table DML SS-Lock and partition DML S-Lock is acquired. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetParallel +( + OCI_DirPath *dp, + boolean value +); + +/** + * @brief + * Set the logging mode for the loading operation + * + * @param dp - Direct path Handle + * @param value - enable/disable logging + * + * @par Logging mode (from Oracle Documentation) + * + * The NOLOG attribute of each segment determines whether image redo or + * invalidation redo is generated: + * - FALSE : Use the attribute of the segment being loaded. + * - TRUE : No logging. Overrides DDL statement, if necessary. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetNoLog +( + OCI_DirPath *dp, + boolean value +); + +/** + * @brief + * Set number of elements in the date cache + * + * @param dp - Direct path Handle + * @param size - Buffer size + * + * @note + * Default value is 0. + * + * @note + * Setting the value to 0 disables the cache + * + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetCacheSize +( + OCI_DirPath *dp, + unsigned int size +); + +/** + * @brief + * Set the size of the internal stream transfer buffer + * + * @param dp - Direct path Handle + * @param size - Buffer size + * + * @note + * Default value is 64KB. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetBufferSize +( + OCI_DirPath *dp, + unsigned int size +); + +/** + * @brief + * Set the direct path conversion mode + * + * @param dp - Direct path Handle + * @param mode - Conversion mode + * + * @note + * Possible values for parameter 'mode' : + * - OCI_DCM_DEFAULT : conversion fails on error + * - OCI_DCM_FORCE : conversion does not fail on error + * + * @note + * See OCI_DirPathConvert() for conversion mode details + * + * @note + * Default value is OCI_DCM_DEFAULT + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetConvertMode +( + OCI_DirPath *dp, + unsigned int mode +); + +/** + * @brief + * Return the number of rows successfully loaded into the database so far + * + * @param dp - Direct path Handle + * + * @note + * Insertions are committed with OCI_DirPathFinish() + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetRowCount +( + OCI_DirPath *dp +); + +/** + * @brief + * return the number of rows successfully processed during in the last + * conversion or loading call + * + * @param dp - Direct path Handle + * + * @note + * This function called after : + * + * - OCI_DirPathConvert(), returns the number of converted rows + * - OCI_DirPathload(), returns the number of loaded rows + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetAffectedRows +( + OCI_DirPath *dp +); + +/** + * @brief + * Return the index of a column which caused an error during data conversion + * + * @param dp - Direct path Handle + * + * @warning + * Direct path column indexes start at 1. + * + * @note + * Errors may happen while data is converted to direct path stream format + * using OCI_DirPathConvert(). + * When using conversion mode OCI_DCM_DEFAULT, OCI_DirPathConvert() returns + * OCI_DPR_ERROR on error. OCI_DirPathGetErrorColumn() returns the column index + * that caused the error + * When using conversion mode OCI_DCM_FORCE, OCI_DirPathConvert() returns + * OCI_DPR_COMPLETE even on errors. In order to retrieve the list of all column + * indexes that have erred, the application can call OCI_DirPathGetErrorColumn() + * repeatedly until it returns 0. + * + * @note + * The internal value is reset to 0 when calling OCI_DirPathConvert() + * + * @return + * 0 is no error occurs otherwise the index of the given column which caused an + * error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetErrorColumn +( + OCI_DirPath *dp +); + +/** + * @brief + * Return the index of a row which caused an error during data conversion + * + * @param dp - Direct path Handle + * + * @warning + * Direct path row indexes start at 1. + * + * @note + * Errors may happen : + * - while data is converted to direct path stream format using OCI_DirPathConvert() + * - while data is loaded to database using OCI_DirPathLoad() + * + * @note + * When using conversion mode OCI_DCM_DEFAULT, OCI_DirPathConvert() returns + * OCI_DPR_ERROR on error. OCI_DirPathGetErrorRow() returns the row index that + * caused the error. + * When using conversion mode OCI_DCM_FORCE, OCI_DirPathConvert() returns + * OCI_DPR_COMPLETE even on errors. In order to retrieve the list of all row + * indexes that have erred, the application can call OCI_DirPathGetErrorRow() + * repeatedly until it returns 0. + * + * @note + * After a call to OCI_DirPathLoad(), in order to retrieve the list of all faulted rows + * indexes, the application can call OCI_DirPathGetErrorRow() repeatedly until it returns 0. + * + * @note + * The internal value is reset to 0 when calling OCI_DirPathConvert(), + * OCI_DirPathReset() or OCI_DirPathLoad() + * + * @return + * 0 is no error occurs otherwise the index of the given row which caused an + * error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetErrorRow +( + OCI_DirPath *dp +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiAdvancedQueuing Oracle Advanced Queuing (A/Q) + * @{ + * + * OCILIB supports Oracle Advanced Queues features + * + * Let's Oracle talk about this features ! + * + * @par Oracle Queues (from Oracle Streams - Advanced Queuing User's Guide) + * + * Oracle Streams AQ provides database-integrated message queuing functionality. + * It is built on top of Oracle Streams and leverages the functions of Oracle + * Database so that messages can be stored persistently, propagated between + * queues on different computers and databases, and transmitted using Oracle + * Net Services and HTTP(S). + * Because Oracle Streams AQ is implemented in database tables, all operational + * benefits of high availability, scalability, and reliability are also + * applicable to queue data. Standard database features such as recovery, + * restart, and security are supported by Oracle Streams AQ. You can use + * database development and management tools such as Oracle Enterprise Manager + * to monitor queues. Like other database tables, queue tables can be imported + * and exported. + * + * @par OCILIB implementation + * + * OCILIB provides a (nearly) full C implementation of Advanced Queues available in + * Oracle OCI and proposes the following data types : + * - OCI_Msg : Implementation of message to enqueue/dequeue from/to queues + * - OCI_Enqueue : Implementation of enqueuing process + * - OCI_Dequeue : Implementation of dequeuing process + * - OCI_Agent : Implementation of Advanced queues Agents + * + * OCILIB support AQ messages notification with Oracle Client 10gR2 or above + * + * Note that the only AQ features not supported yet by OCILIB are : + * - Payloads of type AnyData + * - Enqueuing/dequeuing arrays of messages + * - Optional delivery mode introduced in 10gR2 + * + * OCILIB provides as well a C API to administrate queues and queue tables initially + * reserved to PL/SQL and Java (wrappers around PL/SQL calls). + * This API, based on internal PL/SQL calls wrapping the DBMS_AQADM packages procedures, allow the + * following actions : + * - create, alter, drop and purge queue tables (OCI_QueueTableXXX calls) + * - create, alter, drop, start, stop queues (OCI_QueueXXX calls) + * + * Note that the user connected to the database needs particular privileges to manipulate or + * administrate queues (See Oracle Streams - Advanced Queuing User's Guide for more informations + * on these privileges) + * + *@par Example + * @include queue.c + * + */ + +/** + * @brief + * Create a message object based on the given payload type + * + * @param typinf - Type info handle + * + * @note + * OCILIB supports 2 type of message payload : + * - Oracle types (UDT) + * - RAW data + * + * @note + * Oracle Type AnyData is not supported in the current version of OCILIB + * + * @note + * the parameter 'typinf' indicates the type of payload : + * - For object payload, retrieve the object type information handle with + * OCI_TypeInfoGet() using the object type name + * - For RAW payload, you MUST pass the object type information retrieved with + * OCI_TypeInfoGet() using "SYS.RAW" as object type name + * + * @warning + * Newly created Message handles have NULL payloads. + * For Message handling Objects payloads, OCI_MsgGetObject() returns NULL until an object handle is + * assigned to the message. + * + * @note + * When a local OCI_Msg handle is enqueued, it keeps its attributes. If it's enqueued again, another + * identical message is posted into the queue. + * To reset a message and empty all its properties, call OCI_MsgReset() + * Note that OCI_MsgReset() clears the message payload. + * + * @return + * Return the message handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Msg * OCI_API OCI_MsgCreate +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a message object + * + * @param msg - Message handle + * + * @warning + * Only message handles created with OCI_MsgCreate() should be freed by OCI_MsgFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgFree +( + OCI_Msg *msg +); + +/** + * @brief + * Reset all attributes of a message object + * + * @param msg - Message handle + * + * @note + * This function calls OCI_MsgSetxxx() with default or NULL attributes + * + * @warning + * OCI_MsgReset() clears the message payload and set it to NULL + * For messages handling objects payloads, OCI_MsgSetObject() must be called again to assign a + * payload. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgReset +( + OCI_Msg *msg +); + +/** + * @brief + * Get the object payload of the given message + * + * @param msg - Message handle + * + * @return + * Return the object handle on success otherwise NULL on failure or if payload is NULL + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_MsgGetObject +( + OCI_Msg *msg +); + +/** + * @brief + * Set the object payload of the given message + * + * @param msg - Message handle + * @param obj - Object handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetObject +( + OCI_Msg *msg, + OCI_Object *obj +); + +/** + * @brief + * Get the RAW payload of the given message + * + * @param msg - Message handle + * @param raw - Input buffer + * @param size - Input buffer maximum size + * + * @note + * On output, parameter 'size' holds the number of bytes copied into the given buffer + * + * @return + * TRUE on success otherwise FALSE on failure or if payload is object based. + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgGetRaw +( + OCI_Msg *msg, + void *raw, + unsigned int *size +); + +/** + * @brief + * Set the RAW payload of the given message + * + * @param msg - Message handle + * @param raw - Raw data + * @param size - Raw data size + * + * @return + * TRUE on success otherwise FALSE on failure or if payload is object based. + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetRaw +( + OCI_Msg *msg, + const void *raw, + unsigned int size +); + +/** + * @brief + * Return the number of attempts that have been made to dequeue the message + * + * @param msg - Message handle + * + */ + +OCI_EXPORT int OCI_API OCI_MsgGetAttemptCount +( + OCI_Msg *msg +); + +/** + * @brief + * Return the number of seconds that a message is delayed for dequeuing + * + * @param msg - Message handle + * + * @note + * see OCI_MsgSetEnqueueDelay() for more details + * + */ + +OCI_EXPORT int OCI_API OCI_MsgGetEnqueueDelay +( + OCI_Msg *msg +); + +/** + * @brief + * set the number of seconds to delay the enqueued message + * + * @param msg - Message handle + * @param value - Delay in seconds + * + * @note + * The delay represents the number of seconds after which a message is available for dequeuing. + * When the message is enqueued, its state is set to OCI_AMS_WAITING. + * When the delay expires, its state is set to OCI_AMS_READY. + * + * @note + * If parameter 'value' is set to zero (default value), the message will be immediately available + * for dequeuing + * + * @warning + * Dequeuing by Message ID overrides the delay specification. + * + * @warning + * Delaying processing requires the queue monitor to be started. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetEnqueueDelay +( + OCI_Msg *msg, + int value +); + +/** + * @brief + * return the time the message was enqueued + * + * @param msg - Message handle + * + * @note + * Only use this function for message dequeued from queues + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_MsgGetEnqueueTime +( + OCI_Msg *msg +); + +/** + * @brief + * Return the duration that the message is available for dequeuing + * + * @param msg - Message handle + * + * @note + * see OCI_MsgSetExpiration() for more details + * + */ + +OCI_EXPORT int OCI_API OCI_MsgGetExpiration +( + OCI_Msg *msg +); + +/** + * @brief + * set the duration that the message is available for dequeuing + * + * @param msg - Message handle + * @param value - duration in seconds + * + * @note + * This parameter is an offset from the delay (see OCI_MsgSetEnqueueDelay()) + * While waiting for expiration, the message state is set to OCI_AMS_READY. + * If the message is not dequeued before it expires, it will be moved to the exception queue + * with the state OCI_AMS_EXPIRED. + * + * @note + * If parameter 'value' is set to -1 (default value), the message will not expire + * + * @warning + * Expiration processing requires the queue monitor to be started. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetExpiration +( + OCI_Msg *msg, + int value +); + +/** + * @brief + * Return the state of the message at the time of the dequeue + * + * @param msg - Message handle + * + * @return + * - OCI_UNKNOWN : the function has failed to get the message state + * - OCI_AMS_READY : the message is ready to be processed + * - OCI_AMS_WAITING : the message delay has not yet completed + * - OCI_AMS_PROCESSED : the message has been processed + * - OCI_AMS_EXPIRED : the message has moved to exception queue + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_MsgGetState +( + OCI_Msg *msg +); + +/** + * @brief + * Return the priority of the message + * + * @param msg - Message handle + * + * @note + * see OCI_MsgSetPriority() for more details + * + */ + +OCI_EXPORT int OCI_API OCI_MsgGetPriority +( + OCI_Msg *msg +); + +/** + * @brief + * Set the priority of the message + * + * @param msg - Message handle + * @param value - Message priority + * + * @note + * - The priority can be any number, including negative numbers. + * - A smaller number indicates higher priority. + * - Default value is zero. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetPriority +( + OCI_Msg *msg, + int value +); + +/** + * @brief + * Return the ID of the message + * + * @param msg - Message handle + * @param id - Input buffer + * @param len - Input buffer maximum size + * + * @note + * The message ID is : + * - generated when the message is enqueued in the queue + * - retrieved when the message is dequeued from the queue + * + * @note + * On output, parameter 'len' holds the number of bytes copied into the given buffer + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgGetID +( + OCI_Msg *msg, + void *id, + unsigned int *len +); + +/** + * @brief + * Return the original ID of the message in the last queue that generated this message + * + * @param msg - Message handle + * @param id - Input buffer + * @param len - Input buffer maximum size + * + * @warning + * When a message is propagated from/to different queues, this ID is the one generated for the + * message in the previous queue. + * + * @note + * On output, parameter 'len' holds the number of bytes copied into the given buffer + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgGetOriginalID +( + OCI_Msg *msg, + void *id, + unsigned int *len +); + +/** + * @brief + * Set the original ID of the message in the last queue that generated this message + * + * @param msg - Message handle + * @param id - Message ID + * @param len - Message ID size + * + * @warning + * When a message is propagated from/to different queues, this ID is the one generated for the + * message in the previous queue. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetOriginalID +( + OCI_Msg *msg, + const void *id, + unsigned int len +); + +/** + * @brief + * Return the original sender of a message + * + * @param msg - Message handle + * + * @return + * Sender Handle (OCI_Agent *) on success (if set at enqueue time) otherwise NULL + * + */ + +OCI_EXPORT OCI_Agent * OCI_API OCI_MsgGetSender +( + OCI_Msg *msg +); + +/** + * @brief + * Set the original sender of a message + * + * @param msg - Message handle + * @param sender - Message sender + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetSender +( + OCI_Msg *msg, + OCI_Agent *sender +); + +/** + * @brief + * Set the recipient list of a message to enqueue + * + * @param msg - Message handle + * @param consumers - Recipients list (array of agent handles) + * @param count - Number of recipients + * + * @warning + * This function should only be used for queues which allow multiple consumers. + * The default recipients are the queue subscribers. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetConsumers +( + OCI_Msg *msg, + OCI_Agent **consumers, + unsigned int count +); + +/** + * @brief + * Get the correlation identifier of the message + * + * @param msg - Message handle + * + * @note + * see OCI_MsgSetCorrelation() for more details + * + */ + +OCI_EXPORT const otext * OCI_API OCI_MsgGetCorrelation +( + OCI_Msg *msg +); + +/** + * @brief + * set the correlation identifier of the message + * + * @param msg - Message handle + * @param correlation - Message correlation text + * + * @note + * see OCI_DequeueSetCorrelation() for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetCorrelation +( + OCI_Msg *msg, + const otext *correlation +); + +/** + * @brief + * Get the Exception queue name of the message + * + * @param msg - Message handle + * + * @warning + * When calling this function on a message retrieved with OCI_DequeueGet(), the returned value is + * NULL if the default exception queue associated with the current queue is used (e.g. no user + * defined specified at enqueue time for the message) + * + * @note + * see OCI_MsgSetExceptionQueue() for more details + * + */ +OCI_EXPORT const otext * OCI_API OCI_MsgGetExceptionQueue +( + OCI_Msg *msg +); + +/** + * @brief + * Set the name of the queue to which the message is moved to if it cannot be + * processed successfully + * + * @param msg - Message handle + * @param queue - Exception queue name + * + * @warning + * From Oracle Documentation : + * + * "Messages are moved into exception queues in two cases : + * - If the number of unsuccessful dequeue attempts has exceeded the attribute 'max_retries' of + * given queue + * - if the message has expired. + * + * All messages in the exception queue are in the EXPIRED state. + * + * The default is the exception queue associated with the queue table. + * + * If the exception queue specified does not exist at the time of the move the message will be + * moved to the default exception queue associated with the queue table and a warning will be + * logged in the alert file. + * + * This attribute must refer to a valid queue name." + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetExceptionQueue +( + OCI_Msg *msg, + const otext *queue +); + +/** + * @brief + * Create a Enqueue object for the given queue + * + * @param typinf - Type info handle + * @param name - Queue name + * + * @note + * OCILIB supports 2 type of message payload : + * - Oracle types (UDT) + * - RAW data + * + * @note + * Oracle Type AnyData is not supported in the current version of OCILIB + * + * @note + * the parameter 'typinf' indicates the type of payload to enqueue to the given queue : + * - For object payload, retrieve the object type information handle with + * OCI_TypeInfoGet() using the object type name + * - For RAW payload, you MUST pass the object type information retrieved with + * OCI_TypeInfoGet() using "SYS.RAW" as object type name + * + * @return + * Return the Enqueue handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Enqueue * OCI_API OCI_EnqueueCreate +( + OCI_TypeInfo *typinf, + const otext *name +); + +/** + * @brief + * Free a Enqueue object + * + * @param enqueue - Enqueue handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueueFree +( + OCI_Enqueue *enqueue +); + +/** + * @brief + * Enqueue a message on the queue associated to the Enqueue object + * + * @param enqueue - Enqueue handle + * @param msg - Message handle to enqueue + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueuePut +( + OCI_Enqueue *enqueue, + OCI_Msg *msg +); + +/** +* @brief +* Set the enqueuing sequence of messages to put in the queue +* +* @param enqueue - Enqueue handle +* @param sequence - enqueuing sequence +* +* @note +* Possible values for parameter 'sequence' : +* - OCI_ASD_BEFORE : enqueue message before another message +* - OCI_ASD_TOP : enqueue message before all messages +* +* @note +* Default value is OCI_ASD_TOP +* +* @note +* if the parameter 'sequence' is set to OCI_ASD_BEFORE, the application must +* call OCI_EnqueueSetRelativeMsgID() before enqueuing the next message in the queue. +* +* @note +* In order to stop enqueuing message using a sequence deviation, call +* OCI_EnqueueSetSequenceDeviation() with the value OCI_ASD_TOP +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_EnqueueSetSequenceDeviation +( + OCI_Enqueue *enqueue, + unsigned int sequence +); + +/** + * @brief + * Return the sequence deviation of messages to enqueue to the queue + * + * @param enqueue - Enqueue handle + * + * @note + * see OCI_EnqueueSetSequenceDeviation() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_EnqueueGetSequenceDeviation +( + OCI_Enqueue *enqueue +); + +/** + * @brief + * Set whether the new message is enqueued as part of the current transaction + * + * @param enqueue - Enqueue handle + * @param visibility - Enqueuing visibility + * + * @note + * Possible values for parameter 'visibility' : + * - OCI_AMV_IMMEDIATE : enqueue is an independent transaction + * - OCI_AMV_ON_COMMIT : enqueue is part of current transaction + * + * @note + * Default value is OCI_AMV_ON_COMMIT + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueueSetVisibility +( + OCI_Enqueue *enqueue, + unsigned int visibility +); + +/** + * @brief + * Get the enqueuing/locking behavior + * + * @param enqueue - Enqueue handle + * + * @note + * see OCI_EnqueueSetVisibility() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_EnqueueGetVisibility +( + OCI_Enqueue *enqueue +); + +/** + * @brief + * Set a message identifier to use for enqueuing messages using a sequence deviation + * + * @param enqueue - Enqueue handle + * @param id - message identifier + * @param len - pointer to message identifier length + * + * @note + * This call is only valid if OCI_EnqueueSetSequenceDeviation() has been called + * with the value OCI_ASD_BEFORE + * + * @warning + * if the function cannot assign the message id, the content of the parameter 'len' is set to zero. + * + * @note + * see OCI_EnqueueSetSequenceDeviation() for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueueSetRelativeMsgID +( + OCI_Enqueue *enqueue, + const void *id, + unsigned int len +); + +/** + * @brief + * Get the current associated message identifier used for enqueuing messages + * using a sequence deviation + * + * @param enqueue - Enqueue handle + * @param id - buffer to receive the message identifier + * @param len - pointer to buffer max length + * + * @warning + * When the function returns, parameter 'len' hold the number of bytes assigned to parameter 'id' + * + * @note + * see OCI_EnqueueGetRelativeMsgID() for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueueGetRelativeMsgID +( + OCI_Enqueue *enqueue, + void *id, + unsigned int *len +); + +/** + * @brief + * Create a Dequeue object for the given queue + * + * @param typinf - Type info handle + * @param name - Queue name + * + * @note + * OCILIB supports 2 type of message payload : + * - Oracle types (UDT) + * - RAW data + * + * @note + * Oracle Type AnyData is not supported in the current version of OCILIB + * + * @note + * the parameter 'typinf' indicates the type of payload to dequeue from the given queue : + * - For object payload, retrieve the object type information handle with + * OCI_TypeInfoGet() using the object type name + * - For RAW payload, you MUST pass the object type information retrieved with + * OCI_TypeInfoGet() using "SYS.RAW" as object type name + * + * @return + * Return the Dequeue handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Dequeue * OCI_API OCI_DequeueCreate +( + OCI_TypeInfo *typinf, + const otext *name +); + +/** + * @brief + * Free a Dequeue object + * + * @param dequeue - Dequeue handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueFree +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Dequeue messages from the given queue + * + * @param dequeue - Dequeue handle + * + * @warning + * The returned message is handled by the dequeue object. + * Do not release it with OCI_MsgFree() + * + * @warning + * When dequeuing from a multiple consumer queue, you need + * to set the navigation mode to OCI_ADN_FIRST_MSG using + * OCI_DequeueSetNavigation() + * + * @return + * Message handle on success otherwise NULL on failure or on timeout + * + */ + +OCI_EXPORT OCI_Msg * OCI_API OCI_DequeueGet +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Subscribe for asynchronous messages notifications + * + * @param dequeue - Dequeue handle + * @param port - Port to use for notifications + * @param timeout - notification timeout + * @param callback - User handler callback fired when messages are ready to be dequeued + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * asynchronous messages notifications + * + * @note + * Requires Oracle Client 10gR2 or above + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSubscribe +( + OCI_Dequeue *dequeue, + unsigned int port, + unsigned int timeout, + POCI_NOTIFY_AQ callback +); + +/** + * @brief + * Unsubscribe for asynchronous messages notifications + * + * @param dequeue - Dequeue handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueUnsubscribe +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the current consumer name to retrieve message for. + * + * @param dequeue - Dequeue handle + * @param consumer - consumer name + * + * @warning + * If a queue is not set up for multiple consumers, OCI_DequeueSetConsumer() + * should not be called or called with parameter 'consumer' set to NULL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetConsumer +( + OCI_Dequeue *dequeue, + const otext *consumer +); + +/** + * @brief + * Get the current consumer name associated with the dequeuing process. + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetConsumer() for more details + * + */ + +OCI_EXPORT const otext * OCI_API OCI_DequeueGetConsumer +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * set the correlation identifier of the message to be dequeued + * + * @param dequeue - Dequeue handle + * @param pattern - correlation identifier + * + * @note + * Special pattern matching characters, such as "%" or "_" can be used. + * If more than one message satisfies the pattern, the order of dequeuing is undetermined. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetCorrelation +( + OCI_Dequeue *dequeue, + const otext *pattern +); + +/** + * @brief + * Get the correlation identifier of the message to be dequeued + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetCorrelation() for more details + * + */ + +OCI_EXPORT const otext * OCI_API OCI_DequeueGetCorrelation +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the message identifier of the message to be dequeued + * + * @param dequeue - Dequeue handle + * @param id - message identifier + * @param len - size of the message identifier + * + * @warning + * if the function cannot assign the message id, the content of the parameter 'len' is set to zero. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetRelativeMsgID +( + OCI_Dequeue *dequeue, + const void *id, + unsigned int len +); + +/** + * @brief + * Get the message identifier of the message to be dequeued + * + * @param dequeue - Dequeue handle + * @param id - message identifier + * @param len - size of the message identifier + * + * @warning + * When the function returns, parameter 'len' hold the number of bytes assigned to parameter 'id' + * + * @note + * see OCI_DequeueSetRelativeMsgID() for more details + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueGetRelativeMsgID +( + OCI_Dequeue *dequeue, + void *id, + unsigned int *len +); + +/** + * @brief + * Set whether the new message is dequeued as part of the current transaction + * + * @param dequeue - Dequeue handle + * @param visibility - dequeuing mode + * + * @warning + * The visibility parameter is ignored when using the OCI_ADM_BROWSE dequeuing + * mode (see OCI_DequeueSetMode()) + * + * @note + * Possible values for parameter 'mode' : + * - OCI_AMV_IMMEDIATE : dequeue is an independent transaction + * - OCI_AMV_ON_COMMIT : dequeue is part of current transaction + * + * @note + * Default value is OCI_AMV_ON_COMMIT + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetVisibility +( + OCI_Dequeue *dequeue, + unsigned int visibility +); + +/** + * @brief + * Get the dequeuing/locking behavior + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetVisibility() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DequeueGetVisibility +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the dequeuing/locking behavior + * + * @param dequeue - Dequeue handle + * @param mode - dequeuing mode + * + * @note + * Possible values for parameter 'mode' : + * - OCI_ADM_BROWSE : read message without acquiring a lock + * - OCI_ADM_LOCKED : read and obtain write lock on message + * - OCI_ADM_REMOVE : read the message and delete it + * - OCI_ADM_REMOVE_NODATA : confirm receipt of the message, but do not + * deliver the actual message content + * + * @note + * Default value is OCI_ADM_REMOVE + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetMode +( + OCI_Dequeue *dequeue, + unsigned int mode +); + +/** + * @brief + * Get the dequeuing/locking behavior + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetMode() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DequeueGetMode +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the position of messages to be retrieved. + * + * @param dequeue - Dequeue handle + * @param position - navigation position + * + * @note + * The dequeuing uses the following sequence : + * - find messages using the navigation position + * - apply search criteria (message correlation) + * - get message + * + * @note + * Possible values for parameter 'position' : + * - OCI_ADN_FIRST_MSG : retrieves the first message which is available + * - OCI_ADN_NEXT_MSG : retrieves the next message which is available + * - OCI_ADN_NEXT_TRANSACTION : skips the remainder of the current transaction + * group (if any) and retrieves the first message + * of the next transaction group. + * + * @note + * Default value is OCI_ADN_NEXT_MSG + * + * @warning + * OCI_ADN_NEXT_TRANSACTION can only be used if message grouping is enabled for the given queue. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetNavigation +( + OCI_Dequeue *dequeue, + unsigned int position +); + +/** + * @brief + * Return the navigation position of messages to retrieve from the queue + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetNavigation() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DequeueGetNavigation +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * set the time that OCIDequeueGet() waits for messages if no messages are + * currently available + * + * @param dequeue - Dequeue handle + * @param timeout - timeout in seconds + * + *@note + * - Any positive values in seconds are valid. + * - The value 0 is accepted and means OCIDequeueGet() does not wait for + * messages and returns immediately if no messages are available + * - The value -1 is accepted and means OCIDequeueGet() waits for ever (until + * a message is available in the queue) + * + * @note + * Default value is -1 (wait for ever) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetWaitTime +( + OCI_Dequeue *dequeue, + int timeout +); + +/** + * @brief + * Return the time that OCIDequeueGet() waits for messages if no messages are currently available + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetWaitTime() for more details + * + */ + +OCI_EXPORT int OCI_API OCI_DequeueGetWaitTime +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the Agent list to listen to message for + * + * @param dequeue - Dequeue handle + * @param consumers - Agent handle array + * @param count - Number of agents the array + * + * @return + * return TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetAgentList +( + OCI_Dequeue *dequeue, + OCI_Agent **consumers, + unsigned int count +); + +/** + * @brief + * Listen for messages that match any recipient of the associated Agent list + * + * @param dequeue - Dequeue handle + * @param timeout - Timeout in second + * + * @note + * If an Agent handle is returned, messages are available for this agent. + * In order to retrieve its messages : + * - call OCI_DequeueSetConsumer() with the name of agent using OCI_AgentGetName() + * - call OCI_DequeueGet() to dequeue it's pending messages + * + * @warning + * The return value is valid only until: + * - OCIDequeueListen() is called again + * - OCI_DequeueFree(à is called to free the Dequeue object + * So Do not store the handle value across calls to OCIDequeueListen() + * + * @return + * An Agent handle for who messages are available on success otherwise NULL + */ + +OCI_EXPORT OCI_Agent * OCI_API OCI_DequeueListen +( + OCI_Dequeue *dequeue, + int timeout +); + +/** + * @brief + * Create an AQ agent object + * + * @param con - Connection handle + * @param name - Agent name + * @param address - Agent address + * + * @note + * An AQ agent object is : + * - used as recipient information when enqueuing a message + * - used as sender information when dequeuing a message + * - used for listening message only from identified senders + * + * @note + * the AQ agent address can be any Oracle identifier, up to 128 bytes. + * the AQ agent name can be any Oracle identifier, up to 30 bytes. + * + * @return + * AQ agent handle on success otherwise NULL + * + */ + +OCI_EXPORT OCI_Agent * OCI_API OCI_AgentCreate +( + OCI_Connection *con, + const otext *name, + const otext *address +); + +/** + * @brief + * Free an AQ agent object + * + * @param agent - AQ agent handle + * + * @warning + * Only AQ agent handle created with OCI_AgentCreate() should be freed by OCI_AgentFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_AgentFree +( + OCI_Agent *agent +); + +/** + * @brief + * Set the given AQ agent name + * + * @param agent - AQ agent handle + * @param name - AQ agent name + * + * @note + * the AQ agent name is used to identified an message send or recipient when enqueuing/dequeuing + * a message + * + * @note + * the AQ agent name can be any Oracle identifier, up to 30 bytes. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_AgentSetName +( + OCI_Agent *agent, + const otext *name +); + +/** + * @brief + * Get the given AQ agent name + * + * @param agent - AQ agent handle + * + * @return + * AQ agent name on success otherwise NULL on failure + * + */ + +OCI_EXPORT const otext * OCI_API OCI_AgentGetName +( + OCI_Agent *agent +); + +/** + * @brief + * Set the given AQ agent address + * + * @param agent - AQ agent handle + * @param address - AQ agent address + * + * @note + * the parameter 'address' must be of the form : [schema.]queue_name[\@dblink] + * + * @note + * the AQ agent address can be any Oracle identifier, up to 128 bytes. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_AgentSetAddress +( + OCI_Agent *agent, + const otext *address +); + +/** + * @brief + * Get the given AQ agent address + * + * @param agent - AQ agent handle + * + * @note + * See OCI_AgentSetAddress() + * + * @return + * AQ agent address on success otherwise NULL on failure + * + */ + +OCI_EXPORT const otext * OCI_API OCI_AgentGetAddress +( + OCI_Agent *agent +); + +/** + * @brief + * Create a queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * @param queue_table - Queue table name + * @param queue_type - Queue type + * @param max_retries - Maximum number of attempts to dequeue a message + * @param retry_delay - Number of seconds between attempts to dequeue a message + * @param retention_time - number of seconds a message is retained in the queue table after + * being dequeued from the queue + * @param dependency_tracking - Parameter reserved for future use by Oracle (MUST be set to FALSE) + * @param comment - Description of the queue + * + * @note + * Parameter 'queue_name' can specify the schema where to create to queue ([schema.]queue_name) + * Queue names cannot be longer than 24 characters (Oracle limit for user queues) + * + * @note + * Possible values for parameter 'queue_type' : + * - OCI_AQT_NORMAL : Normal queue + * - OCI_AQT_EXCEPTION : Exception queue + * - OCI_AQT_NON_PERSISTENT : Non persistent queue + * + * To set default values, pass : + * - queue_type : OCI_AQT_NORMAL + * - max_retries : 0 + * - retry_delay : 0 + * - retention_time : 0 + * - comment : NULL + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.CREATE_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueCreate +( + OCI_Connection *con, + const otext *queue_name, + const otext *queue_table, + unsigned int queue_type, + unsigned int max_retries, + unsigned int retry_delay, + unsigned int retention_time, + boolean dependency_tracking, + const otext *comment +); + +/** + * @brief + * Alter the given queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * @param max_retries - Maximum number of attempts to dequeue a message + * @param retry_delay - Number of seconds between attempts to dequeue a message + * @param retention_time - number of seconds a message is retained in the queue table after + * being dequeued from the queue + * @param comment - Description of the queue + * + * @note + * See OCI_QueueCreate() for more details + * + * @warning + * This function updates all attributes handled in the parameter list ! + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.ALTER_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueAlter +( + OCI_Connection *con, + const otext *queue_name, + unsigned int max_retries, + unsigned int retry_delay, + unsigned int retention_time, + const otext *comment +); + +/** + * @brief + * Drop the given queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * + * @warning + * A queue can be dropped only if it has been stopped before. + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.DROP_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueDrop +( + OCI_Connection *con, + const otext *queue_name +); + +/** + * @brief + * Start the given queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * @param enqueue - Enable enqueue + * @param dequeue - Enable dequeue + * + * @warning + * For exception queues, only enqueuing is allowed + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.START_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueStart +( + OCI_Connection *con, + const otext *queue_name, + boolean enqueue, + boolean dequeue +); + +/** + * @brief + * Stop enqueuing or dequeuing or both on the given queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * @param enqueue - Disable enqueue + * @param dequeue - Disable dequeue + * @param wait - Wait for current pending enqueues/dequeues + * + * @warning + * A queue cannot be stopped if there are pending transactions against the queue. + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.STOP_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueStop +( + OCI_Connection *con, + const otext *queue_name, + boolean enqueue, + boolean dequeue, + boolean wait +); + +/** + * @brief + * Create a queue table for messages of the given type + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param queue_payload_type - Message type name + * @param storage_clause - Additional clauses for the table storage + * @param sort_list - Additional columns name to use for sorting + * @param multiple_consumers - Enable multiple consumers for each messages + * @param message_grouping - Specifies if messages are grouped within a transaction + * @param comment - Description of the queue table + * @param primary_instance - primary owner (instance) of the queue table + * @param secondary_instance - Owner of the queue table if the primary instance is not available + * @param compatible - lowest database version with which the queue table is compatible + * + * @note + * Parameter 'queue_table' can specify the schema where to create to queue table ([schema.]queue_table) + * Queue table names cannot be longer than 24 characters (Oracle limit for user queue tables) + * + * @note + * Possible values for parameter 'queue_payload_type' : + * - For Oracle types (UDT) : use the type name ([schema.].type_name) + * - For RAW data : use "SYS.RAW" or "RAW" + * + * @note + * Possible values for parameter 'message_grouping' : + * - OCI_AGM_NONE : each message is treated individually + * - OCI_AGM_TRANSACTIONNAL : all messages enqueued in one transaction are considered part of + * the same group and can be dequeued as a group of related messages. + * + * @note + * Possible values for parameter 'compatible' : + * - "8.0", "8.1", "10.0" + * + * To set default values, pass : + * - storage_clause : NULL + * - sort_list : NULL + * - message_grouping : OCI_AGM_NONE + * - comment : NULL + * - primary_instance : 0 + * - primary_instance : 0 + * - compatible : NULL + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.CREATE_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTableCreate +( + OCI_Connection *con, + const otext *queue_table, + const otext *queue_payload_type, + const otext *storage_clause, + const otext *sort_list, + boolean multiple_consumers, + unsigned int message_grouping, + const otext *comment, + unsigned int primary_instance, + unsigned int secondary_instance, + const otext *compatible +); + +/** + * @brief + * Alter the given queue table + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param comment - Description of the queue table + * @param primary_instance - primary owner (instance) of the queue table + * @param secondary_instance - Owner of the queue table if the primary instance is not available + * + * @note + * See OCI_QueueTableCreate() from more details + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.ALTER_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTableAlter +( + OCI_Connection *con, + const otext *queue_table, + const otext *comment, + unsigned int primary_instance, + unsigned int secondary_instance +); + +/** + * @brief + * Drop the given queue table + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param force - Force the deletion of objects related to the queue table + * + * @note + * Possible values for 'force' : + * - TRUE : all queues using the queue table and their associated propagation schedules are + * dropped automatically + * - FALSE : All the queues using the given queue table must be stopped and dropped before the + * queue table can be dropped. + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.DROP_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTableDrop +( + OCI_Connection *con, + const otext *queue_table, + boolean force +); + +/** + * @brief + * Purge messages from the given queue table + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param purge_condition - Optional SQL based conditions (see notes) + * @param block - Lock all queues using the queue table while doing the purge + * @param delivery_mode - Type of message to purge + * + * @note + * Possible values for parameter 'delivery_mode' : + * - OCI_APM_BUFFERED : purge only buffered messages + * - OCI_APM_PERSISTENT : purge only persistent messages + * - OCI_APM_ALL : purge all messages + * + * @note + * For more information about the SQL purge conditions, refer to + * Oracle Streams - Advanced Queuing User's Guide for more details + * + * @warning + * This feature is only available from ORacle 10gR2. + * This function does nothing and returns TRUE is the server version is < Oracle 10gR2 + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.PURGE_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTablePurge +( + OCI_Connection *con, + const otext *queue_table, + const otext *purge_condition, + boolean block, + unsigned int delivery_mode +); + +/** + * @brief + * Migrate a queue table from one version to another + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param compatible - Database version with witch the queue table has to migrate + * + * @note + * Possible values for parameter 'compatible' : + * - "8.0", "8.1", "10.0" + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.MIGRATE_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTableMigrate +( + OCI_Connection *con, + const otext *queue_table, + const otext *compatible +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiSubscriptions Database Change notifications (DCN or CQN) + * @{ + * + * OCILIB supports Oracle 10gR2 feature Database Change Notifications (DCN) + * also named Continuous Query Notifications (CQN) + * + * This features allows a client application to register notifications + * when some changes are made in a database : + * - Database status changes : startup and shutdown + * - Database objects changes : + * - DDL changes : alter or drop actions + * - DML changes : insert, delete, update actions + * + * This feature can be really useful in applications that hold + * a cache of data. Instead of refreshing data periodically by + * connecting to the server, the application could only refresh + * modified data when necessary or perform specific tasks depending on + * the events. It saves application time, network traffic and can help + * the design of the application logic. + * + * The database status change notification is also interesting to be + * informed of instance startup / shutdown + * + * Check Oracle documentation for more details about this feature + * + * @note + * No active database connection is required to receive the + * notifications as they are handled by the Oracle client using a + * dedicated socket connection to the server + * + * @par Database changes + * + * The client application can be notified of any database status + * change (single DB or multiple DB in a RAC environment). + * + * @par Object changes + * + * The notifications of object changes are based on the registration + * of a query ('select' SQL statement). + * + * Oracle server will notify of any changes of any object that is + * part of the statement result set. + * + * Registering a statement will notify about any changes on its + * result set rows performed after the registration of the query. + * + * The query can be a simple 'select * from table' or a complex + * query involving many tables and/or criteria in the where clause. + * + * For Object changes, the notification can be at : + * - At Object level : only the object name (schema + object) is given + * - At row level : same that object level + RowID of the altered row + * + * @warning + * Trying to use this features with a client/server version < 10gR2 will raise an error + * + * @par Example + * @include notification.c + * + */ + +/** + * @brief + * Register a notification against the given database + * + * @param con - Connection handle + * @param name - Notification name + * @param type - Subscription type + * @param handler - User handler callback + * @param port - Port to use for notifications + * @param timeout - notification timeout + * + * @note + * Parameter 'type' can be one of the following values : + * + * - OCI_CNT_OBJECTS : request for changes at objects (e.g. tables) level (DDL / DML) + * - OCI_CNT_ROWS : request for changes at rows level (DML) + * - OCI_CNT_DATABASES : request for changes at database level (startup, shutdown) + * - OCI_CNT_ALL : request for all changes + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @note + * Requires Oracle Client 10gR2 or above + * + * @note + * Subscription handles are automatically managed by the library + * + * @return + * Subscription handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Subscription * OCI_API OCI_SubscriptionRegister +( + OCI_Connection *con, + const otext *name, + unsigned int type, + POCI_NOTIFY handler, + unsigned int port, + unsigned int timeout +); + +/** + * @brief + * Unregister a previously registered notification + * + * @param sub - Subscription handle + * + * @note + * OCI_Cleanup() will automatically unregister any registered subscriptions + * + * @note + * If the database connection passed to OCI_SubscriptionRegister() + * has been closed by the time that the application calls + * OCI_SubscriptionUnregister, the library internally reconnects + * to the given database, performs the unregistration and then disconnects + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SubscriptionUnregister +( + OCI_Subscription *sub +); + +/** + * @brief + * Add a statement to the notification to monitor + * + * @param sub - Subscription handle + * @param stmt - Statement handle + * + * @note + * The given statement must be prepared but not executed before being passed to this function. + * OCI_SubscriptionAddStatement() executes the statement and register it for notifications + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @note + * The given statement must hold a 'SELECT' SQL statement + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SubscriptionAddStatement +( + OCI_Subscription *sub, + OCI_Statement *stmt +); + +/** + * @brief + * Return the name of the given registered subscription + * + * @param sub - Subscription handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT const otext * OCI_API OCI_SubscriptionGetName +( + OCI_Subscription *sub +); + +/** + * @brief + * Return the port used by the notification + * + * @param sub - Subscription handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_SubscriptionGetPort +( + OCI_Subscription *sub +); + +/** + * @brief + * Return the timeout of the given registered subscription + * + * @param sub - Subscription handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_SubscriptionGetTimeout +( + OCI_Subscription *sub +); + +/** + * @brief + * Return the connection handle associated with a subscription handle + * + * @param sub - Subscription handle + * + * @note + * It may return a NULL handle if the connection used in OCI_SubscriptionRegister has been closed. + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_SubscriptionGetConnection +( +OCI_Subscription *sub +); + +/** + * @brief + * Return the type of event reported by a notification + * + * @param event - Event handle + * + * @note + * The returned value can be one of the following values : + * + * - OCI_ENT_STARTUP : a database has been started up + * - OCI_ENT_SHUTDOWN : a database has been shut down + * - OCI_ENT_SHUTDOWN_ANY : a database has been shut down (RAC) + * - OCI_ENT_DROP_DATABASE : a database has been dropped + * - OCI_ENT_DEREGISTER : the notification is timed out + * - OCI_ENT_OBJECT_CHANGED : a database object has been modified + * + * @note + * OCI_EventGetDatabase() returns the affected database + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @note + * OCI_EventGetObject() returns the affected object + * ('schema_name'.'object_name') + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_EventGetType +( + OCI_Event *event +); + +/** + * @brief + * Return the type of operation reported by a notification + * + * @param event - Event handle + * + * @note + * This call is only valid when OCI_EventGetType() reports the + * event type OCI_ENT_OBJECT_CHANGED + * + * @note + * The returned value can be one of the following values : + * + * - OCI_ONT_INSERT : an insert has been performed + * - OCI_ONT_UPDATE : an update has been performed + * - OCI_ONT_DELETE : a delete has been performed + * - OCI_ONT_ALTER : an alter has been performed + * - OCI_ONT_DROP : a drop has been performed + * - OCI_ONT_GENERIC : generic undefined action + * + * @note + * OCI_EventGetDatabase() returns the affected database + * + * @note + * OCI_EventGetObject() returns the affected object ('schema_name'.'object_name') + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @note + * if OCI_CNT_ROWS is passed to OCI_SubscriptionRegister(), + * the rowid of the altered row can be retrieved with OCI_EventGetRowid() + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_EventGetOperation +( + OCI_Event *event +); + +/** + * @brief + * Return the name of the database that generated the event + * + * @param event - Event handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT const otext * OCI_API OCI_EventGetDatabase +( + OCI_Event *event +); + +/** + * @brief + * Return the name of the object that generated the event + * + * @param event - Event handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT const otext * OCI_API OCI_EventGetObject +( + OCI_Event *event +); + +/** + * @brief + * Return the rowid of the altered database object row + * + * @param event - Event handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT const otext * OCI_API OCI_EventGetRowid +( + OCI_Event *event +); + +/** + * @brief + * Return the subscription handle that generated this event + * + * @param event - Event handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT OCI_Subscription * OCI_API OCI_EventGetSubscription +( + OCI_Event *event +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiInstancesManagement Remote Instance startup/shutdown + * @{ + * + * OCILIB supports Oracle 11g client features for manipulating remote Oracle instances. + * + * Oracle instances (on the same computer or on a remote server) can be : + * + * - started with OCI_DatabaseStartup() + * - shutdown with OCI_DatabaseShutdown() + * + * Several options are handled for this actions + * + * @par Example + * @include instance.c + * + */ + +/** + * @brief + * Start a database instance + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param sess_mode - Session mode + * @param start_mode - Start mode + * @param start_flag - Start flags + * @param spfile - Client-side spfile to start up the database (optional) + * + * Possible values for parameter sess_mode : + * - OCI_SESSION_SYSDBA + * - OCI_SESSION_SYSOPER + * + * @note + * External credentials are supported by supplying a null value for the 'user' and 'pwd' parameters + * If the param 'db' is NULL then a connection to the default local DB is done + * + * Possible (combined) values for parameter start_mode : + * - OCI_DB_SPM_START : start the instance + * - OCI_DB_SPM_MOUNT : mount the instance + * - OCI_DB_SPM_OPEN : open the instance + * - OCI_DB_SPM_FULL : start, mount and open the instance + * + * Possible (combined) values for parameter start_flag : + * - OCI_DB_SPF_DEFAULT : default startup + * - OCI_DB_SPF_FORCE : shuts down a running instance (if needed) using + * ABORT command and starts a new instance + * - OCI_DB_SPF_RESTRICT : allows database access only to users with both + * CREATE SESSION and RESTRICTED SESSION privileges + * + * @note + * If the client side spfile is not provided, the database is started with its server-side spfile + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DatabaseStartup +( + const otext *db, + const otext *user, + const otext *pwd, + unsigned int sess_mode, + unsigned int start_mode, + unsigned int start_flag, + const otext *spfile +); + +/** + * @brief + * Shutdown a database instance + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param sess_mode - Session mode + * @param shut_mode - Shutdown mode + * @param shut_flag - Shutdown flag + * + * + * @warning + * Possible values for parameter sess_mode : + * - OCI_SESSION_SYSDBA + * - OCI_SESSION_SYSOPER + * + * @note + * External credentials are supported by supplying a null value for the 'user' and 'pwd' parameters + * If the param 'db' is NULL then a connection to the default local DB is done + * + * Possible (combined) values for parameter shut_mode : + * - OCI_DB_SDM_SHUTDOWN : shutdown the instance + * - OCI_DB_SDM_CLOSE : close the instance + * - OCI_DB_SDM_DISMOUNT : dismount the instance + * - OCI_DB_SDM_FULL : shutdown, close and dismount the instance + * + * Possible (exclusive) value for parameter shut_flag (from Oracle documentation) : + * - OCI_DB_SDF_DEFAULT : + * - Further connects are prohibited. + * - Waits for users to disconnect from the database + * - OCI_DB_SDF_TRANS : + * - Further connects are prohibited + * - No new transactions are allowed. + * - Waits for active transactions to complete + * - OCI_DB_SDF_TRANS_LOCAL : + * - Further connects are prohibited + * - No new transactions are allowed. + * - Waits only for local transactions to complete + * - OCI_DB_SDF_IMMEDIATE : + * - Does not wait for current calls to complete or users to disconnect from the database. + * - All uncommitted transactions are terminated and rolled back + * - OCI_DB_SDF_ABORT : + * - Does not wait for current calls to complete or users to disconnect from the database. + * - All uncommitted transactions are terminated and are not rolled back. + * - This is the fastest possible way to shut down the database, but the next + * database startup may require instance recovery. + * - Therefore, this option should be used only in unusual circumstances + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DatabaseShutdown +( + const otext *db, + const otext *user, + const otext *pwd, + unsigned int sess_mode, + unsigned int shut_mode, + unsigned int shut_flag +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiRawHandles Using OCI Handles directly + * @{ + * + * OCILIB conception was focused on a full but closed encapsulation of OCI. + * + * All OCI headers, data types, prototypes are imported internally + * (linkage or runtime import). + * + * OCILIB public interface exposes only ISO C scalar types and OCILIB objects + * + * OCI is a wide and rich API that can deals with hundreds of options ! + * + * OCILIB tries to implements most of it. But, sometimes in really specific + * contexts, it might be necessary to directly call OCI APIs in order to use + * uncovered OCI functionalities or options + * + * OCILIB proposes now a set of functions to retrieve its internal OCI handles + * + * @warning + * + * The OCILIB author strongly advises against the use of internal handles, + * unless there is no other way to accomplish the task + * + * @warning + * + * Using these handles for direct application calls to OCI might lead + * to OCILIB instability or crash if handles are incorrectly used ! + * + */ + +/** + * @brief + * Return the OCI Environment Handle (OCIEnv *) of OCILIB library + * + * @return + * OCI Environment handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetEnvironment +( + void +); + +/** + * @brief + * Return the OCI Context Handle (OCISvcCtx *) of an OCILIB OCI_Connection object + * + * @param con - Connection handle + * + * @return + * OCI Context handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetContext +( + OCI_Connection *con +); + +/** + * @brief + * Return the OCI Server Handle (OCIServer *) of an OCILIB OCI_Connection object + * + * @param con - Connection handle + * + * @return + * OCI Server handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetServer +( + OCI_Connection *con +); + +/** + * @brief + * Return the OCI Error Handle (OCIError *) of an OCILIB OCI_Connection object + * + * @param con - Connection handle + * + * @return + * OCI Error handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetError +( + OCI_Connection *con +); + +/** + * @brief + * Return the OCI Session Handle (OCISession *) of an OCILIB OCI_Connection object + * + * @param con - Connection handle + * + * @return + * OCI Session handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetSession +( + OCI_Connection *con +); + +/** + * @brief + * Return the OCI Transaction Handle (OCITrans *) of an OCILIB OCI_Transaction object + * + * @param trans - Transaction handle + * + * @return + * OCI Transaction handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetTransaction +( + OCI_Transaction *trans +); + +/** + * @brief + * Return the OCI Statement Handle (OCIStmt *) of an OCILIB OCI_Statement object + * + * @param stmt - Statement handle + * + * @return + * OCI Statement handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetStatement +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the OCI LobLocator Handle (OCILobLocator *) of an OCILIB OCI_Lob object + * + * @param lob - Lob handle + * + * @return + * OCI LobLocator handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetLob +( + OCI_Lob *lob +); + +/** + * @brief + * Return the OCI LobLocator Handle (OCILobLocator *) of an OCILIB OCI_File object + * + * @param file - File handle + * + * @return + * OCI LobLocator handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetFile +( + OCI_File *file +); + +/** + * @brief + * Return the OCI Date Handle (OCIDate *) of an OCILIB OCI_Date object + * + * @param date - Date handle + * + * @return + * OCI Date handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetDate +( + OCI_Date *date +); + +/** + * @brief + * Return the OCI Date time Handle (OCIDatetime *) of an OCILIB OCI_Timestamp object + * + * @param tmsp - Timestamp handle + * + * @return + * OCI Date time handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetTimestamp +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Return OCI Interval Handle (OCIInterval *) of an OCILIB OCI_Interval object + * + * @param itv - Interval handle + * + * @return + * OCI Interval handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetInterval +( + OCI_Interval *itv +); + +/** + * @brief + * Return OCI Object Handle (void *) of an OCILIB OCI_Object object + * + * @param obj - Object handle + * + * @return + * OCI Object handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetObject +( + OCI_Object *obj +); + +/** + * @brief + * Return OCI Collection Handle (OCIColl *) of an OCILIB OCI_Coll object + * + * @param coll - Collection handle + * + * @return + * OCI Collection handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetColl +( + OCI_Coll *coll +); + +/** + * @brief + * Return OCI Ref Handle (OCIRef *) of an OCILIB OCI_Ref object + * + * @param ref - Ref handle + * + * @return + * OCI Ref handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetRef +( + OCI_Ref *ref +); + +/** + * @brief + * Return OCI Mutex handle (OCIThreadMutex *) of an OCILIB OCI_Mutex object + * + * @param mutex - Mutex handle + * + * @return + * OCI Mutex handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetMutex +( + OCI_Mutex *mutex +); + +/** + * @brief + * Return OCI Thread ID (OCIThreadId *) of an OCILIB OCI_Thread object + * + * @param thread - Thread handle + * + * @return + * OCI Thread ID otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetThreadID +( + OCI_Thread *thread +); + +/** + * @brief + * Return OCI Thread handle (OCIThreadHandle *) of an OCILIB OCI_Thread object + * + * @param thread - Thread handle + * + * @return + * OCI Thread handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetThread +( + OCI_Thread *thread +); + +/** + * @brief + * Return OCI DirectPath Context handle (OCIDirPathCtx *) of an OCILIB OCI_DirPath object + * + * @param dp - DirectPath handle + * + * @return + * OCI DirectPath Context handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetDirPathCtx +( + OCI_DirPath *dp +); + +/** + * @brief + * Return OCI DirectPath Column array handle (OCIDirPathColArray *) of an OCILIB OCI_DirPath object + * + * @param dp - DirectPath handle + * + * @return + * OCI DirectPath Column array handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetDirPathColArray +( + OCI_DirPath *dp +); + +/** + * @brief + * Return OCI DirectPath Stream handle (OCIDirPathStream *) of an OCILIB OCI_DirPath object + * + * @param dp - DirectPath handle + * + * @return + * OCI DirectPath Stream handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetDirPathStream +( + OCI_DirPath *dp +); + +/** + * @brief + * Return OCI Subscription handle (OCISubscription *) of an OCILIB OCI_Subscription object + * + * @param sub - Subscription handle + * + * @return + * OCI Subscription otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetSubscription +( + OCI_Subscription *sub +); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +/** +* @defgroup OcilibCApiEnvironmentVariables Environment Variables +* @{ +* +* Some environment variables can be defined in order to activate specific features +* They must have one of the following values (case insensitive) for being enabled : "TRUE", "1" +* +* - "OCILIB_WORKAROUND_UTF16_COLUMN_NAME": This variable enables an experimental workaround for the Oracle bug 9838993: +* - When calling OCI_GetResultset(), OCILIB queries column names against the Oracle Client +* - Unicode builds of OCILIB initialize Oracle client into UTF16 mode +* - In such environments, a memory leak occurs when statements are re-executed multiple times followed by OCI_GetResultset() +* - This workaround retrieves column names using direct access to undocumented Oracle structures instead of using buggy Oracle calls +* - As Oracle undocumented structures may change upon versions, this workaround is provided as-is in case the Oracle bug represents an real issue for applications +* - This workaround has been tested with 32bit and 64bit Oracle 12g clients and Unicode OCILIB builds +*/ + +#define VAR_OCILIB_WORKAROUND_UTF16_COLUMN_NAME "OCILIB_WORKAROUND_UTF16_COLUMN_NAME" + +/** +* @} +*/ + +/** + * @defgroup OcilibCApiDemoApplication OCILIB main demo application code + * @{ + * + * Portable Main demo application header + * @include ocilib_demo.h + * + * Portable Main demo application source + * @include ocilib_demo.c + * + * @} + */ + +/* Compatibility with sources built with older versions of OCILIB */ + +/* macros added in version 2.3.0 */ + +#define OCI_CreateConnection OCI_ConnectionCreate +#define OCI_FreeConnection OCI_ConnectionFree +#define OCI_CreateStatement OCI_StatementCreate +#define OCI_FreeStatement OCI_StatementFree + +/* macros added in version 2.4.0 */ + +#define OCI_CreateTransaction OCI_TransactionCreate +#define OCI_FreeTransaction OCI_TransactionFree +#define OCI_CreateHashTable OCI_HashCreate +#define OCI_FreeHashTable OCI_HashFree + +/* macros added in version 3.0.0 */ + +#define OCI_GetColumnName OCI_ColumnGetName +#define OCI_GetColumnType OCI_ColumnGetType +#define OCI_GetColumnCharsetForm OCI_ColumnGetCharsetForm +#define OCI_GetColumnSQLType OCI_ColumnGetSQLType +#define OCI_GetColumnFullSQLType OCI_ColumnGetFullSQLType +#define OCI_GetColumnSize OCI_ColumnGetSize +#define OCI_GetColumnScale OCI_ColumnGetScale +#define OCI_GetColumnPrecision OCI_ColumnGetPrecision +#define OCI_GetColumnFractionnalPrecision OCI_ColumnGetFractionnalPrecision +#define OCI_GetColumnLeadingPrecision OCI_ColumnGetLeadingPrecision +#define OCI_GetColumnNullable OCI_ColumnGetNullable +#define OCI_GetColumnCharUsed OCI_ColumnGetCharUsed + +#define OCI_GetFormatDate(s) OCI_GetDefaultFormatDate(OCI_StatementGetConnection(s)) +#define OCI_SetFormatDate(s, f) OCI_SetDefaultFormatDate(OCI_StatementGetConnection(s), f) + +#define OCI_ERR_API OCI_ERR_ORACLE + +/* macros added in version 3.2.0 */ + +#define OCI_ERR_NOT_SUPPORTED OCI_ERR_DATATYPE_NOT_SUPPORTED +#define OCI_SCHEMA_TABLE OCI_TIF_TABLE +#define OCI_SCHEMA_VIEW OCI_TIF_VIEW +#define OCI_SCHEMA_TYPE OCI_TIF_TYPE + +#define OCI_Schema OCI_TypeInfo + +#define OCI_SchemaGet OCI_TypeInfoGet +#define OCI_SchemaFree OCI_TypeInfoFree +#define OCI_SchemaGetColumnCount OCI_TypeInfoGetColumnCount +#define OCI_SchemaGetColumn OCI_TypeInfoGetColumn +#define OCI_SchemaGetName OCI_TypeInfoGetName + +#define OCI_ColumnGetFractionnalPrecision OCI_ColumnGetFractionalPrecision + +/* macro added in version 3.3.0 */ + +/** + * @brief + * [OBSOLETE] Set the bind variable at the given index to null + * + * @param stmt - Statement handle + * @param index - Index of the bind variable + * + * @warning + * This call is obsolete ! Use OCI_BindSetNull() instead. + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Index starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +#define OCI_SetNull(stmt, index) \ + OCI_BindSetNull(OCI_GetBind(stmt, index)) + +/** + * @brief + * [OBSOLETE] Set the bind variable of the given name to null + * + * @param stmt - Statement handle + * @param name - Bind variable name + * + * @warning + * This call is obsolete ! Use OCI_BindSetNull() instead. + * + * @note + * There is no notion of null value in C. + * it's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +#define OCI_SetNull2(stmt, name) \ + OCI_BindSetNull(OCI_GetBind2(stmt, name)) + +/** + * @brief + * [OBSOLETE] Set to null the bind variable at the given position in an input array + * + * @param stmt - Statement handle + * @param index - Index of the bind variable + * @param position - Position in the array + * + * @warning + * This call is obsolete ! Use OCI_BindSetNullAtPos() instead. + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Index and Position starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + * + */ + +#define OCI_SetNullAtPos(stmt, index, position) \ + OCI_BindSetNullAtPos(OCI_GetBind(stmt, index), position) + +/** + * @brief + * [OBSOLETE] Set to null the bind variable of the given name in an input array + * + * @param stmt - Statement handle + * @param name - Bind variable name + * @param position - Position in the array + * + * @warning + * This call is obsolete ! Use OCI_BindSetNullAtPos() instead. + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Position starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + * + */ + +#define OCI_SetNullAtPos2(stmt, name, position) \ + OCI_BindSetNullAtPos(OCI_GetBind2(stmt, name), position) + +/* macro added in version 3.4.0 */ + +#define OCI_8 OCI_8_1 +#define OCI_9 OCI_9_0 +#define OCI_10 OCI_10_1 +#define OCI_11 OCI_11_1 + +/* macro added in version 3.6.0 */ + +#define OCI_CHAR_UNICODE OCI_CHAR_WIDE +#define OCI_CSF_CHARSET OCI_CSF_DEFAULT + +/* macro added in version 3.7.0 */ + +#define OCI_ConnPool OCI_Pool + +#define OCI_ConnPoolCreate(db, us, pw, mo, mi, ma, in) \ + OCI_PoolCreate(db, us, pw, OCI_POOL_CONNECTION, mo, mi, ma, in) + +#define OCI_ConnPoolGetConnection(p) \ + OCI_PoolGetConnection(p, NULL) + +#define OCI_ConnPoolFree OCI_PoolFree +#define OCI_ConnPoolGetTimeout OCI_PoolGetConnection +#define OCI_ConnPoolSetTimeout OCI_PoolSetTimeout +#define OCI_ConnPoolGetNoWait OCI_PoolGetNoWait +#define OCI_ConnPoolSetNoWait OCI_PoolSetNoWait +#define OCI_ConnPoolGetBusyCount OCI_PoolGetBusyCount +#define OCI_ConnPoolGetOpenedCount OCI_PoolGetOpenedCount +#define OCI_ConnPoolGetMin OCI_PoolGetMin +#define OCI_ConnPoolGetMax OCI_PoolGetMax +#define OCI_ConnPoolGetIncrement OCI_PoolGetIncrement + +/* macro added in version 3.8.0 */ + +#define OCI_ObjectGetTimeStamp OCI_ObjectGetTimestamp +#define OCI_ElemGetTimeStamp OCI_ElemGetTimestamp +#define OCI_TimestampSysTimeStamp OCI_TimestampSysTimestamp + +/* macro added in version 4.0.0 */ + +#define OCI_CollSetAt OCI_CollSetElem +#define OCI_CollGetAt OCI_CollGetElem +#define OCI_CollGetAt2 OCI_CollGetElem2 + +#define OCI_GetCharsetMetaData OCI_GetCharset +#define OCI_GetCharsetUserData OCI_GetCharset +#define OCI_SIZE_TRACE_INF0 OCI_SIZE_TRACE_INFO + +#define MT(x) OTEXT(x) +#define mtext otext +#define DT(x) OTEXT(x) +#define dtext otext + +#define mtsdup ostrdup +#define mtscpy ostrcpy +#define mtsncpy ostrncpy +#define mtscat ostrcat +#define mtsncat ostrncat +#define mtslen ostrlen +#define mtscmp ostrcmp +#define mtscasecmp ostrcasecmp +#define mtsprintf osprintf +#define mtstol ostrtol +#define mtsscanf osscanf + +#define dtsdup ostrdup +#define dtscpy ostrcpy +#define dtsncpy ostrncpy +#define dtscat ostrcat +#define dtsncat ostrncat +#define dtslen ostrlen +#define dtscmp ostrcmp +#define dtscasecmp ostrcasecmp +#define dtsprintf osprintf +#define dtstol ostrtol +#define dtsscanf osscanf + +/* macro added in version 4.1.0 */ + +#define OCI_SetDefaultFormatDate(con, fmt) OCI_SetFormat(con, OCI_FMT_DATE, fmt) +#define OCI_SetDefaultFormatNumeric(con, fmt) OCI_SetFormat(con, OCI_FMT_NUMERIC, fmt) + +#define OCI_GetDefaultFormatDate(con) OCI_GetFormat(con, OCI_FMT_DATE) +#define OCI_GetDefaultFormatNumeric(con) OCI_GetFormat(con, OCI_FMT_NUMERIC) + +#define OCI_STRING_FORMAT_NUM_BIN OCI_STRING_FORMAT_NUM_BDOUBLE + +/** + * @} + */ + +#endif /* OCILIB_H_INCLUDED */ + diff --git a/ocilib/4.4.0/AIX-00FB437F4C00/libocilib.a.4 b/ocilib/4.4.0/AIX-00FB437F4C00/libocilib.a.4 new file mode 100755 index 0000000000000000000000000000000000000000..ad258dd589ad3f570d84817839a613763c02adfb Binary files /dev/null and b/ocilib/4.4.0/AIX-00FB437F4C00/libocilib.a.4 differ diff --git a/ocilib/4.4.0/Linux-x86_64/include/ocilib.h b/ocilib/4.4.0/Linux-x86_64/include/ocilib.h new file mode 100755 index 0000000000000000000000000000000000000000..06088b1f45648b724c24b6933a1516a780890ddd --- /dev/null +++ b/ocilib/4.4.0/Linux-x86_64/include/ocilib.h @@ -0,0 +1,19176 @@ +/* + * OCILIB - C Driver for Oracle (C Wrapper for Oracle OCI) + * + * Website: http://www.ocilib.net + * + * Copyright (c) 2007-2017 Vincent ROGIER + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* IMPORTANT NOTICE + * + * This file contains explanations about Oracle and OCI technologies. + * OCILIB is a wrapper around OCI and thus exposes OCI features. + * The OCILIB documentation intends to explain Oracle / OCI concepts + * and is naturally based on the official Oracle OCI documentation. + * + * Some parts of OCILIB documentation may include some informations + * taken and adapted from the following Oracle documentations : + * - Oracle Call Interface Programmer's Guide + * - Oracle Streams - Advanced Queuing User's Guide + */ + +#ifndef OCILIB_H_INCLUDED +#define OCILIB_H_INCLUDED + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + + +/** + * @defgroup OcilibCApi C API + * @{ + * + */ + +/* --------------------------------------------------------------------------------------------- * + * Platform configuration + * --------------------------------------------------------------------------------------------- */ + +#ifdef HAVE_CONFIG_H + #include +#endif + +/* --------------------------------------------------------------------------------------------- * + * C headers + * --------------------------------------------------------------------------------------------- */ + +#include +#include +#include +#include +#include +#include +#include +#include + +/* --------------------------------------------------------------------------------------------- * + * MS Windows platform detection + * --------------------------------------------------------------------------------------------- */ + +#ifndef _WINDOWS + #if defined(_WIN32)|| defined(WIN32) || defined(_WIN64) || defined(WIN64) || defined(_WIN32_WINNT) + #define _WINDOWS + #endif +#endif + +#ifdef _WINDOWS + #ifdef boolean + #undef boolean + #endif + #include + #ifdef boolean + #undef boolean + #endif +#endif + +/* --------------------------------------------------------------------------------------------- * + * OCILIB version information + * --------------------------------------------------------------------------------------------- */ + +#define OCILIB_MAJOR_VERSION 4 +#define OCILIB_MINOR_VERSION 4 +#define OCILIB_REVISION_VERSION 0 + +/* Import mode */ + +#define OCI_IMPORT_MODE_LINKAGE 1 +#define OCI_IMPORT_MODE_RUNTIME 2 + +#ifdef OCI_IMPORT_RUNTIME + #undef OCI_IMPORT_LINKAGE +#endif + +#ifdef OCI_IMPORT_LINKAGE + #undef OCI_IMPORT_RUNTIME +#endif + +#if !defined(OCI_IMPORT_RUNTIME) && !defined(OCI_IMPORT_LINKAGE) + #define OCI_IMPORT_LINKAGE +#endif + +#ifdef OCI_IMPORT_RUNTIME + #define OCI_IMPORT_MODE OCI_IMPORT_MODE_RUNTIME +#else + #define OCI_IMPORT_MODE OCI_IMPORT_MODE_LINKAGE +#endif + +/* Charset modes */ + +#ifdef OCI_CHARSET_UNICODE + #define OCI_CHARSET_WIDE +#endif + +#ifdef OCI_CHARSET_WIDE + #undef OCI_CHARSET_ANSI +#endif + +#ifdef OCI_CHARSET_ANSI + #undef OCI_CHARSET_ANSI +#endif + +#if !defined(OCI_CHARSET_ANSI) && !defined(OCI_CHARSET_WIDE) + #define OCI_CHARSET_ANSI +#endif + +/* Calling convention */ + +#ifndef OCI_API + #ifdef _MSC_VER + #define OCI_API __stdcall + #else + #define OCI_API + #endif +#endif + +/* Build mode */ + +#ifndef OCI_EXPORT + #define OCI_EXPORT +#endif + +/** + * @defgroup OcilibCApiSupportedCharsets Character sets + * @{ + * + * OCILIB supports both ANSI and Unicode. + * + * Oracle started a real Unicode support with Oracle8i but only for bind and fetch data. + * All SQL and PL/SQ/ statements, database objects names were still only supported in ANSI. + * + * With Oracle 9i, Oracle provides a full Unicode support. + * + * So depending on the compile time Oracle library or the runtime loaded library, Unicode support differs. + * + * OCILIB supports: + * + * - ANSI (char) + * - Unicode (wchar_t) + * - UTF8 strings + * + * OCILIB uses the character type 'otext' that is a define around char and wchar_t depending on the charset mode. + * + * @par Option OCI_CHARSET_ANSI + * + * - otext --> char + * - OTEXT(x) --> x + * + * @par Option OCI_CHARSET_WIDE + * + * - otext --> wchar_t + * - OTEXT(x) --> L ## x + * + * @par Unicode and ISO C + * + * Well, ISO C: + * - doesn't know anything about Unicode. + * - makes wide characters support tricky because wide character size is not defined and is freely adaptable by implementations. + * + * OCILIB uses char/wchar_t strings for both public interface and internal storage. + * + * Unicode builds of OCILIB initialize OCI in UTF16 Unicode mode. + * Oracle implements this mode with a 2 bytes (fixed length) UTF16 encoding. + * + * @warning + * When using Unicode builds of OCILIB, make sure that the target + * Database charset is also using an Unicode charset or is a superset of UTF16. + * If not, strings may be converted with substitution characters by the Oracle client ! + * + * So, on systems implementing wchar_t as 2 bytes based UTF16 (e.g. Ms Windows), + * strings are directly passed to Oracle and taken back from it. + * + * On other systems (most of the Unix systems) that use UTF32 as encoding, (4 bytes based wchar_t), OCILIB uses: + * - temporary buffers for statements and object names + * - buffer expansion from UTF16 to UTF32 for fetch and bind string: + * - allocation based on sizeof(wchar_t) + * - data filling based on sizeof(short) -> (UTF16 2 bytes) + * - data expansion to sizeof(wchar_t). + * + * Buffer expansion is done in place and has the advantage of not requiring extra buffer. + * That reduces the cost of the Unicode/ISO C handling overhead on Unix systems. + * + * @par UTF8 strings + * + * OCILIB fully supports UTF8 strings : + * - Within OCI_CHARSET_ANSI builds + * - NLS_LANG environment variable must be set to any valid UTF8 Oracle charset string + * + * @par Charset mapping macros + * + * OCILIB main header file provides macro around most common string functions of + * the C standard library. + * + * these macros are based on the model: ostr[libc function name]() + * + * xxx is the standard C library string function name without the character type prefix (str/wcs). + * + * List of available macros: + * - ostrdup + * - ostrcpy + * - ostrncpy + * - ostrcat + * - ostrncat + * - ostrlen + * - ostrcmp + * - ostrcasecmp + * - osprintf + * - ostol + * +**/ + +#if defined(__cplusplus) && defined(_MSC_VER) && (_MSC_VER < 1300) +extern "C++" { +#endif + +#include + +#if defined(__cplusplus) && defined(_MSC_VER) && (_MSC_VER < 1300) +} +#endif + +/* Charset macros */ + +#define OCI_CHAR_ANSI 1 +#define OCI_CHAR_WIDE 2 + +#ifdef OCI_CHARSET_ANSI + typedef char otext; + #define OTEXT(x) x + #define OCI_CHAR_TEXT OCI_CHAR_ANSI +#else + typedef wchar_t otext; + #define OTEXT(x) L ## x + #define OCI_CHAR_TEXT OCI_CHAR_WIDE +#endif + +/* + For ISO conformance, strdup/wcsdup/stricmp/strncasecmp are not used. + All wide char routines are part of the 1995 Normative Addendum 1 to the ISO C90 standard. + OCILIB also needs an ANSI equivalent to swprintf => ocisprintf + Thus OCILIB exports the following helper functions + +*/ + +OCI_EXPORT int ocisprintf +( + char *str, + int size, + const char *format, + ... +); + +OCI_EXPORT char * ocistrdup +( + const char * src +); + +OCI_EXPORT int ocistrcasecmp +( + const char *str1, + const char *str2 +); + +OCI_EXPORT wchar_t * ociwcsdup +( + const wchar_t * src +); + +OCI_EXPORT int ociwcscasecmp +( + const wchar_t *str1, + const wchar_t *str2 +); + +/* special defines for Microsoft C runtime that is not C ISO compliant */ + +#ifdef _WINDOWS + + #define vsnprintf _vsnprintf + #define swprintf _snwprintf + +#endif + +/* helpers mapping macros */ + +#ifdef OCI_CHARSET_ANSI + #define ostrdup ocistrdup + #define ostrcpy strcpy + #define ostrncpy strncpy + #define ostrcat strcat + #define ostrncat strncat + #define ostrlen strlen + #define ostrcmp strcmp + #define ostrcasecmp ocistrcasecmp + #define osprintf ocisprintf + #define ostrtol strtol + #define osscanf sscanf + #define otoupper toupper + #define oisdigit isdigit +#else + #define ostrdup ociwcsdup + #define ostrcpy wcscpy + #define ostrncpy wcsncpy + #define ostrcat wcscat + #define ostrncat wcsncat + #define ostrlen wcslen + #define ostrcmp wcscmp + #define ostrcasecmp ociwcscasecmp + #define osprintf swprintf + #define ostrtol wcstol + #define osscanf swscanf + #define otoupper towupper + #define oisdigit iswdigit + +#endif + +/* string size macros */ + +#define otextsize(s) (ostrlen(s) * sizeof(otext)) + +/** + * @} + */ + +/** + * @defgroup OcilibCApiDatatypes Data types + * @{ + * + * OCILIB implements: + * + * - Oracle Scalar data types through scalar C data types + * - Oracle opaque/complex objects though opaque library handles + * - Library objects for manipulating the database: connections, transactions, statements... + * + * @par Supported Oracle data types + * + * - All Database types are supported excluding REFs. + * + * Here is a summary of the supported data types: + * + * - Scalar types CHAR/NCHAR, VARCHAR2/NVARCHAR2, NUMBER, FLOAT, REAL, RAW, ... + * - Binary types: RAW, LONG RAW, VARRAW, .. + * - Larges Objects (Lobs and Files) : BLOB, CLOB, NCLOB, BFILE + * - LONG types: LONG, VAR LONG + * - Date, Timestamps et Intervals: DATE, TIMESTAMP, INTERVAL + * - PL/SQL types: Ref cursors, PL/SQL Tables + * - Named Types (by value): Built-in system objects and User defined objects + * - VARRAYs and Nested Tables + * - ROWIDs + * + * @par OCILIB library objects + * + * The public OCILIB library interface implements encapsulation for + * representing database objects (such as connections, statements ...) through + * opaque structures (pointers to structures whose definition is kept private) + * + * Instead of directly manipulating the structures and their members, the library + * has functions to access the underlying members. + * + * It's designed to make the user code as more independent as possible of + * the library details. + * +**/ + +/** + * @typedef OCI_Pool + * + * @brief + * Pool object (session or connection) + * + * A pool is a set of pooled objects + * + */ + +typedef struct OCI_Pool OCI_Pool; + +/** + * @typedef OCI_Connection + * + * @brief + * Oracle physical connection. + * + * It holds all information about a connection such as error handling, associated statements, ... + * Error handling and transactions are embedded within a connection object. + * + * @warning + * Multi threaded applications that use multiple connections should use one connection per thread + * as all statements associated with a connection share the same context. + * + */ + +typedef struct OCI_Connection OCI_Connection; + +/** + * @typedef OCI_Statement + * + * @brief + * Oracle SQL or PL/SQL statement. + * + * A Statement object allows users to prepare, execute SQL orders or PL/SQL blocks + * + */ + +typedef struct OCI_Statement OCI_Statement; + +/** + * @typedef OCI_Bind + * + * @brief + * Internal bind representation. + * + * A bind object is an object that holds all information about an Oracle statement binding operation + * + */ + +typedef struct OCI_Bind OCI_Bind; + +/** + * @typedef OCI_Resultset + * + * @brief + * Collection of output columns from a select statement. + * + * A resultset object is the result of 'select' SQL Statement. + * + * It's a set of data (ordered in columns) that can be fetched row by row + * to get data returned by the SQL statement + * + */ + +typedef struct OCI_Resultset OCI_Resultset; + +/** + * @typedef OCI_Column + * + * @brief + * Oracle SQL Column and Type member representation. + * + * A column object represents an output column from a select statement + * + */ + +typedef struct OCI_Column OCI_Column; + +/** + * @typedef OCI_Lob + * + * @brief + * Oracle Internal Large objects: + * + * The following internal Larges Objects are supported: + * + * - BLOBs : Binary large objects + * - CLOBs / NCLOBs : Character large objects + * + * LOBs were introduced by OCI8 to replace Long data types. + * + * It's designed to store really larges objects (buffer, files) inside the database + * + * Oracle encourages programmers to use those objects instead of LONG, LONG RAW, ... + * + * OCILIB supports both LOBs and LONGs + * + */ + +typedef struct OCI_Lob OCI_Lob; + +/** + * @typedef OCI_File + * + * @brief + * Oracle External Large objects: + * + * The following external Larges Objects are supported: + * + * - BFILEs : Binary files + * - CFILEs : Character files + * + * FILEs were introduced by OCI8 in order to store references to files located outside the database. + * + * @warning + * Only Read-only access is allowed on BFILEs + * + * Two way to use FILEs : + * + * - within statement context (query, binding) + * - without statement context (server files reading) through OCI_File properties functions + * + */ + +typedef struct OCI_File OCI_File; + +/** + * @typedef OCI_Transaction + * + * @brief + * Oracle Transaction. + * + * A transaction can be: + * + * - Local: it's implicitly created by OCILIB + * - Global: it's explicitly created by the program + * + */ + +typedef struct OCI_Transaction OCI_Transaction; + +/** + * @typedef OCI_Long + * + * @brief Oracle Long data type. + * + * The following long Objects are supported: + * + * - LONG RAW : Binary long objects + * - LONG : Character long objects + * + * Those types were used in older versions of Oracle (before Oracle8i) to store + * large chunks of data in the database. + * + * It's now depreciated by Oracle that recommends using LOBs + * + * Many databases and applications are still designed to use LONGs that's why + * OCILIB supports Long Objects and piecewise operations + * + */ + +typedef struct OCI_Long OCI_Long; + +/** +* @typedef OCI_Number +* +* @brief +* Oracle NUMBER representation. +* +*/ +typedef struct OCI_Number OCI_Number; + +/** + * @typedef OCI_Date + * + * @brief + * Oracle internal date representation. + * + */ + +typedef struct OCI_Date OCI_Date; + +/** + * @typedef OCI_Timestamp + * + * @brief + * Oracle internal timestamp representation. + * + */ + +typedef struct OCI_Timestamp OCI_Timestamp; + +/** + * @typedef OCI_Interval + * + * @brief + * Oracle internal interval representation. + * + */ + +typedef struct OCI_Interval OCI_Interval; + +/** + * @typedef OCI_Object + * + * @brief + * Oracle Named types representation. + * + */ + +typedef struct OCI_Object OCI_Object; + +/** + * @typedef OCI_Coll + * + * @brief + * Oracle Collections (VARRAYs and Nested Tables) representation. + * + */ + +typedef struct OCI_Coll OCI_Coll; + +/** + * @typedef OCI_Elem + * + * @brief + * Oracle Collection item representation. + * + */ + +typedef struct OCI_Elem OCI_Elem; + +/** + * @typedef OCI_Iter + * + * @brief + * Oracle Collection iterator representation. + * + */ +typedef struct OCI_Iter OCI_Iter; + +/** + * @typedef OCI_TypeInfo + * + * @brief + * Type info metadata handle. + * + */ + +/** + * @typedef OCI_Ref + * + * @brief + * Oracle REF type representation. + * + */ + +typedef struct OCI_Ref OCI_Ref; + +/** + * @typedef OCI_TypeInfo + * + * @brief + * Type info meta data handle. + * + */ + +typedef struct OCI_TypeInfo OCI_TypeInfo; + +/** + * @typedef OCI_HashTable + * + * @brief + * OCILIB implementation of hash tables. + * + */ + +typedef struct OCI_HashTable OCI_HashTable; + +/** + * @typedef OCI_Error + * + * @brief + * Encapsulates an Oracle or OCILIB exception. + * + * The error object is used to raise internal or oracle errors. + * When an error occurs, if the application has provided an error handler, an + * error object is constructed and passed to the handler + * + */ + +typedef struct OCI_Error OCI_Error; + +/** + * @typedef OCI_Mutex + * + * @brief + * OCILIB encapsulation of OCI mutexes. + * + */ + +typedef struct OCI_Mutex OCI_Mutex; + +/** + * @typedef OCI_Thread + * + * @brief + * OCILIB encapsulation of OCI Threads. + * + */ + +typedef struct OCI_Thread OCI_Thread; + +/** + * @typedef OCI_DirPath + * + * @brief + * OCILIB encapsulation of OCI Direct Path handle. + * + */ + +typedef struct OCI_DirPath OCI_DirPath; + +/** + * @typedef OCI_Subscription + * + * @brief + * OCILIB encapsulation of Oracle DCN notification + * + */ + +typedef struct OCI_Subscription OCI_Subscription; + +/** + * @typedef OCI_Event + * + * @brief + * OCILIB encapsulation of Oracle DCN event + * + */ + +typedef struct OCI_Event OCI_Event; + +/** + * @typedef OCI_Msg + * + * @brief + * OCILIB encapsulation of A/Q message + * + */ + +typedef struct OCI_Msg OCI_Msg; + +/** + * @typedef OCI_Agent + * + * @brief + * OCILIB encapsulation of A/Q Agent + * + */ + +typedef struct OCI_Agent OCI_Agent; + +/** + * @typedef OCI_Dequeue + * + * @brief + * OCILIB encapsulation of A/Q dequeuing operations + * + */ + +typedef struct OCI_Dequeue OCI_Dequeue; + +/** + * @typedef OCI_Enqueue + * + * @brief + * OCILIB encapsulation of A/Q enqueuing operations + * + */ + +typedef struct OCI_Enqueue OCI_Enqueue; + +/** + * @var POCI_ERROR + * + * @brief + * Error procedure prototype + * + * @param err - Error handle + * + */ + +typedef void (*POCI_ERROR) +( + OCI_Error *err +); + +/** + * @var POCI_THREAD + * + * @brief + * Thread procedure prototype + * + * @param thread - Thread handle + * @param arg - Pointer passed to OCI_ThreadRun() + * + */ + +typedef void (*POCI_THREAD) +( + OCI_Thread *thread, + void *arg +); + +/** + * @var POCI_THREADKEYDEST + * + * @brief + * Thread key destructor prototype. + * + * @param data - Thread Key current pointer value + * + */ + +typedef void (*POCI_THREADKEYDEST) +( + void *data +); + +/** + * @var POCI_NOTIFY + * + * @brief + * Database Change Notification User callback prototype. + * + * @param event - Event handle + * + */ + +typedef void (*POCI_NOTIFY) +( + OCI_Event *event +); + +/** + * @var POCI_NOTIFY_AQ + * + * @brief + * AQ notification callback prototype. + * + * @param dequeue - dequeue handle + * + */ + +typedef void (*POCI_NOTIFY_AQ) +( + OCI_Dequeue *dequeue +); + +/** + * @var POCI_TAF_HANDLER + * + * @brief + * Failover Notification User callback prototype. + * + * @param con - Connection handle related to the event + * @param type - Event type + * @param event - Event code + * + * @note + * Possible values for parameter 'type' : + * - OCI_FOT_NONE + * - OCI_FOT_SESSION + * - OCI_FOT_SELECT + * + * @note + * Possible values for parameter 'event' : + * - OCI_FOE_END + * - OCI_FOE_ABORT + * - OCI_FOE_REAUTH + * - OCI_FOE_BEGIN + * - OCI_FOE_ERROR + * + * @return + * User callback should return one of the following value : + * - OCI_FOC_OK + * - OCI_FOC_RETRY + * + */ + +typedef unsigned int (*POCI_TAF_HANDLER) +( + OCI_Connection *con, + unsigned int type, + unsigned int event +); + +/** + * @var POCI_HA_HANDLER + * + * @brief + * HA (High Availability) events Notification User callback prototype. + * + * @param con - Connection handle related to the event + * @param source - source of the event + * @param event - type of the event + * @param time - Timestamp of the event + * + * @note + * Currently, Oracle only send HA down events + * + * @note + * Possible values for parameter 'source' : + * - OCI_HES_INSTANCE + * - OCI_HES_DATABASE + * - OCI_HES_NODE + * - OCI_HES_SERVICE + * - OCI_HES_SERVICE_MEMBER + * - OCI_HES_ASM_INSTANCE + * - OCI_HES_PRECONNECT + * + * @note + * Possible values for parameter 'event' : + * - OCI_HET_DOWN : HA event type down + * - OCI_HET_UP : HA event type up + * + */ + +typedef void (*POCI_HA_HANDLER) +( + OCI_Connection *con, + unsigned int source, + unsigned int event, + OCI_Timestamp *time +); + +/* public structures */ + +/** + * @typedef OCI_XID + * + * @brief + * Global transaction identifier + * + */ + +typedef struct OCI_XID { + long formatID; + long gtrid_length; + long bqual_length; + char data[128]; +} OCI_XID; + +/** + * @typedef OCI_Variant + * + * @brief + * Internal Variant type based on union C type. + * + * @note + * Helpful for generic buffer, it reduces the amount of casts + * + */ + +typedef union OCI_Variant { + /* integers */ + int num; + + /* raw data */ + unsigned char *p_bytes; + + /* pointer to c natives types */ + void *p_void; + int *p_int; + float *p_float; + double *p_double; + otext *p_text; + + /* ocilib object types */ + OCI_Date *p_date; + OCI_Interval *p_interval; + OCI_Timestamp *p_timestamp; + OCI_Long *p_long; + OCI_Lob *p_lob; + OCI_File *p_file; + OCI_Statement *p_stmt; + OCI_Column *p_col; + OCI_Object *p_obj; + OCI_Coll *p_coll; + OCI_Iter *p_iter; + OCI_Elem *p_elem; +} OCI_Variant; + +/** +* @typedef OCI_HashValue +* +* @brief +* Hash table entry value +* +* OCILIB implementation of hash tables uses chaining method for dealing with collisions +* +*/ + +typedef struct OCI_HashValue { + OCI_Variant value; + struct OCI_HashValue *next; +} OCI_HashValue; + +/** + * @typedef OCI_HashEntry + * + * @brief + * Hash table entry + * + */ + +typedef struct OCI_HashEntry { + otext *key; + struct OCI_HashValue *values; + struct OCI_HashEntry *next; +} OCI_HashEntry; + +/** + * @typedef big_int + * + * @brief + * big_int is a C scalar integer (32 or 64 bits) depending on compiler support for 64bits integers. + * big_uint is an unsigned big_int + * + */ + +/* check for long long support */ + +#if defined(_LONGLONG) || defined(LONG_LONG_MAX) || defined(LLONG_MAX) || defined(__LONG_LONG_MAX__) + +/* C99 long long supported */ + +typedef long long big_int; +typedef unsigned long long big_uint; + + #define OCI_BIG_UINT_ENABLED + +#elif defined(_WINDOWS) + +/* Microsoft extension supported */ + +typedef __int64 big_int; +typedef unsigned __int64 big_uint; + + #define OCI_BIG_UINT_ENABLED + +#else + +typedef int big_int; +typedef unsigned int big_uint; + +#endif + +/** + * @} + */ + +/* boolean values */ + +#ifndef TRUE + #define TRUE 1 + #define FALSE 0 +#endif + +#ifndef boolean + #define boolean int +#endif + +/* oracle OCI key versions*/ + +#define OCI_8_0 800 +#define OCI_8_1 810 +#define OCI_9_0 900 +#define OCI_9_2 920 +#define OCI_10_1 1010 +#define OCI_10_2 1020 +#define OCI_11_1 1110 +#define OCI_11_2 1120 +#define OCI_12_1 1210 +#define OCI_12_2 1220 + +/* versions extract macros */ + +#define OCI_VER_MAJ(v) (unsigned int) (v/100) +#define OCI_VER_MIN(v) (unsigned int) ((v/10) - ((v/100)*10)) +#define OCI_VER_REV(v) (unsigned int) ((v) - ((v/10)*10)) + +/* OCILIB Error types */ + +#define OCI_ERR_ORACLE 1 +#define OCI_ERR_OCILIB 2 +#define OCI_ERR_WARNING 3 + +/* OCILIB Error codes */ + +#define OCI_ERR_NONE 0 +#define OCI_ERR_NOT_INITIALIZED 1 +#define OCI_ERR_LOADING_SHARED_LIB 2 +#define OCI_ERR_LOADING_SYMBOLS 3 +#define OCI_ERR_MULTITHREADED 4 +#define OCI_ERR_MEMORY 5 +#define OCI_ERR_NOT_AVAILABLE 6 +#define OCI_ERR_NULL_POINTER 7 +#define OCI_ERR_DATATYPE_NOT_SUPPORTED 8 +#define OCI_ERR_PARSE_TOKEN 9 +#define OCI_ERR_MAP_ARGUMENT 10 +#define OCI_ERR_OUT_OF_BOUNDS 11 +#define OCI_ERR_UNFREED_DATA 12 +#define OCI_ERR_MAX_BIND 13 +#define OCI_ERR_ATTR_NOT_FOUND 14 +#define OCI_ERR_MIN_VALUE 15 +#define OCI_ERR_NOT_COMPATIBLE 16 +#define OCI_ERR_STMT_STATE 17 +#define OCI_ERR_STMT_NOT_SCROLLABLE 18 +#define OCI_ERR_BIND_ALREADY_USED 19 +#define OCI_ERR_BIND_ARRAY_SIZE 20 +#define OCI_ERR_COLUMN_NOT_FOUND 21 +#define OCI_ERR_DIRPATH_STATE 22 +#define OCI_ERR_CREATE_OCI_ENVIRONMENT 23 +#define OCI_ERR_REBIND_BAD_DATATYPE 24 +#define OCI_ERR_TYPEINFO_DATATYPE 25 +#define OCI_ERR_ITEM_NOT_FOUND 26 +#define OCI_ERR_ARG_INVALID_VALUE 27 +#define OCI_ERR_XA_ENV_FROM_STRING 28 +#define OCI_ERR_XA_CONN_FROM_STRING 29 + +#define OCI_ERR_COUNT 30 + + +/* allocated bytes types */ + +#define OCI_MEM_ORACLE 1 +#define OCI_MEM_OCILIB 2 +#define OCI_MEM_ALL OCI_MEM_ORACLE | OCI_MEM_OCILIB + +/* binding */ + +#define OCI_BIND_BY_POS 0 +#define OCI_BIND_BY_NAME 1 +#define OCI_BIND_SIZE 6 +#define OCI_BIND_MAX 65535 + +/* fetching */ + +#define OCI_FETCH_SIZE 20 +#define OCI_PREFETCH_SIZE 20 +#define OCI_LONG_EXPLICIT 1 +#define OCI_LONG_IMPLICIT 2 + +/* unknown value */ + +#define OCI_UNKNOWN 0 + +/* C Data Type mapping */ + +#define OCI_CDT_NUMERIC 1 +#define OCI_CDT_DATETIME 3 +#define OCI_CDT_TEXT 4 +#define OCI_CDT_LONG 5 +#define OCI_CDT_CURSOR 6 +#define OCI_CDT_LOB 7 +#define OCI_CDT_FILE 8 +#define OCI_CDT_TIMESTAMP 9 +#define OCI_CDT_INTERVAL 10 +#define OCI_CDT_RAW 11 +#define OCI_CDT_OBJECT 12 +#define OCI_CDT_COLLECTION 13 +#define OCI_CDT_REF 14 +#define OCI_CDT_BOOLEAN 15 + +/* Data Type codes for OCI_ImmediateXXX() calls */ + +#define OCI_ARG_SHORT 1 +#define OCI_ARG_USHORT 2 +#define OCI_ARG_INT 3 +#define OCI_ARG_UINT 4 +#define OCI_ARG_BIGINT 5 +#define OCI_ARG_BIGUINT 6 +#define OCI_ARG_DOUBLE 7 +#define OCI_ARG_DATETIME 8 +#define OCI_ARG_TEXT 9 +#define OCI_ARG_LOB 10 +#define OCI_ARG_FILE 11 +#define OCI_ARG_TIMESTAMP 12 +#define OCI_ARG_INTERVAL 13 +#define OCI_ARG_RAW 14 +#define OCI_ARG_OBJECT 15 +#define OCI_ARG_COLLECTION 16 +#define OCI_ARG_REF 17 +#define OCI_ARG_FLOAT 18 +#define OCI_ARG_NUMBER 19 + +/* statement types */ + +#define OCI_CST_SELECT 1 +#define OCI_CST_UPDATE 2 +#define OCI_CST_DELETE 3 +#define OCI_CST_INSERT 4 +#define OCI_CST_CREATE 5 +#define OCI_CST_DROP 6 +#define OCI_CST_ALTER 7 +#define OCI_CST_BEGIN 8 +#define OCI_CST_DECLARE 9 +#define OCI_CST_CALL 10 + +/* environment modes */ + +#define OCI_ENV_DEFAULT 0 +#define OCI_ENV_THREADED 1 +#define OCI_ENV_CONTEXT 2 +#define OCI_ENV_EVENTS 4 + +/* sessions modes */ + +#define OCI_SESSION_DEFAULT 0x00000000 /* any version */ +#define OCI_SESSION_SYSDBA 0x00000002 /* any version */ +#define OCI_SESSION_SYSOPER 0x00000004 /* any version */ +#define OCI_SESSION_SYSASM 0x00008000 /* From 11gR1 */ +#define OCI_SESSION_SYSBKP 0x00020000 /* From 12cR1 */ +#define OCI_SESSION_SYSDGD 0x00040000 /* From 12cR1 */ +#define OCI_SESSION_SYSKMT 0x00080000 /* From 12cR1 */ +#define OCI_SESSION_SYSRAC 0x00100000 /* From 12cR2 */ + +#define OCI_SESSION_XA 0x00000001 +#define OCI_SESSION_PRELIM_AUTH 0x00000008 + +/* change notification types */ + +#define OCI_CNT_OBJECTS 1 +#define OCI_CNT_ROWS 2 +#define OCI_CNT_DATABASES 4 +#define OCI_CNT_ALL OCI_CNT_OBJECTS | OCI_CNT_ROWS | OCI_CNT_DATABASES + +/* event notification types */ + +#define OCI_ENT_STARTUP 1 +#define OCI_ENT_SHUTDOWN 2 +#define OCI_ENT_SHUTDOWN_ANY 3 +#define OCI_ENT_DROP_DATABASE 4 +#define OCI_ENT_DEREGISTER 5 +#define OCI_ENT_OBJECT_CHANGED 6 + +/* event object notification types */ + +#define OCI_ONT_INSERT 0x2 +#define OCI_ONT_UPDATE 0x4 +#define OCI_ONT_DELETE 0x8 +#define OCI_ONT_ALTER 0x10 +#define OCI_ONT_DROP 0x20 +#define OCI_ONT_GENERIC 0x40 + +/* database startup modes */ + +#define OCI_DB_SPM_START 1 +#define OCI_DB_SPM_MOUNT 2 +#define OCI_DB_SPM_OPEN 4 +#define OCI_DB_SPM_FULL OCI_DB_SPM_START | OCI_DB_SPM_MOUNT | OCI_DB_SPM_OPEN + +/* database startup flags */ + +#define OCI_DB_SPF_DEFAULT 0 +#define OCI_DB_SPF_FORCE 1 +#define OCI_DB_SPF_RESTRICT 2 + +/* database shutdown modes */ + +#define OCI_DB_SDM_SHUTDOWN 1 +#define OCI_DB_SDM_CLOSE 2 +#define OCI_DB_SDM_DISMOUNT 4 +#define OCI_DB_SDM_FULL OCI_DB_SDM_SHUTDOWN | OCI_DB_SDM_CLOSE | OCI_DB_SDM_DISMOUNT + +/* database shutdown flags */ + +#define OCI_DB_SDF_DEFAULT 0 +#define OCI_DB_SDF_TRANS 1 +#define OCI_DB_SDF_TRANS_LOCAL 2 +#define OCI_DB_SDF_IMMEDIATE 3 +#define OCI_DB_SDF_ABORT 4 + +/* charset form types */ + +#define OCI_CSF_NONE 0 +#define OCI_CSF_DEFAULT 1 +#define OCI_CSF_NATIONAL 2 + +/* statement fetch mode */ + +#define OCI_SFM_DEFAULT 0 +#define OCI_SFM_SCROLLABLE 0x08 + +/* statement fetch direction */ + +#define OCI_SFD_ABSOLUTE 0x20 +#define OCI_SFD_RELATIVE 0x40 + +/* bind allocation mode */ + +#define OCI_BAM_EXTERNAL 1 +#define OCI_BAM_INTERNAL 2 + +/* bind direction mode */ + +#define OCI_BDM_IN 1 +#define OCI_BDM_OUT 2 +#define OCI_BDM_IN_OUT (OCI_BDM_IN | OCI_BDM_OUT) + +/* Column property flags */ + +#define OCI_CPF_NONE 0 +#define OCI_CPF_IS_IDENTITY 1 +#define OCI_CPF_IS_GEN_ALWAYS 2 +#define OCI_CPF_IS_GEN_BY_DEFAULT_ON_NULL 4 + +/* Column collation IDs */ + +#define OCI_CCI_NONE 0x00000000 +#define OCI_CCI_NLS_COMP 0x00003FFE +#define OCI_CCI_NLS_SORT 0x00003FFD +#define OCI_CCI_NLS_SORT_CI 0x00003FFC +#define OCI_CCI_NLS_SORT_AI 0x00003FFB +#define OCI_CCI_NLS_SORT_CS 0x00003FFA +#define OCI_CCI_NLS_SORT_VAR1 0x00003FF9 +#define OCI_CCI_NLS_SORT_VAR1_CI 0x00003FF8 +#define OCI_CCI_NLS_SORT_VAR1_AI 0x00003FF7 +#define OCI_CCI_NLS_SORT_VAR1_CS 0x00003FF6 +#define OCI_CCI_BINARY 0x00003FFF +#define OCI_CCI_BINARY_CI 0x00023FFF +#define OCI_CCI_BINARY_AI 0x00013FFF + + +/* Integer sign flag */ + +#define OCI_NUM_UNSIGNED 2 + +/* External Integer types */ + +#define OCI_NUM_SHORT 4 +#define OCI_NUM_INT 8 +#define OCI_NUM_BIGINT 16 +#define OCI_NUM_FLOAT 32 +#define OCI_NUM_DOUBLE 64 +#define OCI_NUM_NUMBER 128 + +#define OCI_NUM_USHORT (OCI_NUM_SHORT | OCI_NUM_UNSIGNED) +#define OCI_NUM_UINT (OCI_NUM_INT | OCI_NUM_UNSIGNED) +#define OCI_NUM_BIGUINT (OCI_NUM_BIGINT | OCI_NUM_UNSIGNED) + +/* timestamp types */ + +#define OCI_TIMESTAMP 1 +#define OCI_TIMESTAMP_TZ 2 +#define OCI_TIMESTAMP_LTZ 3 + +/* interval types */ + +#define OCI_INTERVAL_YM 1 +#define OCI_INTERVAL_DS 2 + +/* long types */ + +#define OCI_BLONG 1 +#define OCI_CLONG 2 + +/* lob types */ + +#define OCI_BLOB 1 +#define OCI_CLOB 2 +#define OCI_NCLOB 3 + +/* lob opening mode */ + +#define OCI_LOB_READONLY 1 +#define OCI_LOB_READWRITE 2 + +/* file types */ + +#define OCI_BFILE 1 +#define OCI_CFILE 2 + +/* lob browsing mode */ + +#define OCI_SEEK_SET 1 +#define OCI_SEEK_END 2 +#define OCI_SEEK_CUR 3 + +/* type info types */ + +#define OCI_TIF_TABLE 1 +#define OCI_TIF_VIEW 2 +#define OCI_TIF_TYPE 3 + +/* object type */ + +#define OCI_OBJ_PERSISTENT 1 +#define OCI_OBJ_TRANSIENT 2 +#define OCI_OBJ_VALUE 3 + +/* collection types */ + +#define OCI_COLL_VARRAY 1 +#define OCI_COLL_NESTED_TABLE 2 +#define OCI_COLL_INDEXED_TABLE 3 + +/* pool types */ + +#define OCI_POOL_CONNECTION 1 +#define OCI_POOL_SESSION 2 + +/* AQ message state */ + +#define OCI_AMS_READY 1 +#define OCI_AMS_WAITING 2 +#define OCI_AMS_PROCESSED 3 +#define OCI_AMS_EXPIRED 4 + +/* AQ sequence deviation */ + +#define OCI_ASD_BEFORE 2 +#define OCI_ASD_TOP 3 + +/* AQ message visibility */ + +#define OCI_AMV_IMMEDIATE 1 +#define OCI_AMV_ON_COMMIT 2 + +/* AQ dequeue mode */ + +#define OCI_ADM_BROWSE 1 +#define OCI_ADM_LOCKED 2 +#define OCI_ADM_REMOVE 3 +#define OCI_ADM_REMOVE_NODATA 4 + +/* AQ dequeue navigation */ + +#define OCI_ADN_FIRST_MSG 1 +#define OCI_ADN_NEXT_TRANSACTION 2 +#define OCI_ADN_NEXT_MSG 3 + +/* AQ queue table purge mode */ + +#define OCI_APM_BUFFERED 1 +#define OCI_APM_PERSISTENT 2 +#define OCI_APM_ALL (OCI_APM_BUFFERED | OCI_APM_PERSISTENT) + +/* AQ queue table grouping mode */ + +#define OCI_AGM_NONE 0 +#define OCI_AGM_TRANSACTIONNAL 1 + +/* AQ queue table type */ + +#define OCI_AQT_NORMAL 0 +#define OCI_AQT_EXCEPTION 1 +#define OCI_AQT_NON_PERSISTENT 2 + +/* direct path processing return status */ + +#define OCI_DPR_COMPLETE 1 +#define OCI_DPR_ERROR 2 +#define OCI_DPR_FULL 3 +#define OCI_DPR_PARTIAL 4 +#define OCI_DPR_EMPTY 5 + +/* direct path conversion modes */ + +#define OCI_DCM_DEFAULT 1 +#define OCI_DCM_FORCE 2 + +/* trace size constants */ + +#define OCI_SIZE_TRACE_ID 64 +#define OCI_SIZE_TRACE_MODULE 48 +#define OCI_SIZE_TRACE_ACTION 32 +#define OCI_SIZE_TRACE_INFO 64 + +/* trace types */ + +#define OCI_TRC_IDENTITY 1 +#define OCI_TRC_MODULE 2 +#define OCI_TRC_ACTION 3 +#define OCI_TRC_DETAIL 4 + +/* HA event type */ + +#define OCI_HET_DOWN 0 +#define OCI_HET_UP 1 + +/* HA event source */ +#define OCI_HES_INSTANCE 0 +#define OCI_HES_DATABASE 1 +#define OCI_HES_NODE 2 +#define OCI_HES_SERVICE 3 +#define OCI_HES_SERVICE_MEMBER 4 +#define OCI_HES_ASM_INSTANCE 5 +#define OCI_HES_PRECONNECT 6 + +/* Fail over types */ + +#define OCI_FOT_NONE 1 +#define OCI_FOT_SESSION 2 +#define OCI_FOT_SELECT 4 + +/* fail over notifications */ + +#define OCI_FOE_END 1 +#define OCI_FOE_ABORT 2 +#define OCI_FOE_REAUTH 4 +#define OCI_FOE_BEGIN 8 +#define OCI_FOE_ERROR 16 + +/* fail over callback return code */ + +#define OCI_FOC_OK 0 +#define OCI_FOC_RETRY 25410 + +/* hash tables support */ + +#define OCI_HASH_STRING 1 +#define OCI_HASH_INTEGER 2 +#define OCI_HASH_POINTER 3 + +/* transaction types */ + +#define OCI_TRS_NEW 0x00000001 +#define OCI_TRS_READONLY 0x00000100 +#define OCI_TRS_READWRITE 0x00000200 +#define OCI_TRS_SERIALIZABLE 0x00000400 +#define OCI_TRS_LOOSE 0x00010000 +#define OCI_TRS_TIGHT 0x00020000 + +/* format types */ + +#define OCI_FMT_DATE 1 +#define OCI_FMT_TIMESTAMP 2 +#define OCI_FMT_NUMERIC 3 +#define OCI_FMT_BINARY_DOUBLE 4 +#define OCI_FMT_BINARY_FLOAT 5 + +/* sql function codes */ + +#define OCI_SFC_CREATE_TABLE 1 +#define OCI_SFC_SET_ROLE 2 +#define OCI_SFC_INSERT 3 +#define OCI_SFC_SELECT 4 +#define OCI_SFC_UPDATE 5 +#define OCI_SFC_DROP_ROLE 6 +#define OCI_SFC_DROP_VIEW 7 +#define OCI_SFC_DROP_TABLE 8 +#define OCI_SFC_DELETE 9 +#define OCI_SFC_CREATE_VIEW 10 +#define OCI_SFC_DROP_USER 11 +#define OCI_SFC_CREATE_ROLE 12 +#define OCI_SFC_CREATE_SEQUENCE 13 +#define OCI_SFC_ALTER_SEQUENCE 14 + +#define OCI_SFC_DROP_SEQUENCE 16 +#define OCI_SFC_CREATE_SCHEMA 17 +#define OCI_SFC_CREATE_CLUSTER 18 +#define OCI_SFC_CREATE_USER 19 +#define OCI_SFC_CREATE_INDEX 20 +#define OCI_SFC_DROP_INDEX 21 +#define OCI_SFC_DROP_CLUSTER 22 +#define OCI_SFC_VALIDATE_INDEX 23 +#define OCI_SFC_CREATE_PROCEDURE 24 +#define OCI_SFC_ALTER_PROCEDURE 25 +#define OCI_SFC_ALTER_TABLE 26 +#define OCI_SFC_EXPLAIN 27 +#define OCI_SFC_GRANT 28 +#define OCI_SFC_REVOKE 29 +#define OCI_SFC_CREATE_SYNONYM 30 +#define OCI_SFC_DROP_SYNONYM 31 +#define OCI_SFC_ALTER_SYSTEM_SWITCHLOG 32 +#define OCI_SFC_SET_TRANSACTION 33 +#define OCI_SFC_PLSQL_EXECUTE 34 +#define OCI_SFC_LOCK 35 +#define OCI_SFC_NOOP 36 +#define OCI_SFC_RENAME 37 +#define OCI_SFC_COMMENT 38 +#define OCI_SFC_AUDIT 39 +#define OCI_SFC_NO_AUDIT 40 +#define OCI_SFC_ALTER_INDEX 41 +#define OCI_SFC_CREATE_EXTERNAL_DATABASE 42 +#define OCI_SFC_DROP_EXTERNALDATABASE 43 +#define OCI_SFC_CREATE_DATABASE 44 +#define OCI_SFC_ALTER_DATABASE 45 +#define OCI_SFC_CREATE_ROLLBACK_SEGMENT 46 +#define OCI_SFC_ALTER_ROLLBACK_SEGMENT 47 +#define OCI_SFC_DROP_ROLLBACK_SEGMENT 48 +#define OCI_SFC_CREATE_TABLESPACE 49 +#define OCI_SFC_ALTER_TABLESPACE 50 +#define OCI_SFC_DROP_TABLESPACE 51 +#define OCI_SFC_ALTER_SESSION 52 +#define OCI_SFC_ALTER_USER 53 +#define OCI_SFC_COMMIT_WORK 54 +#define OCI_SFC_ROLLBACK 55 +#define OCI_SFC_SAVEPOINT 56 +#define OCI_SFC_CREATE_CONTROL_FILE 57 +#define OCI_SFC_ALTER_TRACING 58 +#define OCI_SFC_CREATE_TRIGGER 59 +#define OCI_SFC_ALTER_TRIGGER 60 +#define OCI_SFC_DROP_TRIGGER 61 +#define OCI_SFC_ANALYZE_TABLE 62 +#define OCI_SFC_ANALYZE_INDEX 63 +#define OCI_SFC_ANALYZE_CLUSTER 64 +#define OCI_SFC_CREATE_PROFILE 65 +#define OCI_SFC_DROP_PROFILE 66 +#define OCI_SFC_ALTER_PROFILE 67 +#define OCI_SFC_DROP_PROCEDURE 68 + +#define OCI_SFC_ALTER_RESOURCE_COST 70 +#define OCI_SFC_CREATE_SNAPSHOT_LOG 71 +#define OCI_SFC_ALTER_SNAPSHOT_LOG 72 +#define OCI_SFC_DROP_SNAPSHOT_LOG 73 +#define OCI_SFC_DROP_SUMMARY 73 +#define OCI_SFC_CREATE_SNAPSHOT 74 +#define OCI_SFC_ALTER_SNAPSHOT 75 +#define OCI_SFC_DROP_SNAPSHOT 76 +#define OCI_SFC_CREATE_TYPE 77 +#define OCI_SFC_DROP_TYPE 78 +#define OCI_SFC_ALTER_ROLE 79 +#define OCI_SFC_ALTER_TYPE 80 +#define OCI_SFC_CREATE_TYPE_BODY 81 +#define OCI_SFC_ALTER_TYPE_BODY 82 +#define OCI_SFC_DROP_TYPE_BODY 83 +#define OCI_SFC_DROP_LIBRARY 84 +#define OCI_SFC_TRUNCATE_TABLE 85 +#define OCI_SFC_TRUNCATE_CLUSTER 86 +#define OCI_SFC_CREATE_BITMAPFILE 87 +#define OCI_SFC_ALTER_VIEW 88 +#define OCI_SFC_DROP_BITMAPFILE 89 +#define OCI_SFC_SET_CONSTRAINTS 90 +#define OCI_SFC_CREATE_FUNCTION 91 +#define OCI_SFC_ALTER_FUNCTION 92 +#define OCI_SFC_DROP_FUNCTION 93 +#define OCI_SFC_CREATE_PACKAGE 94 +#define OCI_SFC_ALTER_PACKAGE 95 +#define OCI_SFC_DROP_PACKAGE 96 +#define OCI_SFC_CREATE_PACKAGE_BODY 97 +#define OCI_SFC_ALTER_PACKAGE_BODY 98 +#define OCI_SFC_DROP_PACKAGE_BODY 99 +#define OCI_SFC_CREATE_DIRECTORY 157 +#define OCI_SFC_DROP_DIRECTORY 158 +#define OCI_SFC_CREATE_LIBRARY 159 +#define OCI_SFC_CREATE_JAVA 160 +#define OCI_SFC_ALTER_JAVA 161 +#define OCI_SFC_DROP_JAVA 162 +#define OCI_SFC_CREATE_OPERATOR 163 +#define OCI_SFC_CREATE_INDEXTYPE 164 +#define OCI_SFC_DROP_INDEXTYPE 165 +#define OCI_SFC_ALTER_INDEXTYPE 166 +#define OCI_SFC_DROP_OPERATOR 167 +#define OCI_SFC_ASSOCIATE_STATISTICS 168 +#define OCI_SFC_DISASSOCIATE_STATISTICS 169 +#define OCI_SFC_CALL_METHOD 170 +#define OCI_SFC_CREATE_SUMMARY 171 +#define OCI_SFC_ALTER_SUMMARY 172 +#define OCI_SFC_CREATE_DIMENSION 174 +#define OCI_SFC_ALTER_DIMENSION 175 +#define OCI_SFC_DROP_DIMENSION 176 +#define OCI_SFC_CREATE_CONTEXT 177 +#define OCI_SFC_DROP_CONTEXT 178 +#define OCI_SFC_ALTER_OUTLINE 179 +#define OCI_SFC_CREATE_OUTLINE 180 +#define OCI_SFC_DROP_OUTLINE 181 +#define OCI_SFC_UPDATE_INDEXES 182 +#define OCI_SFC_ALTER_OPERATOR 183 + +/* size constants */ + +#define OCI_SIZE_FORMAT 64 +#define OCI_SIZE_BUFFER 512 +#define OCI_SIZE_LONG (64*1024)-1 +#define OCI_SIZE_DATE 45 +#define OCI_SIZE_TIMESTAMP 54 +#define OCI_SIZE_FORMAT_TODATE 14 +#define OCI_SIZE_NULL 4 +#define OCI_SIZE_PRECISION 10 +#define OCI_SIZE_ROWID 23 +#define OCI_SIZE_DIRECTORY 30 +#define OCI_SIZE_FILENAME 255 +#define OCI_SIZE_FORMAT_NUMS 40 +#define OCI_SIZE_FORMAT_NUML 65 +#define OCI_SIZE_OBJ_NAME 128 + +#define OCI_HASH_DEFAULT_SIZE 256 + +/* string constants */ + +#define OCILIB_DRIVER_NAME OTEXT("OCILIB") +#define OCI_STRING_NULL OTEXT("NULL") +#define OCI_STRING_EMPTY OTEXT("") +#define OCI_STRING_FORMAT_DATE OTEXT("YYYY-MM-DD") +#define OCI_STRING_FORMAT_TIME OTEXT("HH24:MI:SS") +#define OCI_STRING_FORMAT_DATETIME OTEXT("YYYY-MM-DD HH24:MI:SS") +#define OCI_STRING_FORMAT_TIMESTAMP OTEXT("YYYY-MM-DD HH24:MI:SS.FF") +#define OCI_STRING_DEFAULT_PREC 3 +#define OCI_STRING_FORMAT_NUM \ + OTEXT("FM99999999999999999999999999999999999990.999999999999999999999999") +#define OCI_STRING_FORMAT_NUM_BDOUBLE OTEXT("%lf") +#define OCI_STRING_FORMAT_NUM_BFLOAT OTEXT("%f") +#define OCI_STRING_FORMAT_NUM_SHORT OTEXT("%hd") +#define OCI_STRING_FORMAT_NUM_INT OTEXT("%d") +#define OCI_STRING_TRUE OTEXT("TRUE") +#define OCI_STRING_FALSE OTEXT("FALSE") +#define OCI_STRING_TRUE_SIZE 4 +#define OCI_STRING_FALSE_SIZE 5 + +#ifdef _WINDOWS + #define OCI_CHAR_SLASH '\\' +#else + #define OCI_CHAR_SLASH '/' +#endif + +/** + * @defgroup OcilibCApiInitialization Initializing the library + * @{ + * + * To use OCILIB, it first needs to be initialized through a call to OCI_Initialize(). + * + * Then, the application connects to server, executes queries... + * + * Finally, OCILIB resources must be released by OCI_Cleanup() + * + * @note + * + * The following objects are automatically freed by the library: + * - Connections + * - pools + * - Statements + * - Type info objects + * - Thread keys + * + * @warning + * + * All other standalone object instances (mutexes, threads, dates, lobs, ...) ARE NOT freed. + * + */ + +/** + * @brief + * Initialize the library + * + * @param err_handler - Pointer to error handler procedure (optional) + * @param lib_path - Oracle shared library path (optional) + * @param mode - Environment mode + * + * Possible values for parameter mode: + * - OCI_ENV_DEFAULT : default mode + * - OCI_ENV_THREADED : multi-threading support + * - OCI_ENV_CONTEXT : thread contextual error handling + * - OCI_ENV_EVENTS : enables events for subscription, HA Events, AQ notifications + * + * @note + * This function must be called before any OCILIB library function. + * + * @warning + * - The parameter 'libpath' is only used if OCILIB has been built with the option OCI_IMPORT_RUNTIME + * - If the parameter 'lib_path' is NULL, the Oracle library is loaded from system environment variables + * + * @warning + * OCI_Initialize() should be called ONCE per application + * + * @return + * TRUE on success otherwise FALSE (only with Oracle runtime loading mode + * if the oracle shared libraries can't be loaded or if OCI subsystem cannot be initialized) + * + */ + +OCI_EXPORT boolean OCI_API OCI_Initialize +( + POCI_ERROR err_handler, + const otext *lib_path, + unsigned int mode +); + +/** + * @brief + * Clean up all resources allocated by the library + * + * @note + * * This function must be the last OCILIB library function call. + * - It deallocates objects not explicitly freed by the program (connections, statements, ...) + * - It unloads the Oracle shared library if it has been dynamically loaded + * + * @warning + * OCI_Cleanup() should be called ONCE per application + * + * @return TRUE + */ + +OCI_EXPORT boolean OCI_API OCI_Cleanup +( + void +); + +/** + * @brief + * Return the version of OCI used for compilation + * + * @note + * - with linkage build option, the version is determined from the oci.h header through different ways + * - with runtime loading build option, the version is set to the highest version + * of OCI needed by OCILIB, not necessarily the real OCI version + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetOCICompileVersion +( + void +); + +/** + * @brief + * Return the version of OCI used at runtime + * + * @note + * - with linkage build option, the version is determined from the oci.h header + * through different ways + * - with runtime loading build option, the version determined from the symbols + * dynamically loaded. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetOCIRuntimeVersion +( + void +); + +/** + * @brief + * Return the Oracle shared library import mode + * + * @note + * Possible values are: + * - OCI_IMPORT_MODE_LINKAGE + * - OCI_IMPORT_MODE_RUNTIME + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetImportMode +( + void +); + +/** + * @brief + * Return the OCILIB charset type + * + * @note + * Possible values are: + * - OCI_CHAR_ANSI + * - OCI_CHAR_WIDE + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetCharset +( + void +); + +/** +* @brief +* Return the current number of bytes allocated internally in the library +* +* @param mem_type : type of memory to request +* +* @note +* Possible values are: +* - OCI_MEM_ORACLE : bytes allocated by Oracle client library +* - OCI_MEM_OCILIB : bytes allocated by OCILIB library +* - OCI_MEM_ORACLE : bytes allocated by all libraries +* +*/ + +OCI_EXPORT big_uint OCI_API OCI_GetAllocatedBytes +( + unsigned int mem_type +); + +/** + * @brief + * Enable or disable Oracle warning notifications + * + * @param value - enable/disable warnings + * + * @note + * Default value is FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnableWarnings +( + boolean value +); + +/** + * @brief + * Set the global error user handler + * + * @param handler - Pointer to error handler procedure + * + * @note + * Use this call to change or remove the user callback error handler installed by OCI_Initialize() + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetErrorHandler +( + POCI_ERROR handler +); + +/** + * @brief + * Set the High availability (HA) user handler + * + * @param handler - Pointer to HA handler procedure + * + * @note + * See POCI_HA_HANDLER documentation for more details + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * HA events + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns FALSE without throwing any exception. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetHAHandler +( + POCI_HA_HANDLER handler +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiErrorHandling Error handling + * @{ + * + * OCILIB provides two mechanisms for error handling: + * + * - Global error handling through callbacks. + * - Contextual thread error handling + * + * Exceptions are raised: + * + * - On Oracle OCI API call error + * - On Oracle SQL statement error + * - On Internal OCILIB error (type checking, memory allocations ...) + * - On Oracle warnings (OCI API or SQL) + * + * If an error handler was provided to OCI_Initialize(), when an error occurs, the + * library generates an OCI_Error handle and pass it to the error handler. + * + * In order to use the thread contextual error handling, you must call + * OCI_Initialize() with the flag OCI_ENV_CONTEXT for the mode parameter. When + * activated, error handles are stored per thread and the last error within a + * thread can be retrieved with OCI_GetLastError() + * + * Exception properties are accessible through a set of functions + * + * @note + * The two ways to handle errors are not exclusive and can be mixed. + * + * @note + * Thread contextual error is also available for single thread based applications + * + * @par Oracle Warnings + * + * Oracle warnings are raised through OCI_Error API. + * Such error handles have their error type property (OCI_ErrorGetType()) set to OCI_ERR_WARNING. + * Warning handing is disabled by default. To activate/deactivate it, use OCI_EnableWarnings() + * + * @par Example with callbacks + * @include err.c + * + * @par Example with thread context + * @include err_ctx.c + * + *@par Example of warning handling + * @include err_warning.c + * + */ + +/** + * @brief + * Retrieve the last error or warning occurred within the last OCILIB call + * + * @note + * OCI_GetLastError() is based on thread context and thus OCILIB must be + * initialized with the flag OCI_ENV_CONTEXT + * + * @warning + * OCILIB functions that returns a boolean value to indicate their success : + * - return TRUE if no error occurred OR if a warning occurred + * - return FALSE if an error occurred + * + */ + +OCI_EXPORT OCI_Error * OCI_API OCI_GetLastError +( + void +); + +/** + * @brief + * Retrieve error message from error handle + * + * @param err - Error handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ErrorGetString +( + OCI_Error *err +); + +/** + * @brief + * Retrieve the type of error from error handle + * + * @param err - Error handle + * + * @note + * Returns one of the following values: + * + * - OCI_ERR_ORACLE + * - OCI_ERR_OCILIB + * - OCI_ERR_WARNING + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ErrorGetType +( + OCI_Error *err +); + +/** + * @brief + * Retrieve Oracle Error code from error handle + * + * @param err - Error handle + * + */ + +OCI_EXPORT int OCI_API OCI_ErrorGetOCICode +( + OCI_Error *err +); + +/** + * @brief + * Retrieve Internal Error code from error handle + * + * @param err - Error handle + * + */ + +OCI_EXPORT int OCI_API OCI_ErrorGetInternalCode +( + OCI_Error *err +); + +/** + * @brief + * Retrieve connection handle within the error occurred + * + * @param err - Error handle + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_ErrorGetConnection +( + OCI_Error *err +); + +/** + * @brief + * Retrieve statement handle within the error occurred + * + * @param err - Error handle + * + * @note + * If the error occurred outside of a statement context, it returns NULL + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_ErrorGetStatement +( + OCI_Error *err +); + +/** + * @brief + * Return the row index which caused an error during statement execution + * + * @param err - Error handle + * + * @warning + * Row index start at 1. + * + * @return + * 0 is the error is not related to array DML otherwise the index of the given + * row which caused the error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ErrorGetRow +( + OCI_Error *err +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiConnections Connecting to Database + * @{ + * + * Connecting to a database server is done with one call to OCI_ConnectionCreate(). + * + * OCI_ConnectionFree() closes the established connection. + * + * Connection properties are accessible through a set of functions + * + * @par Example + * @include conn.c + * + */ + +/** + * @brief + * Create a physical connection to an Oracle database server + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param mode - Session mode + * + * Possible values for parameter mode : + * - OCI_SESSION_DEFAULT + * - OCI_SESSION_SYSDBA + * - OCI_SESSION_SYSOPER + * - OCI_SESSION_XA + * + * @note + * External credentials are supported by supplying a null value for the + * 'user' and 'pwd' parameters. + * If the param 'db' is NULL then a connection to the default local DB is done + * + * @note + * For parameter 'mode', the possible values are exclusive and cannot be combined + * + * @par Oracle XA support + * + * OCILIB supports Oracle XA connectivity. In order to get a connection using + * the XA interface : + * - For parameter 'db' : pass the value of the 'DB' parameter of the given + * XA connection string passed to the Transaction Processing Monitor (TPM) + * - Pass NULL to the 'user' and 'pwd' parameters + * - Pass the value OCI_SESSION_XA to parameter 'mode' + * + * @par Oracle XA Connection String + * + * The XA connection string used in a transaction monitor to connect to Oracle must + * be compatible with OCILIB : + * + * - the XA parameter 'Objects' MUST be set to 'true' + * - If OCI_ENV_THREADED is passed to OCI_Initialize(), the XA parameter 'Threads' must + * be set to 'true', otherwise to 'false' + * - If OCI_ENV_EVENTS is passed to OCI_Initialize(), the XA parameter 'Events' must + * be set to 'true', otherwise to 'false' + * - As Oracle does not support Unicode UTF16 character set through the XA interface, + * Only OCI_CHARSET_ANSI builds of OCILIB can be used + * - You still can use UTF8 if the NLS_LANG environment variable is set with a valid + * UTF8 NLS value + * - DO NOT USE OCI_CHARSET_WIDE OCILIB builds with XA connections + * + * @note + * On success, a local transaction is automatically created and started ONLY for regular + * standalone connections and connections retrieved from connection pools. + * No transaction is created for a XA connection or q connection retrieved from session pools. + * + * @return + * Connection handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_ConnectionCreate +( + const otext *db, + const otext *user, + const otext *pwd, + unsigned int mode +); + +/** + * @brief + * Close a physical connection to an Oracle database server + * + * @param con - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ConnectionFree +( + OCI_Connection *con +); + +/** + * @brief + * Returns TRUE is the given connection is still connected otherwise FALSE + * + * @param con - Connection handle + * + */ + +OCI_EXPORT boolean OCI_API OCI_IsConnected +( + OCI_Connection *con +); + +/** + * @brief + * Return the pointer to user data previously associated with the connection + * + * @param con - Connection handle + * + */ + +OCI_EXPORT void * OCI_API OCI_GetUserData +( + OCI_Connection *con +); + +/** + * @brief + * Associate a pointer to user data to the given connection + * + * @param con - Connection handle + * @param data - User data pointer + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetUserData +( + OCI_Connection *con, + void *data +); + +/** + * @brief + * Associate a tag to the given connection/session + * + * @param con - Connection handle + * @param tag - user tag string + * + * @note + * Use this call only for connections retrieved from a session pool + * See OCI_PoolGetConnection() for more details + * + * @note + * To untag a session, call OCI_SetSessionTag() with 'tag' parameter set to NULL + * + * @warning + * No error is raised if the connection is a standalone connection or retrieved from a connection + * pool + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetSessionTag +( + OCI_Connection *con, + const otext *tag +); + +/** + * @brief + * Return the tag associated the given connection + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetSessionTag +( + OCI_Connection *con +); + +/** + * @brief + * Return the name of the connected database/service name + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetDatabase +( + OCI_Connection *con +); + +/** + * @brief + * Return the current logged user name + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetUserName +( + OCI_Connection *con +); + +/** + * @brief + * Return the current logged user password + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetPassword +( + OCI_Connection *con +); + +/** + * @brief + * Change the password of the logged user + * + * @param con - Connection handle + * @param password - New password + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetPassword +( + OCI_Connection *con, + const otext *password +); + +/** + * @brief + * Change the password of the given user on the given database + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param new_pwd - Oracle User New password + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetUserPassword +( + const otext *db, + const otext *user, + const otext *pwd, + const otext *new_pwd +); + +/** + * @brief + * Return the current session mode + * + * @param con - Connection handle + * + * @note + * See OCI_ConnectionCreate() for possible values + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetSessionMode +( + OCI_Connection *con +); + +/** + * @brief + * Return the connected database server version + * + * @param con - Connection handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetVersionServer +( + OCI_Connection *con +); + +/** + * @brief + * Return the major version number of the connected database server + * + * @param con - Connection handle + * + * @return + * Version number or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetServerMajorVersion +( + OCI_Connection *con +); + +/** + * @brief + * Return the minor version number of the connected database server + * + * @param con - Connection handle + * + * @return + * Version number or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetServerMinorVersion +( + OCI_Connection *con +); + +/** + * @brief + * Return the revision version number of the connected database server + * + * @param con - Connection handle + * + * @return + * Version number or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetServerRevisionVersion +( + OCI_Connection *con +); + +/** + * @brief + * Set the format string for implicit string conversions of the given type + * + * @param con - Connection handle (optional) + * @param type - Type of format + * @param format - Format string + * + * Formats can set at 2 levels: + * - Library level: by passing a NULL Connection handle + * - Connection level: by passing a valid Connection handle + * + * When the library needs to perform a string conversion, it search for a valid format using the + * following order: + * - Connection format + * - Library format + * - Default format + * + * @note + * Possible values of parameter 'type' : + * + * - OCI_FMT_DATE : format used to convert DATE to string + * - OCI_FMT_TIMESTAMP : format used to convert TIMESTAMP to string + * - OCI_FMT_NUMERIC : format used to convert numeric types to string + * - OCI_FMT_BINARY_DOUBLE : format used to convert BINARY_DOUBLE to string + * - OCI_FMT_BINARY FLOAT : format used to convert BINARY_FLOAT to string + * + * @note + * Default format values are : + * - OCI_FMT_DATE : constant OCI_STRING_FORMAT_DATE + * - OCI_FMT_TIMESTAMP : constant OCI_STRING_FORMAT_TIMESTAMP + * - OCI_FMT_NUMERIC : constant OCI_STRING_FORMAT_NUMERIC + * - OCI_FMT_BINARY_DOUBLE : constant OCI_STRING_FORMAT_BINARY_DOUBLE + * - OCI_FMT_BINARY FLOAT : constant OCI_STRING_FORMAT_BINARY_FLOAT + * + * @note + * Conversions are performed by Oracle built-in functions whenever possible. + * For DATE, TIMESTAMP and numeric types, see documentation of Oracle SQL to_char() function for more details + * For BINARY_DOUBLE and BINARY_FLOAT, refer to the C Standard Library printf() family documentation + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetFormat +( + OCI_Connection *con, + unsigned int type, + const otext *format +); + +/** + * @brief + * Return the format string for implicit string conversions of the given type + * + * @param con - Connection handle + * @param type - Type of format + * + * @note + * See OCI_SetFormat() for possible values + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetFormat +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Return the current transaction of the connection + * + * @param con - Connection handle + * + * @note + * From v3.9.4, no more default transaction object is created for a new connection + * + */ + +OCI_EXPORT OCI_Transaction * OCI_API OCI_GetTransaction +( + OCI_Connection *con +); + +/** + * @brief + * Set a transaction to a connection + * + * @param con - Connection handle + * @param trans - Transaction handle to assign + * + * @note + * The current transaction (if any) is automatically stopped but the newly assigned is not + * started or resumed + * + * @warning + * Do not set transaction object to XA connection or connection retrieved from a session pool + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetTransaction +( + OCI_Connection *con, + OCI_Transaction *trans +); + +/** + * @brief + * Return the highest Oracle version is supported by the connection + * + * @param con - connection handle + * + * @note + * The highest supported version is the lower version between client and server: + * + * @note + * Returns one of the following values: + * + * - OCI_UNKNOWN + * - OCI_8_0 + * - OCI_8_1 + * - OCI_9_0 + * - OCI_9_2 + * - OCI_10_1 + * - OCI_10_2 + * - OCI_11_1 + * - OCI_11_2 + * - OCI_12_1 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetVersionConnection +( + OCI_Connection *con +); + +/** + * @brief + * Set tracing information to the session of the given connection + * + * @param con - connection handle + * @param trace - trace type + * @param value - trace content + * + * Store current trace information to the given connection handle. + * These information: + * + * - is stored in the system view V$SESSION + * - can be retrieved from the connection property of an OCI_Error handle + * + * @note + * Possible values of parameter 'trace' : + * + * - OCI_TRC_IDENTITY : Specifies the user defined identifier in the session. + * It's recorded in the column CLIENT_IDENTIFIER of the + * system view V$SESSION + * - OCI_TRC_MODULE : name of the current module in the client application. + * It's recorded in the column MODULE of the + * system view V$SESSION + * - OCI_TRC_ACTION : name of the current action within the current module. + * It's recorded in the column ACTION of the + * system view V$SESSION + * - OCI_TRC_DETAIL : Client application additional information. + * It's recorded in the column CLIENT_INFO of the + * system view V$SESSION + * + * @warning + * The system view V$SESSION is updated on Oracle versions >= 10g + * + * @warning + * Oracle limits the size of these traces content and thus OCILIB will truncate + * the given values if needed : + * + * - OCI_TRC_IDENTITY : 64 bytes + * - OCI_TRC_MODULE : 48 bytes + * - OCI_TRC_ACTION : 32 bytes + * - OCI_TRC_DETAIL : 64 bytes + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetTrace +( + OCI_Connection *con, + unsigned int trace, + const otext *value +); + +/** + * @brief + * Get the current trace for the trace type from the given connection. + * + * @param con - connection handle + * @param trace - trace type + * + * @note + * See OCI_SetTrace() for more details. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetTrace +( + OCI_Connection *con, + unsigned int trace +); + +/** + * @brief + * Makes a round trip call to the server to confirm that the connection and the server are active. + * + * @param con - Connection handle + * + * @note + * Returns TRUE is the connection is still alive otherwise FALSE + * + * @warning + * This call is supported from Oracle 10g. + * For previous versions, it returns FALSE without throwing any exception. + * + */ + +OCI_EXPORT boolean OCI_API OCI_Ping +( + OCI_Connection *con +); + +/** + * @brief + * Return the Oracle server database name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetDBName +( + OCI_Connection *con +); + +/** + * @brief + * Return the Oracle server Instance name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetInstanceName +( + OCI_Connection *con +); + + +/** + * @brief + * Return the Oracle server service name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetServiceName +( + OCI_Connection *con +); + + +/** + * @brief + * Return the Oracle server machine name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetServerName +( + OCI_Connection *con +); + + +/** + * @brief + * Return the Oracle server domain name of the connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetDomainName +( + OCI_Connection *con +); + + +/** + * @brief + * Return the date and time (Timestamp) server instance start of the + * connected database/service name + * + * @param con - Connection handle + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns NULL without throwing any exception. + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_GetInstanceStartTime +( + OCI_Connection *con +); + +/** + * @brief + * Verify if the given connection support TAF events + * + * @param con - Connection handle + * + * @note + * Returns TRUE is the connection supports TAF event otherwise FALSE + * + * @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns FALSE without throwing any exception. + * + */ + +OCI_EXPORT boolean OCI_API OCI_IsTAFCapable +( + OCI_Connection *con +); + +/** + * @brief + * Set the Transparent Application Failover (TAF) user handler + * + * @param con - Connection handle + * @param handler - Pointer to TAF handler procedure + * + * @note + * See POCI_TAF_HANDLER documentation for more details + * +* @warning + * This call is supported from Oracle 10gR2. + * For previous versions, it returns FALSE without throwing any exception. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetTAFHandler +( + OCI_Connection *con, + POCI_TAF_HANDLER handler +); + +/** + * @brief + * Return the maximum number of statements to keep in the statement cache + * + * @param con - Connection handle + * + * @note + * Default value is 20 (value from Oracle Documentation) + * + * @warning + * Requires Oracle Client 9.2 or above + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetStatementCacheSize +( + OCI_Connection *con +); + +/** + * @brief + * Set the maximum number of statements to keep in the statement cache + * + * @param con - Connection handle + * @param value - maximum number of statements in the cache + * + * @warning + * Requires Oracle Client 9.2 or above + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetStatementCacheSize +( + OCI_Connection *con, + unsigned int value +); + +/** + * @brief + * Return the default LOB prefetch buffer size for the connection + * + * @param con - Connection handle + * + * @warning + * Requires Oracle Client AND Server 11gR1 or above + * + * @note + * Prefetch size is: + * - number of bytes for BLOBs and BFILEs + * - number of characters for CLOBs. + * + * @note + * Default is 0 (prefetching disabled) + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetDefaultLobPrefetchSize +( + OCI_Connection *con +); + +/** + * @brief + * Enable or disable prefetching for all LOBs fetched in the connection + * + * @param con - Connection handle + * @param value - default prefetch buffer size + * + * @note + * If parameter 'value': + * - is == 0, it disables prefetching for all LOBs fetched in the connection. + * - is > 0, it enables prefetching for all LOBs fetched in the connection + * and the given buffer size is used for prefetching LOBs + * + * @note + * LOBs prefetching is disabled by default + * + * @warning + * Requires Oracle Client AND Server 11gR1 or above. + * + * @note + * Prefetch size is: + * - number of bytes for BLOBs and BFILEs + * - number of characters for CLOBs. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetDefaultLobPrefetchSize +( + OCI_Connection *con, + unsigned int value +); + + +/** +* @brief +* Return the maximum number of SQL statements that can be opened in one session +* +* @param con - Connection handle +* +* @warning +* Requires Oracle Client AND Server 12cR1 or above +* +* @note +* the returned value is the same as the db parameter 'open_cursors' from server's parameter file +* +* @note +* Return 0 if the client and server version are < 12cR1 +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_GetMaxCursors +( + OCI_Connection *con +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiPools Oracle Pools + * @{ + * + * OCILIB support the connections and sessions pooling features introduced + * in Oracle 9i. + * + * Let's Oracle talk about this features ! + * + * @par Connection pools (from Oracle Call Interface Programmer's Guide) + * + * Connection pooling is the use of a group (the pool) of reusable physical connections + * by several sessions, in order to balance loads. The management of the pool is done + * by OCI, not the application. Applications that can use connection pooling include + * middle-tier applications for Web application servers and e-mail servers. + * + * @par Session Pools (from Oracle Call Interface Programmer's Guide) + * + * Session pooling means that the application will create and maintain a group of stateless + * sessions to the database. These sessions will be handed over to thin clients as requested. + * If no sessions are available, a new one may be created. When the client is done with + * the session, the client will release it to the pool. Thus, the number of sessions in + * the pool can increase dynamically. + * + * @note + * OCILIB implements homogeneous session pools only. + * + * @par When using Pools (from Oracle Call Interface Programmer's Guide) + * + * If database sessions are not reusable by mid-tier threads (that is, they are stateful) + * and the number of back-end server processes may cause scaling problems on the database, + * use OCI connection pooling. + * + * If database sessions are reusable by mid-tier threads (that is, they are stateless) + * and the number of back-end server processes may cause scaling problems on the database, + * use OCI session pooling. + * + * If database sessions are not reusable by mid-tier threads (that is, they are stateful) + * and the number of back-end server processes will never be large enough to potentially + * cause any scaling issue on the database, there is no need to use any pooling mechanism. + * + * @par Oracle 8i support + * + * Pooling has bee introduced in : + * - 9iR1 for connection pools + * - 9iR2 for session pools + * For Oracle 8i, OCILIB implements its own pooling mechanism in order to remain compatible + * with older versions. But sessions pools then are handled as connection pools + * + * @par Example + * @include pool.c + * + */ + +/** + * @brief + * Create an Oracle pool of connections or sessions + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param type - Type of pool + * @param mode - Session mode + * @param min_con - minimum number of connections/sessions that can be opened. + * @param max_con - maximum number of connections/sessions that can be opened. + * @param incr_con - next increment for connections/sessions to be opened + * + * Possible values for parameter 'type': + * - OCI_POOL_CONNECTION + * - OCI_POOL_SESSION + * + * Possible values for parameter 'mode': + * - OCI_SESSION_DEFAULT + * - OCI_SESSION_SYSDAB + * - OCI_SESSION_SYSOPER + * + * @note + * External credentials are supported by supplying a null value for the 'user' + * and 'pwd' parameters + * If the param 'db' is NULL then a connection to the default local DB is done + * + * @return + * Connection or session pool handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Pool * OCI_API OCI_PoolCreate +( + const otext *db, + const otext *user, + const otext *pwd, + unsigned int type, + unsigned int mode, + unsigned int min_con, + unsigned int max_con, + unsigned int incr_con +); + +/** + * @brief + * Destroy a pool object + * + * @param pool - Pool handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolFree +( + OCI_Pool *pool +); + +/** + * @brief + * Get a connection from the pool + * + * @param pool - Pool handle + * @param tag - user tag string + * + * @par Session tagging + * + * Session pools have a nice feature that is 'session tagging' + * It's possible to tag a session with a string identifier + * when the session is returned to the pool, it keeps its tags. + * When requesting a connection from the session pool, it's + * possible to request a session that has the given 'tag' parameter + * If one exists, it is returned. If not and if an untagged session + * is available, it is then returned. So check the connection tag + * property with OCI_GetSessionTag() to find out if the returned + * connection is tagged or not. + * + * This features is described in the OCI developer guide as the following : + * + * "The tags provide a way for users to customize sessions in the pool. + * A client may get a default or untagged session from a pool, set certain + * attributes on the session (such as NLS settings), and return the session + * to the pool, labeling it with an appropriate tag. + * The user may request a session with the same tags in order to have a + * session with the same attributes" + * + * @return + * Connection handle otherwise NULL on failure + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_PoolGetConnection +( + OCI_Pool *pool, + const otext *tag +); + +/** + * @brief + * Get the idle timeout for connections/sessions in the pool + * + * @param pool - Pool handle + * + * @note + * Connections/sessions idle for more than this time value (in seconds) is terminated + * + * @note + * Timeout is not available for internal pooling implementation (client < 9i) + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetTimeout +( + OCI_Pool *pool +); + +/** + * @brief + * Set the connections/sessions idle timeout + * + * @param pool - Pool handle + * @param value - Timeout value + * + * @note + * connections/sessions idle for more than this time value (in seconds) is terminated + * + * @note + * This call has no effect if pooling is internally implemented (client < 9i) + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolSetTimeout +( + OCI_Pool *pool, + unsigned int value +); + +/** + * @brief + * Get the waiting mode used when no more connections/sessions are available + * from the pool + * + * @param pool - Pool handle + * + * @return + * - FALSE to wait for an available object if the pool is saturated + * - TRUE to not wait for an available object + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolGetNoWait +( + OCI_Pool *pool +); + +/** + * @brief + * Set the waiting mode used when no more connections/sessions are available + * from the pool + * + * @param pool - Pool handle + * @param value - wait for object + * + * @note + * Pass : + * - FALSE to wait for an available object if the pool is saturated + * - TRUE to not wait for an available object + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolSetNoWait +( + OCI_Pool *pool, + boolean value +); + +/** + * @brief + * Return the current number of busy connections/sessions + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetBusyCount +( + OCI_Pool *pool +); + +/** + * @brief + * Return the current number of opened connections/sessions + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetOpenedCount +( + OCI_Pool *pool +); + +/** + * @brief + * Return the minimum number of connections/sessions that can be opened to the database + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetMin +( + OCI_Pool *pool +); + +/** + * @brief + * Return the maximum number of connections/sessions that can be opened to the database + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetMax +( + OCI_Pool *pool +); + +/** + * @brief + * Return the increment for connections/sessions to be opened to the database when the pool is + * not full + * + * @param pool - Pool handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetIncrement +( + OCI_Pool *pool +); + +/** + * @brief + * Return the maximum number of statements to keep in the pool statement cache + * + * @param pool - Pool handle + * + * @note + * Default value is 20 (value from Oracle Documentation) + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_PoolGetStatementCacheSize +( + OCI_Pool *pool +); + +/** + * @brief + * Set the maximum number of statements to keep in the pool statement cache + * + * @param pool - Pool handle + * @param value - maximum number of statements in the cache + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_PoolSetStatementCacheSize +( + OCI_Pool *pool, + unsigned int value +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiTransactions Managing transactions + * @{ + * + * OCILIB supports local and global transactions. + * + * Local transactions are implicit within connection objects and there is no + * specific call or programming step for using it. + * + * In order to control changes made in the database: + * + * - OCI_Commit() validates current pending modifications + * - OCI_Rollback() discards current pending modifications + * + * OCILIB supports a feature called 'Auto Commit' that performs an implicit and + * automatic commit call after every execute call + * + * @note + * Those actions are executed within a connection context and not directly to a transaction. + * + * @warning + * Global transactions are optional and are designed for distributed or global + * transaction environments. + * + * OCILIB supports them by : + * + * - Creating/Destroying explicitly a transaction object + * - Starting/Stopping/Resuming explicitly the transaction + * - Preparing the transaction for specific calls + * + */ + +/** + * @brief + * Commit current pending changes + * + * @param con - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_Commit +( + OCI_Connection *con +); + +/** + * @brief + * Cancel current pending changes + * + * @param con - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_Rollback +( + OCI_Connection *con +); + +/** + * @brief + * Enable / disable auto commit mode + * + * The auto commit mode allows commit changes after every executed SQL order + * + * @param con - Connection handle + * @param enable - Enable (TRUE) or disable (FALSE) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetAutoCommit +( + OCI_Connection *con, + boolean enable +); + +/** + * @brief + * Get current auto commit mode status + * + * @param con - Connection handle + * + * @return + * TRUE if auto commit mode is activated otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_GetAutoCommit +( + OCI_Connection *con +); + +/** + * @brief + * Create a new global transaction or a serializable/read-only local transaction + * + * @param con - Connection handle + * @param timeout - Time that a transaction stays inactive after being stopped + * @param mode - Transaction mode + * @param pxid - pointer to a global transaction identifier structure + * + * + * @note + * The parameter 'mode' can be one of the following values : + * + * - Global transactions: + * - OCI_TRS_NEW : By default starts a new, tightly coupled and + * migratable branch. + * - OCI_TRS_TIGHT : explicitly specifies a tightly coupled branch + * - OCI_TRS_LOOSE : specifies a loosely coupled branch + * + * - Global and local transactions : + * - OCI_TRS_READONLY - start a read-only transaction + * - OCI_TRS_READWRITE - start a read-write transaction + * - OCI_TRS_SERIALIZABLE : start a serializable transaction + * + * @note + * For local transaction: + * - pass a NULL value for pxid + * + */ + +OCI_EXPORT OCI_Transaction * OCI_API OCI_TransactionCreate +( + OCI_Connection *con, + unsigned int timeout, + unsigned int mode, + OCI_XID *pxid +); + +/** + * @brief + * Free current transaction + * + * @param trans - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionFree +( + OCI_Transaction *trans +); + +/** + * @brief + * Start global transaction + * + * @param trans - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionStart +( + OCI_Transaction *trans +); + +/** + * @brief + * Stop current global transaction + * + * @param trans - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionStop +( + OCI_Transaction *trans +); + +/** + * @brief + * Resume a stopped global transaction + * + * @param trans - Global transaction handle + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionResume +( + OCI_Transaction *trans +); + +/** + * @brief + * Prepare a global transaction validation + * + * @param trans - Global transaction handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionPrepare +( + OCI_Transaction *trans +); + +/** + * @brief + * Cancel the prepared global transaction validation + * + * @param trans - Global transaction handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TransactionForget +( + OCI_Transaction *trans +); + +/** + * @brief + * Return global transaction mode. + * + * @note: + * see OCI_TransactionCreate() for possible values + * + * @param trans - Global transaction handle + * + * @return + * Transaction mode or OCI_UNKNOW if trans is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TransactionGetMode +( + OCI_Transaction *trans +); + +/** + * @brief + * Return global transaction Timeout + * + * @param trans - Global transaction handle + * + * @return + * Transaction timeout or 0 if trans is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TransactionGetTimeout +( + OCI_Transaction *trans +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiStatements Executing statements + * @{ + * + * Executing SQL statements or PL/SQL blocks is really simple with OCILIB. + * + * First, call OCI_StatementCreate() to allocate a statement handle. Then : + * + * - Prepare the SQL with OCI_Prepare() + * - Parse and execute it with OCI_Execute() + * + * These two steps can be done together by calling OCI_ExecuteStmt() that + * prepares and executes in one go. + * + * To find out if the statement has affected any rows, call OCI_GetAffectedRows() + * + * Finally, release the statement and its resources with OCI_StatementFree() + * + * @note + * A statement can be prepared once and executed as many times as needed (see + * Binding variables section) + * + * @note + * An OCI_Statement can be used to prepare and/or execute different SQL and PL/SQL + * statements as many times as needed. + * For example, if the SQL processing of an application is sequential, only + * one statement handle is required + * + * @note + * OCILIB supports nested levels of SQL statement processing. + * An application can loop through the resultset of the statement handle A, + * executing statement B and fetching statement C at every loop, and so on ... + * + * @par Example + * @include exec.c + * + */ + +/** + * @brief + * Create a statement object and return its handle + * + * @param con - Connection handle + * + * @return + * A statement handle on success otherwise NULL + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_StatementCreate +( + OCI_Connection *con +); + +/** + * @brief + * Free a statement and all resources associated to it (resultsets ...) + * + * @param stmt - Connection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_StatementFree +( + OCI_Statement *stmt +); + +/** + * @brief + * Prepare a SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL order or PL/SQL block + * + * @note + * Do not call this function for fetched statements (REF cursors) + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_Prepare +( + OCI_Statement *stmt, + const otext *sql +); + +/** + * @brief + * Execute a prepared SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * + * @return + * TRUE on success otherwise FALSE + * + * @warning + * If a SQL warning occurs: + * - the function returns TRUE + * - the SQL warning triggers the global error handler with an OCI_Error having its OCI_ErrorGetType() + * attribute set to OCI_ERR_WARNING + * - If OCILIB is initialized with the OCI_ENV_CONTEXT mode, OCI_GetLastError() will return the OCI_Error + * object corresponding to the warning + * + */ + +OCI_EXPORT boolean OCI_API OCI_Execute +( + OCI_Statement *stmt +); + +/** + * @brief + * Prepare and Execute a SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL order - PL/SQL block + * + * @return + * TRUE on success otherwise FALSE + * + * @warning + * If a SQL warning occurs: + * - the function returns TRUE + * - the SQL warning triggers the global error handler with an OCI_Error having its OCI_ErrorGetType() + * attribute set to OCI_ERR_WARNING + * - If OCILIB is initialized with the OCI_ENV_CONTEXT mode, OCI_GetLastError() will return the OCI_Error + * object corresponding to the warning + * + */ + +OCI_EXPORT boolean OCI_API OCI_ExecuteStmt +( + OCI_Statement *stmt, + const otext *sql +); + +/** + * @brief + * Parse a SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL order - PL/SQL block + * + * @note + * This call sends the SQL or PL/SQL command to the server for parsing only. + * The command is not executed. + * This call is only useful to check is a command is valid or not. + * + * @note + * This call prepares the statement (internal call to OCI_Prepare()) and ask + * the Oracle server to parse its SQL or PL/SQL command. + * OCI_Execute() can be call after OCI_Parse() in order to execute the + * statement, which means that the server will re-parse again the command. + * + * @warning + * Do not use OCI_Parse() unless you're only interested in the parsing result + * because the statement will be parsed again when executed and thus leading to + * unnecessary server round-trips and less performance + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_Parse +( + OCI_Statement *stmt, + const otext *sql +); + +/** + * @brief + * Describe the select list of a SQL select statement. + * + * @param stmt - Statement handle + * @param sql - SELECT sql statement + * + * @note + * This call sends the SELECT SQL order to the server for retrieving the + * description of the select order only. + * The command is not executed. + * This call is only useful to retrieve information on the associated resultset + * Call OCI_GetResultet() after OCI_Describe() to access to SELECT list + * information + * + * @note + * This call prepares the statement (internal call to OCI_Prepare()) and ask + * the Oracle server to describe the output SELECT list. + * OCI_Execute() can be called after OCI_Desbribe() in order to execute the + * statement, which means that the server will parse, and describe again the SQL + * order. + * + * @warning + * Do not use OCI_Desbribe() unless you're only interested in the resultset + * information because the statement will be parsed again when executed and thus + * leading to unnecessary server round-trips and less performance + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_Describe +( + OCI_Statement *stmt, + const otext *sql +); + +/** + * @brief + * Return the last SQL or PL/SQL statement prepared or executed by the statement + * + * @param stmt - Statement handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetSql +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the error position (in terms of characters) in the SQL statement + * where the error occurred in case of SQL parsing error + * + * @param stmt - Statement handle + * + * @note + * Positions start at 1. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetSqlErrorPos +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the number of rows affected by the SQL statement + * + * @param stmt - Statement handle + * + * The returned value is : + * - For UPDATEs : number of rows updated + * - For INSERTs : number of rows inserted + * - For DELETEs : number of rows deleted + * + * @note + * For SELECTs statements, use OCI_GetRowCount() instead + * + * @note + * For PL/SQL blocks performing "select into :": + * - it returns the number of rows selected from PL/SQL + * - Up to version 4.3.0, OCI_Execute() returned FALSE and generated an error ORA-01403 - "No Data Found" + * - From version 4.3.1, OCI_Execute() returns 0 if no data found, otherwise the number of selected rows + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetAffectedRows +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the Oracle SQL code the command held by the statement handle + * + * @param stmt - Statement handle + * + * @warning + * OCI_GetSQLCommand() must be called after the statement has be executed + * because that's the server engine that computes the SQL command code + * + * @return + * The SQL command code of the statement otherwise OCI_UNKOWN + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetSQLCommand +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the verb of the SQL command held by the statement handle + * + * @param stmt - Statement handle + * + * @warning + * OCI_GetSQLVerb() must be called after the statement has been executed + * because that's the server engine that computes the SQL verb + * + * @note + * The SQL verb list is available in Oracle documentations and guides + * + * @return + * The SQL command verb of the statement otherwise NULL + */ + +OCI_EXPORT const otext * OCI_API OCI_GetSQLVerb +( + OCI_Statement *stmt +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiBinding Binding variables and arrays + * @{ + * + * OCILIB supports OCI data binding APIs + * + * Programs variables can be binded to an Oracle SQL PL/SQL statement in order to : + * + * - Provide input data for SQL statement + * - Provide input/output data for PL/SQL blocks + * + * OCILIB provides a set of binding functions to use with: + * + * - Basic data types: string (char/wchar_t *), int, float, double, raw + * - Object data types: lobs, files,longs, dates, cursors, statements, + * timestamps, intervals, objects + * + * To use binding: + * + * - Prepare a statement with OCI_Prepare() (see Executing statements) + * - Bind variables by calling one if the OCI_Bindxxxxx() function for every + * input variable referenced by the SQL statement + * - Setup up values of the program variables + * - Call OCI_Execute() as many times as needed + * - Each OCI_Execute() call may be preceded by an update of the program + * variables (for INSERTs for example) + * + * Bindings can be: + * - IN (host variable are not used anymore after statement execution) + * - OUT (host variable are set during statement execution) + * - IN/OUT (default) + * Use OCI_BindSetDirectionTo() to change a host variable bind direction mode after the binding call but before statement execution. + * Note that each direction mode may have a little overhead depending on the SQL type as OCILIB may have to do checks/conversions/mappings between host variable and buffers. + * Thus, to maximize performances: + * - set direction mode to OCI_BDM_IN if host variable is not updated by statement execution + * - set direction mode to OCI_BDM_OUT if host variable value does not matter prior to statement execution + * - set direction mode to OCI_BDM_IN_OUT when host variable value is used for execution and updated by statement execution + * + * OCILIB supports the OCI array Interface by binding arrays of C scalar types + * and OCILIB object types. + * + * - all types supported the library can be used for array binding except + * OCI_Statement and OCI_Long + * - Array binding is really fast for massive DML operations + * - For string/RAW arrays, the input array MUST BE a contiguous block of data + * and not an array of pointers. So to bind an array of 10 elements for a + * varchar2(30) column, binded variable must be a like array[10][31] + * + * OCILIB does not pre-parse statements (like other frameworks such as JDBC, ...) + * and lets Oracle recognize input variables embedded within the SQL statements. + * + * Bind variables must be preceded in the SQL code by the character ':'. + * + * Oracle and OCILIB supports two ways of binding: + * + * - by name (default mode in OCILIB): Oracle looks for variables in the SQL + * statement by searching their names provided to the binding function. + * So a variable can be binded once and used many times in the statement + * - by position: Oracle binds variables by position, so every variable is + * binded with a position number + * + * OCILIB Default binding mode is OCI_BIND_BY_NAME. + * + * When using binding by position, provide the position to OCI_BindXXXX() call + * through the name parameter. Within this mode the bind name must be the + * position preceded by a semicolon like ':1', ':2', .... + * + * @par Internal Bind allocation mode + * + * Bind variables or arrays can be internally allocated by OCILIB. + * That means that instead of allocating variables or arrays on the stack/heap + * in the user program, bind contents can be allocated internally and thus : + * - minimize the amount of program variables + * - optimize internal memory management for arrays + * + * To do so : + * - Call OCI_SetBindAllocation() with the mode OCI_BAM_INTERNAL + * - pass a NULL variable or array to OCI_BindXXX() calls + * - Retrieve the bind content allocated by OCILIB with OCI_BindGetData() + * + * Internal Bind allocation mode IS compatible with ALL array binding OCI_BindArrayOfxxx() methods. + * + * Internal Bind allocation mode IS NOT compatible with some single variable bind calls : + * - OCI_BindTimestamp() + * - OCI_BindInterval() + * - OCI_BindLob() + * - OCI_BindFile() + * - OCI_BindObject() + * - OCI_BindColl() + * - OCI_BindRef() + * - OCI_BindStatement() + * - OCI_BindLong() + * + * These methods need to know the data sub type (like OCI_CLOB/OCI_BLOB for lobs) in order + * to internally create variables. As these methods prototypes are not passing the sub type, + * calling them with the statement bind mode set to OCI_BAM_INTERNAL will raise + * an OCILIB error of type OCI_ERR_NULL_POINTER + * + * @note + * Rebinding is disabled by default (see OCI_AllowRebinding()) + * When using rebinding feature, host variable re-binded to a previously allocated + * bind MUST be of the SAME data type ! + * + * @par Basic input bind Example + * @include bind.c + * + * @par Array interface Example + * @include array.c + * + * @par Internal Array interface Example + * @include array_internal.c + * + * */ + +/** + * @brief + * Set the input array size for bulk operations + * + * @param stmt - Statement handle + * @param size - Array size + * + * @warning + * Do not use OCI_BindArraySetSize() for PL/SQL tables binding + * + * @note + * OCI_BindArraySetSize() is used to set the size of input bind array when using + * arrays for DML statements. + * OCI_BindArraySetSize() MUST be called to set the maximum size of the arrays + * to bind to the statement before any of its execution. This initial call must + * be bone AFTER OCI_Prepare() and BEFORE any OCI_BindArrayOfxxx() call. + * + * @note + * OCI_BindArraySetSize() can optionally be called before any later OCI_Execute() + * call in order to notify the statement of the exact number of elements + * populating the input arrays for the next execution. The array size passed to + * later OCI_BindArraySetSize() calls cannot be greater than the initial size + * otherwise an exception will be thrown. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArraySetSize +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the current input array size for bulk operations + * + * @param stmt - Statement handle + * + * @return + * Array size value or 0 if OCI_BindArraySetSize() has not been called + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindArrayGetSize +( + OCI_Statement *stmt +); + +/** + * @brief + * Allow different host variables to be binded using the same bind name or + * position between executions of a prepared statement + * + * @param stmt - Statement handle + * @param value - Rebinding mode allowed + * + * @note + * Default value is FALSE + * + * @warning + * When using rebinding feature, host variable re-binded to a previously allocated + * bind MUST be of the same data type ! + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_AllowRebinding +( + OCI_Statement *stmt, + boolean value +); + +/** + * @brief + * Indicate if rebinding is allowed on the given statement + * + * @param stmt - Statement handle + * + * @note + * See OCI_AllowRebinding() for more details + * + * @return + * TRUE if allowed otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_IsRebindingAllowed +( + OCI_Statement *stmt +); + +/** +* @brief +* Bind a boolean variable (PL/SQL ONLY) +* +* @param stmt - Statement handle +* @param name - Variable name +* @param data - Pointer to boolean variable +* +* @note +* parameter 'data' can NULL if the statement bind allocation mode +* has been set to OCI_BAM_INTERNAL +* +* @warning +* - OCI_BindBoolean() CAN ONLY BE USED for PL/SQL boolean type when calling PL/SQL procedures/function +* - ONLY supported by Oracle 12c and above ! +* +* @return +* TRUE on success otherwise FALSE +*/ +OCI_EXPORT boolean OCI_API OCI_BindBoolean +( + OCI_Statement *stmt, + const otext *name, + boolean *data +); + +/** +* @brief +* Bind an Number variable +* +* @param stmt - Statement handle +* @param name - Variable name +* @param data - Pointer to short variable +* +* @note +* parameter 'data' can NULL if the statement bind allocation mode +* has been set to OCI_BAM_INTERNAL +* +* @return +* TRUE on success otherwise FALSE +*/ + +OCI_EXPORT boolean OCI_API OCI_BindNumber +( + OCI_Statement *stmt, + const otext *name, + OCI_Number *data +); + +/** +* @brief +* Bind an array of Number +* +* @param stmt - Statement handle +* @param name - Variable name +* @param data - Array of numbers +* @param nbelem - Number of element in the array (PL/SQL table only) +* +* @warning +* Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. +* For regular DML array operations, pass the value 0. +* +* @note +* parameter 'data' can NULL if the statement bind allocation mode +* has been set to OCI_BAM_INTERNAL +* +* @return +* TRUE on success otherwise FALSE +*/ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfNumbers +( + OCI_Statement *stmt, + const otext *name, + OCI_Number **data, + unsigned int nbelem +); + +/** + * @brief + * Bind an short variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to short variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindShort +( + OCI_Statement *stmt, + const otext *name, + short *data +); + +/** + * @brief + * Bind an array of shorts + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of shorts + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfShorts +( + OCI_Statement *stmt, + const otext *name, + short *data, + unsigned int nbelem +); + +/** + * @brief + * Bind an unsigned short variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to unsigned short variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindUnsignedShort +( + OCI_Statement *stmt, + const otext *name, + unsigned short *data +); + +/** + * @brief + * Bind an array of unsigned shorts + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of unsigned shorts + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfUnsignedShorts +( + OCI_Statement *stmt, + const otext *name, + unsigned short *data, + unsigned int nbelem +); + +/** + * @brief + * Bind an integer variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to int variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindInt +( + OCI_Statement *stmt, + const otext *name, + int *data +); + +/** + * @brief + * Bind an array of integers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of int + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfInts +( + OCI_Statement *stmt, + const otext *name, + int *data, + unsigned int nbelem +); + +/** + * @brief + * Bind an unsigned integer variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to unsigned int variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindUnsignedInt +( + OCI_Statement *stmt, + const otext *name, + unsigned int *data +); + +/** + * @brief + * Bind an array of unsigned integers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of unsigned int + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfUnsignedInts +( + OCI_Statement *stmt, + const otext *name, + unsigned int *data, + unsigned int nbelem +); + +/** + * @brief + * Bind a big integer variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to big int variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindBigInt +( + OCI_Statement *stmt, + const otext *name, + big_int *data +); + +/** + * @brief + * Bind an array of big integers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of big int + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfBigInts +( + OCI_Statement *stmt, + const otext *name, + big_int *data, + unsigned int nbelem +); + +/** + * @brief + * Bind an unsigned big integer variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to unsigned big int variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindUnsignedBigInt +( + OCI_Statement *stmt, + const otext *name, + big_uint *data +); + +/** + * @brief + * Bind an array of unsigned big integers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of unsigned big int + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfUnsignedBigInts +( + OCI_Statement *stmt, + const otext *name, + big_uint *data, + unsigned int nbelem +); + +/** + * @brief + * Bind a string variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - String to bind + * @param len - Max length of the string (in character without + * the zero null terminal character) + * + * @note + * if len == 0, len is set to the string size + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindString +( + OCI_Statement *stmt, + const otext *name, + otext *data, + unsigned int len +); + +/** + * @brief + * Bind an array of strings + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of string + * @param len - Max length of a single string element (in character without + * the zero null terminal character) + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @warning + * if len <= 0, it returns FALSE + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfStrings +( + OCI_Statement *stmt, + const otext *name, + otext *data, + unsigned int len, + unsigned int nbelem +); + +/** + * @brief + * Bind a raw buffer + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - buffer to bind + * @param len - Max length of the buffer + * + * @note + * if len <= 0, it returns false + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindRaw +( + OCI_Statement *stmt, + const otext *name, + void *data, + unsigned int len +); + +/** + * @brief + * Bind an array of raw buffers + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of buffers + * @param len - Size in bytes on a single RAW array element + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * The buffer must be a contiguous block of data elements + * + * @note + * If len <= 0, it returns FALSE + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfRaws +( + OCI_Statement *stmt, + const otext *name, + void *data, + unsigned int len, + unsigned int nbelem +); + +/** + * @brief + * Bind a double variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to double variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindDouble +( + OCI_Statement *stmt, + const otext *name, + double *data +); + +/** + * @brief + * Bind an array of doubles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of double + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfDoubles +( + OCI_Statement *stmt, + const otext *name, + double *data, + unsigned int nbelem +); + + +/** + * @brief + * Bind a float variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Pointer to float variable + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindFloat +( + OCI_Statement *stmt, + const otext *name, + float *data +); + +/** + * @brief + * Bind an array of floats + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of float + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfFloats +( + OCI_Statement *stmt, + const otext *name, + float *data, + unsigned int nbelem +); + +/** + * @brief + * Bind a date variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Date handle + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindDate +( + OCI_Statement *stmt, + const otext *name, + OCI_Date *data +); + +/** + * @brief + * Bind an array of dates + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of date handle + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfDates +( + OCI_Statement *stmt, + const otext *name, + OCI_Date **data, + unsigned int nbelem +); + +/** + * @brief + * Bind a timestamp variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Timestamp handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindTimestamp +( + OCI_Statement *stmt, + const otext *name, + OCI_Timestamp *data +); + +/** + * @brief + * Bind an array of timestamp handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Timestamp handle + * @param type - Timestamp type + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_TimestampCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfTimestamps +( + OCI_Statement *stmt, + const otext *name, + OCI_Timestamp **data, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Bind an interval variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Interval handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindInterval +( + OCI_Statement *stmt, + const otext *name, + OCI_Interval *data +); + +/** + * @brief + * Bind an array of interval handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Interval handle + * @param type - Interval type + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_IntervalCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfIntervals +( + OCI_Statement *stmt, + const otext *name, + OCI_Interval **data, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Bind a Lob variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Lob handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindLob +( + OCI_Statement *stmt, + const otext *name, + OCI_Lob *data +); + +/** + * @brief + * Bind an array of Lob handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Lob handle + * @param type - Lob type + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_LobCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfLobs +( + OCI_Statement *stmt, + const otext *name, + OCI_Lob **data, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Bind a File variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - File handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindFile +( + OCI_Statement *stmt, + const otext *name, + OCI_File *data +); + +/** + * @brief + * Bind an array of File handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of File handle + * @param type - File type + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_FileCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfFiles +( + OCI_Statement *stmt, + const otext *name, + OCI_File **data, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Bind an object (named type) variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Object handle + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindObject +( + OCI_Statement *stmt, + const otext *name, + OCI_Object *data +); + +/** + * @brief + * Bind an array of object handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of object handle + * @param typinf - type info handle + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfObjects +( + OCI_Statement *stmt, + const otext *name, + OCI_Object **data, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Bind a Collection variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Collection handle to bind + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindColl +( + OCI_Statement *stmt, + const otext *name, + OCI_Coll *data +); + +/** + * @brief + * Bind an array of Collection handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Collection handle + * @param typinf - Type info handle + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * See OCI_CollCreate() for possible values of parameter 'type' + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfColls +( + OCI_Statement *stmt, + const otext *name, + OCI_Coll **data, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Bind a Ref variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Ref handle to bind + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindRef +( + OCI_Statement *stmt, + const otext *name, + OCI_Ref *data +); + +/** + * @brief + * Bind an array of Ref handles + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Array of Ref handle + * @param typinf - type info handle + * @param nbelem - Number of element in the array (PL/SQL table only) + * + * @warning + * Parameter 'nbelem' SHOULD ONLY be USED for PL/SQL tables. + * For regular DML array operations, pass the value 0. + * + * @note + * parameter 'data' can NULL if the statement bind allocation mode + * has been set to OCI_BAM_INTERNAL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindArrayOfRefs +( + OCI_Statement *stmt, + const otext *name, + OCI_Ref **data, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Bind a Statement variable (PL/SQL Ref Cursor) + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Statement handle to bind + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindStatement +( + OCI_Statement *stmt, + const otext *name, + OCI_Statement *data +); + +/** + * @brief + * Bind a Long variable + * + * @param stmt - Statement handle + * @param name - Variable name + * @param data - Long handle + * @param size - Size of the long buffer in bytes or characters + * + * @note + * Size is expressed in: + * - Bytes for BLONGs + * - Characters for CLONGs + * + * @note + * parameter 'data' CANNOT be NULL whatever the statement bind allocation mode + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindLong +( + OCI_Statement *stmt, + const otext *name, + OCI_Long *data, + unsigned int size +); + +/** + * @brief + * Returns the first or next error that occurred within a DML array statement execution + * + * @param stmt - Statement handle + * + * @return + * The first or next error handle otherwise NULL + */ + +OCI_EXPORT OCI_Error * OCI_API OCI_GetBatchError +( + OCI_Statement *stmt +); + +/** + * @brief + * Returns the number of errors that occurred within the last DML array statement + * + * @param stmt - Statement handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetBatchErrorCount +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the number of binds currently associated to a statement + * + * @param stmt - Statement handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetBindCount +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the bind handle at the given index in the internal array of bind + * handle + * + * @param stmt - Statement handle + * @param index - Bind position + * + * @note + * Index starts at 1. + * + * @note + * Bind handle are created sequentially. For example, the third call to a + * OCI_BindXXX() generates a bind handle of index 3. + * + * @return + * The bind handle or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Bind * OCI_API OCI_GetBind +( + OCI_Statement *stmt, + unsigned int index +); + +/** + * @brief + * Return a bind handle from its name + * + * @param stmt - Statement handle + * @param name - Bind variable name + * + * @note + * Bind names must include a semicolon at the beginning. + * + * @return + * The bind handle or NULL if not found + * + */ + +OCI_EXPORT OCI_Bind * OCI_API OCI_GetBind2 +( + OCI_Statement *stmt, + const otext *name +); + +/** +* @brief +* Return the index of the bind from its name belonging to the given statement +* +* @param stmt - Statement handle +* @param name - Bind variable name +* +* @warning +* The bind name is case insensitive +* +* @note +* Bind indexes start with 1 in OCILIB +* +* @return +* Bind index on success or zero if the bind does not exists or if statement is NULL +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_GetBindIndex +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Return the name of the given bind + * + * @param bnd - Bind handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_BindGetName +( + OCI_Bind *bnd +); + + +/** + * @brief + * Set the direction mode of a bind handle + * + * @param bnd - Bind handle + * @param direction - direction mode + * + * @note + * Possible values for parameter 'direction' : + * - OCI_BDM_IN : input values (not modified by the server) + * - OCI_BDM_OUT : output values (modified by the server) + * - OCI_BDM_IN_OUT : input and output values + * + * @note + * Default value is OCI_BDM_IN_OUT + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetDirection +( + OCI_Bind *bnd, + unsigned int direction +); + +/** + * @brief + * Get the direction mode of a bind handle + * + * @param bnd - Bind handle + * + * @note + * see OCI_BindSetDirection() for more details + * + * return the bind direction mode on success otherwise OCI_UNKNWON + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetDirection +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the OCILIB type of the given bind + * + * @param bnd - Bind handle + * + * @note + * Possible values are : + * + * - OCI_CDT_NUMERIC : short, int, long long, float, double + * - OCI_CDT_DATETIME : OCI_Date * + * - OCI_CDT_TEXT : otext * + * - OCI_CDT_LONG : OCI_Long * + * - OCI_CDT_CURSOR : OCI_Statement * + * - OCI_CDT_LOB : OCI_Lob * + * - OCI_CDT_FILE : OCI_File * + * - OCI_CDT_TIMESTAMP : OCI_Timestamp * + * - OCI_CDT_INTERVAL : OCI_Interval * + * - OCI_CDT_RAW : void * + * - OCI_CDT_OBJECT : OCI_Object * + * - OCI_CDT_COLLECTION : OCI_Coll * + * - OCI_CDT_REF : OCI_Ref * + * - OCI_CDT_BOOLEAN : boolean + * + * @return + * The column type or OCI_CDT_UNKNOWN on error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetType +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the OCILIB object subtype of the given bind + * + * @param bnd - Bind handle + * + * @note + * * This call is valid for the following OCILIB types: + * - OCI_CDT_NUMERIC + * - OCI_CDT_LONG + * - OCI_CDT_LOB + * - OCI_CDT_FILE + * - OCI_CDT_TIMESTAMP + * - OCI_CDT_INTERVAL + * + * For numeric binds the possible values are: + * - OCI_NUM_SHORT + * - OCI_NUM_INT + * - OCI_NUM_BIGINT + * - OCI_NUM_USHORT + * - OCI_NUM_UINT + * - OCI_NUM_BIGUINT + * - OCI_NUM_DOUBLE + * - OCI_NUM_FLOAT + * - OCI_NUM_NUMBER + * + * For OCI_Long type the possible values are: + * - OCI_BLONG + * - OCI_CLONG + * + * For OCI_Lob type the possible values are: + * - OCI_BLOB + * - OCI_CLOB + * - OCI_NCLOB + * + * For OCI_File type the possible values are: + * - OCI_BFILE + * - OCI_CFILE + * + * For OCI_Timestamp type the possible values are: + * - OCI_TIMESTAMP + * - OCI_TIMESTAMP_TZ + * - OCI_TIMESTAMP_LTZ + * + * For OCI_Interval type the possible values are: + * - OCI_INTERVAL_YM + * - OCI_INTERVAL_DS + * + * @note + * For all other OCILIB types, it returns OCI_UNKNOWN + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetSubtype +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the number of elements of the bind handle + * + * @param bnd - Bind handle + * + * @return + * - For single binds, it returns 1 + * - For array binds, it returns the number of element in the array + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetDataCount +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the user defined data associated with a bind handle + * + * @param bnd - Bind handle + * + * @return + * - The pointer to variable/array passed to an OCI_BindXXX() or + * OCI_BindArrayOfXXX() call + * + */ + +OCI_EXPORT void * OCI_API OCI_BindGetData +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the statement handle associated with a bind handle + * + * @param bnd - bind handle + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_BindGetStatement +( + OCI_Bind *bnd +); + +/** + * @brief + * Set the actual size of the element held by the given bind handle + * + * @param bnd - bind handle + * @param size - data size + * + * @note + * This call is not mandatory and should ONLY be called for RAWs binds to set + * the real size of the given data if different from the expected column or + * parameter size + * + * @note + * It works as well with string based PL/SQL tables (in or in/out but NOT out) + * even if it's not necessary. + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the parameter 'size' is expressed in + * number of characters. + * + * @return + * Data size if the bind type is listed above otherwise 0. + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetDataSize +( + OCI_Bind *bnd, + unsigned int size +); + +/** + * @brief + * Set the size of the element at the given position in + * the bind input array + * + * @param bnd - bind handle + * @param position - Position in the array + * @param size - data size + * + * @note + * See OCI_BindSetDataSize() for supported data types + * + * @warning + * Before execution, it returns the max default size for the bind and not the real + * data size, unless a custom size has been set with OCI_BindSetDataSizeXXX() + * After execution, it returns the real data size. + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the parameter 'size' is expressed in + * number of characters. + * + * @return + * Data size if the bind type is listed above otherwise 0. + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetDataSizeAtPos +( + OCI_Bind *bnd, + unsigned int position, + unsigned int size +); + +/** + * @brief + * Return the actual size of the element held by the given bind handle + * + * @param bnd - bind handle + * + * @note + * See OCI_BindSetDataSize() for supported data types + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the returned value is expressed in + * number of characters. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetDataSize +( + OCI_Bind *bnd +); + +/** + * @brief + * Return the actual size of the element at the given position in + * the bind input array + * + * @param bnd - bind handle + * @param position - Position in the array + * + * @note + * See OCI_BindSetDataSize() for supported data types + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the returned value is expressed in + * number of characters. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetDataSizeAtPos +( + OCI_Bind *bnd, + unsigned int position +); + +/** + * @brief + * Set the bind variable to null + * + * @param bnd - Bind handle + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetNull +( + OCI_Bind *bnd +); + +/** + * @brief + * Set to null the entry in the bind variable input array + * + * @param bnd - Bind handle + * @param position - Position in the array + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Position starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetNullAtPos +( + OCI_Bind *bnd, + unsigned int position +); + +/** + * @brief + * Set the bind variable to NOT null + * + * @param bnd - Bind handle + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetNotNull +( + OCI_Bind *bnd +); + +/** + * @brief + * Set to NOT null the entry in the bind variable input array + * + * @param bnd - Bind handle + * @param position - Position in the array + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Position starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_BindSetNotNullAtPos +( + OCI_Bind *bnd, + unsigned int position +); + +/** + * @brief + * Check if the current value of the binded variable is marked as NULL + * + * @param bnd - Bind handle + * + * @return + * TRUE if it's null otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindIsNull +( + OCI_Bind *bnd +); + +/** + * @brief + * Check if the current entry value at the given index of the binded array + * is marked as NULL + * + * @param bnd - Bind handle + * @param position - Position in the array + * + * @warning + * Position starts with 1 + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_BindIsNullAtPos +( + OCI_Bind *bnd, + unsigned int position +); + +/** + * @brief + * Set the charset form of the given character based bind variable + * + * @param bnd - Bind handle + * @param csfrm - charset form + * + * @note + * Possible values are : + * + * - OCI_CSF_DEFAULT : the column has default charset + * - OCI_CSF_NATIONAL: the column has national charset + * + * @note + * This call has to be made after OCI_Prepare() but before OCI_Execute() + * + * @warning + * This call does nothing : + * - if the csform is out of range + * - if the bind type is not OCI_CFT_TEXT or OCI_CDT_LONG + * + * @return + * TRUE on success otherwise FALSE + * + */ + +boolean OCI_API OCI_BindSetCharsetForm +( + OCI_Bind *bnd, + unsigned int csfrm +); + +/** + * @brief + * Get the allocaton mode of a bind handle + * + * @param bnd - Bind handle + * + * @note + * Possible values are : + * - OCI_BAM_EXTERNAL : bind variable is allocated by user code + * - OCI_BAM_INTERNAL : bind variable is allocated internally + * + * return the allocaton mode on success otherwise OCI_UNKNWON + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_BindGetAllocationMode +( + OCI_Bind *bnd +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiFetching Fetching data + * @{ + * + * OCILIB offers a really easy and smart mechanism to fetch data from a SQL Statement. + * It looks like what's found in JDBC and other object oriented databases frameworks. + * + * ONLY the following statements can return resultsets that can be fetched by host programs: + * - Statements executing SQL SELECT + * - Statements executing SQL UPDATE/DELETE using a RETURNING INTO clause + * - Statements binded to PL/SQL OPEN FOR argument + * - Statements binded to PL/SQL procedure OUT variables + * - Statements implicitly returned from PL/SQL procedure or blocks (new feature in Oracle 12cR1) using + * DBMS_SQL.RETURN_RESULT() + * + * These resultsets are encapsulated in OCILIB by OCI_Resultset objects. + * + * Thus, after any successful call to an OCI_Executexxx() function that executed + * a fetchable statement or filled output bind variables, the resultset can be + * retrieved by calling OCI_GetResultset() + * + * The creation of a OCI_Resultset object consists in : + * + * - Describing the output columns of the resultset + * - Allocating memory to hold the content data + * + * OCILIB supports multi-row fetching for increasing performances. Instead of + * fetching data row by row from the server (that induces lots of round-trips + * between the client and the server), the library prefetches data chunk by + * chunks (default is 20 rows). + * So, less network traffic and better performances. + * These mechanisms are completely hidden from the application which fetches the + * resultset row by row. + * + * Once the Resultset handle is retrieved : + * + * - It can be fetched by calling OCI_FetchNext() as long as it returns TRUE. + * - To retrieve the value of a column, call OCI_GetXXXX() where XXXX is the + * type of data you want to fetch. + * + * @note + * In case of a statement that has executed PL/SQL calls or blocks returning implicit resultsets: + * - OCI_GetResultset() return the first available resultset + * - OCI_GetNextResultset() return the next available resultset until no more resultset available + * + * @par Scrollable Resultsets + * + * Oracle 9i introduced scrollable cursors (resultsets in OCILIB) that can be + * fetched: + * + * - Sequentially in both directions: OCI_FetchPrev() and OCI_FetchNext() + * - To a relative position in the resultset: OCI_FetchSeek() with OCI_SFD_RELATIVE + * - To an absolute position in the resultset: OCI_FetchSeek() with OCI_SFD_ABOSLUTE + * - To the first or last row in the resultset: OCI_FetchFirst() and OCI_FetchLast() + * + * Scrollable statements uses more server and client resources and should only + * be used when necessary. + * + * Resultsets are 'forward only' by default. Call OCI_SetFetchMode() with + * OCI_SFM_SCROLLABLE to enable scrollable resultsets for a given statement. + * + * @warning + * Any use of scrollable fetching functions with a resultset that depends on a + * statement with fetch mode set to OCI_SFM_DEFAULT will fail ! + * + * @warning + * If you intend to use OCI_FetchSeek() on a scrollable statement and if any of the + * selected columns is a ref cursor or a nested table, OCILIB will internally set the + * resultset internal array size to 1 and thus ignore any values set using OCI_SetFetchSize() + * This is performed due to an Oracle bug. + * + * @note + * If the column internal data does not match the requested type, OCILIB tries + * to convert the data when it's possible and throws an error if not. + * + * The properties (columns names, types ...) of the resultset are accessible + * through a set of APIs. + * + * @par Implicit conversion to string types + * + * OCI_GetString() performs an implicit conversion from ANY Oracle types: + * + * - Numerics (based on the current connection handle numeric format) + * - Binary doubles and floats (using the standard C Library functions) + * - OCI_Date : uses OCI_DateToText() with current connection date format + * - OCI_Timestamp : uses OCI_TimestampToText() with current connection date format + * - OCI_Interval : uses OCI_IntervalToText() with Oracle default format + * - OCI_Coll : uses OCI_CollToText() + * - OCI_Object : uses OCI_ObjectToText() + * - OCI_Ref : uses OCI_RefToText() + * - OCI_File : returns "$(folder)/$(filename)" - no content returned + * - OCI_Lob : see note above for binary types + * - OCI_Long : see note above for binary types + * - RAWs : see note above for binary types + * + * @note + * For RAWs and BLOBs attributes, their binary values are converted to hexadecimal strings + * For LONG and CLOBs/NCLOBSs attributes, the whole string content is returned + * + * @note + * The following OCILIB types are not supported for implicit conversion: + * - OCI_Statement + * + * @warning + * For Dates and numerics types, OCILIB uses OCI client calls to perform + * the conversion. + * For binary double and binary floats data types, OCI client functions cannot + * handle the full double range of values. Thus, OCILIB is using the + * standard C library to convert theses data types to string + * + * @par Fetching rows into user structures + * + * It is possible to fetch a complete row into a user defined structure. + * Each column of the resultset is mapped to a structure member. + * The mapping rules are : + * - LOBs (CLOB, NCLOB, BLOB) : OCI_Lob * + * - DATE : OCI_Date * + * - TIMESTAMPS : OCI_Timestamp * + * - INTERVALS : OCI_Interval * + * - LONG, LONG RAW : OCI_Long * + * - REFs : OCI_Ref * + * - CURSOR, RESULSET : OCI_Statement * + * - OBJECTS, UDT : OCI_Object * + * - Character columns (CHAR,VARCHAR, etc..) : otext * + * - All NUMERIC types : + * - default : big_int + * - user defined (see OCI_SetStructNumericType()) + * + * See OCI_GetStruct() and OCI_SetStructNumericType() for more details + * + * @par Fetch Example + * @include fetch.c + * + * @par Fetch Rows into user structures Example + * @include fetch_struct.c + * + * @par Meta data Example + * @include meta.c + * + * @par Ref cursor Example + * @include cursor.c + * + * @par Implicit resultset Example + * @include implicit_resultset.c + * + * @par Scrollable resultset Example + * @include scroll.c + * + */ + +/** + * @brief + * Retrieve the resultset handle from an executed statement + * + * @param stmt - Statement handle + * + * @note + * See @ref OcilibCApiFetching for more details about what statements can return resultsets + * + * @warning + * If the statement has not been prepared and executed, no resultset will be returned + * + * @return + * A resultset handle on success otherwise NULL + * + */ + +OCI_EXPORT OCI_Resultset * OCI_API OCI_GetResultset +( + OCI_Statement *stmt +); + +/** + * @brief + * Free the statement resultsets + * + * @param stmt - Statement handle + * + * @note + * This call is optional. Resultsets are automatically freed when the + * statement is destroyed or when it's reused. + * + * @note + * This function has been introduced for releasing big resultsets when the + * application wants to keep the statement alive and doesn't know when it + * will be destroyed. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ReleaseResultsets +( + OCI_Statement *stmt +); + +/** + * @brief + * Fetch the next row of the resultset + * + * @param rs - Resultset handle + * + * @note + * OCI_FetchNext() works for normal and scrollable resultsets + * + * @return + * TRUE on success otherwise FALSE if : + * - Empty resultset + * - Last row already fetched + * - An error occurred + * + */ + +OCI_EXPORT boolean OCI_API OCI_FetchNext +( + OCI_Resultset *rs +); + +/** + * @brief + * Fetch the previous row of the resultset + * + * @param rs - Resultset handle + * + * @note + * OCI_FetchPrev() works ONLY for scrollable resultsets + * + * @return + * TRUE on success otherwise FALSE if : + * - Empty resultset + * - First row already fetched + * - An error occurred + * + */ + +OCI_EXPORT boolean OCI_API OCI_FetchPrev +( + OCI_Resultset *rs +); + +/** + * @brief + * Fetch the first row of the resultset + * + * @param rs - Resultset handle + * + * @note + * OCI_FetchFirst() works ONLY for scrollable resultsets + * + * @return + * TRUE on success otherwise FALSE if : + * - Empty resultset + * - An error occurred + *f + */ + +OCI_EXPORT boolean OCI_API OCI_FetchFirst +( + OCI_Resultset *rs +); + +/** + * @brief + * Fetch the last row of the resultset + * + * @param rs - Resultset handle + * + * @note + * OCI_FetchLast() works ONLY for scrollable resultsets + * + * @return + * TRUE on success otherwise FALSE if: + * - Empty resultset + * - An error occurred + * + */ + +OCI_EXPORT boolean OCI_API OCI_FetchLast +( + OCI_Resultset *rs +); + +/** + * @brief + * Custom Fetch of the resultset + * + * @param rs - Resultset handle + * @param mode - Fetch direction + * @param offset - Fetch offset + * + * @note + * Possible values for 'direction' parameter are: + * - OCI_SFD_ABSOLUTE + * - OCI_SFD_RELATIVE + * + * @note + * OCI_FetchSeek() works ONLY for scrollable resultsets + * + * @warning + * If you intend to use OCI_FetchSeek() on a scrollable statement and if any of the + * selected columns is a ref cursor or a nested table, you must set the fetching size + * to 1 using OCI_SetFetchSize() before calling OCI_GetResultset() + * Otherwise OCI_FetchSeek() will fails with a OCI-10002 error + * + * @return + * TRUE on success otherwise FALSE if: + * - Empty resultset + * - An error occurred + * - OCI_SetFetchMode() has not been called with OCI_SFM_SCROLLABLE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FetchSeek +( + OCI_Resultset *rs, + unsigned int mode, + int offset +); + +/** + * @brief + * Retrieve the number of rows fetched so far + * + * @param rs - Resultset handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetRowCount +( + OCI_Resultset *rs +); + +/** + * @brief + * Retrieve the current row number + * + * @param rs - Resultset handle + * + * @note + * - OCI_GetCurrentRow() returns the current row number starting from 1 + * - If the resultset has not been fetched or if the resultset is empty, it returns 0 + * - If the resultset has been fully fetched, it returns the last fetched row number + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetCurrentRow +( + OCI_Resultset *rs +); + +/** + * @brief + * Return the number of columns in the resultset + * + * @param rs - Resultset handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetColumnCount +( + OCI_Resultset *rs +); + +/** + * @brief + * Return the column object handle at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @return + * - Column handle on success + * - NULL if index is out of bounds or on error + * + */ + +OCI_EXPORT OCI_Column * OCI_API OCI_GetColumn +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the column object handle from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * - Column handle on success or + * - NULL if no column found with the given name or on error + * + */ + +OCI_EXPORT OCI_Column * OCI_API OCI_GetColumn2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the index of the column in the result from its name + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @note + * Column indexes start with 1 in OCILIB + * + * @return + * Column index on success or zero on error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetColumnIndex +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the name of the given column + * + * @param col - Column handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ColumnGetName +( + OCI_Column *col +); + +/** + * @brief + * Return the type of the given column + * + * @param col - Column handle + * + * @note + * Possible values are : + * + * - OCI_CDT_NUMERIC : short, int, long long, float, double + * - OCI_CDT_DATETIME : OCI_Date * + * - OCI_CDT_TEXT : otext * + * - OCI_CDT_LONG : OCI_Long * + * - OCI_CDT_CURSOR : OCI_Statement * + * - OCI_CDT_LOB : OCI_Lob * + * - OCI_CDT_FILE : OCI_File * + * - OCI_CDT_TIMESTAMP : OCI_Timestamp * + * - OCI_CDT_INTERVAL : OCI_Interval * + * - OCI_CDT_RAW : void * + * - OCI_CDT_OBJECT : OCI_Object * + * - OCI_CDT_COLLECTION : OCI_Coll * + * - OCI_CDT_REF : OCI_Ref * + * - OCI_CDT_BOOLEAN : boolean + * + * @return + * The column type or OCI_CDT_UNKNOWN if index is out of bounds + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetType +( + OCI_Column *col +); + +/** + * @brief + * Return the charset form of the given column + * + * @param col - Column handle + * + * @note + * Possible values are : + * - OCI_CSF_NONE : the column is not an character or lob column + * - OCI_CSF_DEFAULT : the column has server default charset + * - OCI_CSF_NATIONAL : the column has national server charset + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetCharsetForm +( + OCI_Column *col +); + +/** + * @brief + * Return the Oracle SQL type name of the column data type + * + * @param col - Column handle + * + * @note + * For possible values, consults Oracle Documentation + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ColumnGetSQLType +( + OCI_Column *col +); + +/** + * @brief + * Return the Oracle SQL Full name including precision and size of the + * column data type + * + * @param col - Column handle + * @param buffer - buffer to store the full column type name and size + * @param len - max size of the buffer in characters + * + * @note + * This function returns a description that matches the one given by SQL*Plus + * + * @note + * Return the number of characters written into the buffer + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetFullSQLType +( + OCI_Column *col, + otext *buffer, + unsigned int len +); + +/** + * @brief + * Return the size of the column + * + * @note + * For all types, the size is expressed is bytes, excepted for character + * based columns that were created with a character based size or of type NCHAR/NVARCHAR + * + * @param col - Column handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetSize +( + OCI_Column *col +); + +/** + * @brief + * Return the scale of the column for numeric columns + * + * @param col - Column handle + * + */ + +OCI_EXPORT int OCI_API OCI_ColumnGetScale +( + OCI_Column *col +); + +/** + * @brief + * Return the precision of the column for numeric columns + * + * @param col - Column handle + * + */ + +OCI_EXPORT int OCI_API OCI_ColumnGetPrecision +( + OCI_Column *col +); + +/** + * @brief + * Return the fractional precision of the column for timestamp and interval columns + * + * @param col - Column handle + * + */ + +OCI_EXPORT int OCI_API OCI_ColumnGetFractionalPrecision +( + OCI_Column *col +); + +/** + * @brief + * Return the leading precision of the column for interval columns + * + * @param col - Column handle + * + */ + +OCI_EXPORT int OCI_API OCI_ColumnGetLeadingPrecision +( + OCI_Column *col +); + +/** + * @brief + * Return the nullable attribute of the column + * + * @param col - Column handle + * + * @return + * Return TRUE if the column is nullable otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ColumnGetNullable +( + OCI_Column *col +); + +/** + * @brief + * Return TRUE if the length of the column is character-length or FALSE if + * it is byte-length + * + * @param col - Column handle + * + * @note + * This was introduced in Oracle 9i. So for version that are not supporting this + * property, it always return FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ColumnGetCharUsed +( + OCI_Column *col +); + +/** + * @brief + * Return the column property flags + * + * @param col - Column handle + * + * For flags are: + * - OCI_CPF_NONE : The column has no flags or the OCI client does not support this call + * - OCI_CPF_IS_IDENTITY : + * - If Set, the column is an IDENTITY column + * - Otherwise, it is not an IDENTITY column + * - OCI_CPF_IS_GEN_ALWAYS (only if OCI_CPF_IS_IDENTITY is set) : + * - If set, means that the value is "ALWAYS GENERATED" + * - Otherwise mens that the value is "GENERATED BY" + * - OCI_CPF_IS_GEN_BY_DEFAULT_ON_NULL (only if OCI_CPF_IS_IDENTITY is set): + * - If set, means that the value is generated by default on NULL + * + * @note + * This was introduced in Oracle 12cR1. + * It is currently used for identifying Identity columns. + * For earlier versions, it always return OCI_CPF_NONE + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetPropertyFlags +( + OCI_Column *col +); + +/** +* @brief +* Return the column collation ID +* +* @param col - Column handle +* +* Possible values: +* - OCI_CCI_NONE +* - OCI_CCI_NLS_COMP +* - OCI_CCI_NLS_SORT +* - OCI_CCI_NLS_SORT_CI +* - OCI_CCI_NLS_SORT_AI +* - OCI_CCI_NLS_SORT_CS +* - OCI_CCI_NLS_SORT_VAR1 +* - OCI_CCI_NLS_SORT_VAR1_CI +* - OCI_CCI_NLS_SORT_VAR1_AI +* - OCI_CCI_NLS_SORT_VAR1_CS +* - OCI_CCI_BINARY +* - OCI_CCI_BINARY_CI +* - OCI_CCI_BINARY_AI +* +* @note +* This was introduced in Oracle 12cR2. +* For earlier versions, it always return OCI_CCI_NONE +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetCollationID +( + OCI_Column *col +); + +/** + * @brief + * Return the type information object associated to the column + * + * @param col - Column handle + * + * @note + * This call is used only for Named Object typed and collection columns. + * It returns NULL if the column is not a Named Object or a collection. + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_ColumnGetTypeInfo +( + OCI_Column *col +); + +/** + * @brief + * Return the OCILIB object subtype of a column + * + * @param col - Column handle + * + * @note + * This call is valid for the following OCILIB types: + * + * - OCI_CDT_LONG + * - OCI_CDT_LOB + * - OCI_CDT_FILE + * - OCI_CDT_TIMESTAMP + * - OCI_CDT_INTERVAL + * - OCI_CDT_NUMERIC + * + * For OCI_Long type the possible values are: + * - OCI_BLONG + * - OCI_CLONG + * + * For OCI_Lob type the possible values are: + * - OCI_BLOB + * - OCI_CLOB + * - OCI_NCLOB + * + * For OCI_File type the possible values are: + * - OCI_BFILE + * - OCI_CFILE + * + * For OCI_Timestamp type the possible values are: + * - OCI_TIMESTAMP + * - OCI_TIMESTAMP_TZ + * - OCI_TIMESTAMP_LTZ + * + * For OCI_Interval type the possible values are: + * - OCI_INTERVAL_YM + * - OCI_INTERVAL_DS + * + * For numeric columns the possible values are: + * - OCI_NUM_SHORT + * - OCI_NUM_INT + * - OCI_NUM_BIGINT + * - OCI_NUM_USHORT + * - OCI_NUM_UINT + * - OCI_NUM_BIGUINT + * - OCI_NUM_DOUBLE + * - OCI_NUM_FLOAT + * - OCI_NUM_NUMBER + * + * @warning + * For numeric columns, the value may be not accurate at all! + * OCI does not allow to find out the real SQL precise type of an numeric column (int, real, ...). + * OCI based libraries can only 'guess' some types in some situations : float, binary_float, binary_float, number. + * For example: + * - with the statement 'select 101 from dual', OCI would report numeric type NUMBER. + * - if a column is declared as "INT", OCI would report also NUMBER. + * + * + * @note + * For all other OCILIB types, it returns OCI_UNKNOWN + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ColumnGetSubType +( + OCI_Column *col +); + +/** + * @brief + * set the numeric data type of the given structure member (identified from position in the + * resultset) to retrieve when calling OCI_GetStruct() + * + * @param rs - Resultset handle + * @param index - Column position + * @param type - Numeric type + * + * @note + * Possible values for parameter 'type' : + * - OCI_NUM_SHORT + * - OCI_NUM_USHORT + * - OCI_NUM_INT + * - OCI_NUM_UINT + * - OCI_NUM_BIGINT + * - OCI_NUM_BIGUINT + * - OCI_NUM_DOUBLE + * - OCI_NUM_FLOAT + * - OCI_NUM_NUMBER + * + * @return + * Return TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetStructNumericType +( + OCI_Resultset *rs, + unsigned int index, + unsigned int type +); + +/** + * @brief + * set the numeric data type of the given structure member (identified from column name in the + * resultset) to retrieve when calling OCI_GetStruct() + * + * @param rs - Resultset handle + * @param name - Column name + * @param type - Numeric type + * + * @note + * Possible values for parameter 'type' : + * - OCI_NUM_SHORT + * - OCI_NUM_USHORT + * - OCI_NUM_INT + * - OCI_NUM_UINT + * - OCI_NUM_BIGINT + * - OCI_NUM_BIGUINT + * - OCI_NUM_DOUBLE + * - OCI_NUM_FLOAT + * - OCI_NUM_NUMBER + * + * @return + * Return TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetStructNumericType2 +( + OCI_Resultset *rs, + const otext *name, + unsigned int type +); + +/** + * @brief + * Return the row columns values into a single structure + * + * @param rs - Resultset handle + * @param row_struct - pointer to user row structure + * @param row_struct_ind - pointer to user indicator structure + * + * @note + * Structure members values are contextual to the current row. + * The returned values can get out of scope when the current row + * changes when calling any OCI_FecthXXX() calls + * + * @par User row structure + * + * The user structure must have the same members than the resultset. + * Each column in the resultset must have its equivalent in the structure. + * Fields must be in the same order. + * + * The mapping rules are : + * + * - LOBs (CLOB, NCLOB, BLOB) : OCI_Lob * + * - DATE : OCI_Date * + * - TIMESTAMPS : OCI_Timestamp * + * - INTERVALS : OCI_Interval * + * - LONG, LONG RAW : OCI_Long * + * - REFs : OCI_Ref * + * - CURSOR, RESULSET : OCI_Statement * + * - OBJECTS, UDT : OCI_Object * + * - Character columns (CHAR,VARCHAR, etc..) : otext * + * - All NUMERIC types : + * - default : big_int + * - user defined (see OCI_SetStructNumericType()) + * + * The user structure pointer is not mandatory + * + * @par User row indicator structure + + * This structure must have one boolean field per column in + * the resultset and respect in the same member order. + * + * If the value of the given member is TRUE, it means the value in + * the user row structure is NOT NULL, otherwise its NULL + * + * The user indicator structure pointer is mandatory + * + * @return + * Return TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_GetStruct +( + OCI_Resultset *rs, + void *row_struct, + void *row_struct_ind +); + +/** +* @brief +* Return the current Number value of the column at the given index in the resultset +* +* @param rs - Resultset handle +* @param index - Column position +* +* @note +* Column position starts at 1. +* +* @return +* The column current row value or 0 if index is out of bounds +* +*/ +OCI_EXPORT OCI_Number * OCI_API OCI_GetNumber +( + OCI_Resultset *rs, + unsigned int index +); + +/** +* @brief +* Return the current number value of the column from its name in the resultset +* +* @param rs - Resultset handle +* @param name - Column name +* +* @note +* The column name is case insensitive +* +* @return +* The column current row value or 0 if no column found with the given name +* +*/ + +OCI_EXPORT OCI_Number * OCI_API OCI_GetNumber2 +( + OCI_Resultset *rs, + const otext *name +); + + +/** + * @brief + * Return the current short value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT short OCI_API OCI_GetShort +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current short value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT short OCI_API OCI_GetShort2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current unsigned short value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT unsigned short OCI_API OCI_GetUnsignedShort +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current unsigned short value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT unsigned short OCI_API OCI_GetUnsignedShort2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current integer value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT int OCI_API OCI_GetInt +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current integer value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT int OCI_API OCI_GetInt2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current unsigned integer value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetUnsignedInt +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current unsigned integer value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetUnsignedInt2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current big integer value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT big_int OCI_API OCI_GetBigInt +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current big integer value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT big_int OCI_API OCI_GetBigInt2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current unsigned big integer value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0 if index is out of bounds + * + */ + +OCI_EXPORT big_uint OCI_API OCI_GetUnsignedBigInt +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current unsigned big integer value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0 if no column found with the given name + * + */ + +OCI_EXPORT big_uint OCI_API OCI_GetUnsignedBigInt2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current string value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @note + * OCI_GetString() performs an implicit conversion from the + * following data types: + * + * - Numerics (based on the current connection handle numeric format) + * - Binary doubles and floats (using the standard C Library functions) + * - OCI_Number (based on the current connection handle numeric format) + * - OCI_Date (based on the current connection handle date format) + * - OCI_Timestamp (based on the current connection handle date format) + * - OCI_Interval (based on Oracle default conversion) + * - OCI_Lob (for BLOBs, output is expressed in hexadecimal) + * - OCI_Long (for BLONGs, output is expressed in hexadecimal) + * - OCI_File ("[directory]/[name]" will be output) + * - OCI_Object (Textual SQL string representation) + * - OCI_Coll (Textual SQL string representation) + * - RAW buffer (expressed in hexadecimal) + * - OCI_Statement (SQL statement string or cursor name) + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetString +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current string value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT const otext * OCI_API OCI_GetString2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Copy the current raw value of the column at the given index into the specified buffer + * + * @param rs - Resultset handle + * @param index - Column position + * @param buffer - Buffer that receive the raw value + * @param len - Max size of the input buffer in bytes + * + * @note + * Column position starts at 1. + * + * @return + * Number of bytes copied into the buffer on SUCCESS otherwise 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetRaw +( + OCI_Resultset *rs, + unsigned int index, + void *buffer, + unsigned int len +); + +/** + * @brief + * Copy the current raw value of the column from its name into the specified buffer + * + * @param rs - Resultset handle + * @param name - Column name + * @param buffer - Buffer that receive the raw value + * @param len - Max size of the input buffer + * + * @note + * The column name is case insensitive + * + * @return + * Number of bytes copied into the buffer on SUCCESS otherwise 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetRaw2 +( + OCI_Resultset *rs, + const otext *name, + void *buffer, + unsigned int len +); + +/** + * @brief + * Return the current double value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0.O if index is out of bounds + * + */ + +OCI_EXPORT double OCI_API OCI_GetDouble +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current double value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0.0 if no column found with the given name + * + */ + +OCI_EXPORT double OCI_API OCI_GetDouble2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current float value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or 0.O if index is out of bounds + * + */ + +OCI_EXPORT float OCI_API OCI_GetFloat +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current float value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @note + * The column name is case insensitive + * + * @return + * The column current row value or 0.0 if no column found with the given name + * + */ + +OCI_EXPORT float OCI_API OCI_GetFloat2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current date value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_GetDate +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current date value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_GetDate2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current timestamp value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_GetTimestamp +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current timestamp value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_GetTimestamp2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current interval value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_GetInterval +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current interval value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_GetInterval2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current cursor value (Nested table) of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_GetStatement +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current cursor value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_GetStatement2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current lob value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_GetLob +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current lob value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_GetLob2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current File value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_GetFile +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current File value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_GetFile2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current Object value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_GetObject +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current Object value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_GetObject2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current Collection value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_GetColl +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current Collection value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_GetColl2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current Ref value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_GetRef +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current Ref value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_GetRef2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the current Long value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row value or NULL if index is out of bounds + * + */ + +OCI_EXPORT OCI_Long * OCI_API OCI_GetLong +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the current Long value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * The column current row value or NULL if no column found with the given name + * + */ + +OCI_EXPORT OCI_Long * OCI_API OCI_GetLong2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Check if the current row value is null for the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * TRUE if it's null otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IsNull +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the size of the value of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the returned value is expressed in + * number of characters. + * + * @return value size of 0 if the value is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetDataSize +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @brief + * Return the size of the value of the column from its name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @warning + * For binds of type OCI_CDT_TEXT (strings), the returned value is expressed in + * number of characters. + * + * @return value size of 0 if the value is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetDataSize2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Check if the current row value is null for the column of the given name in the resultset + * + * @param rs - Resultset handle + * @param name - Column name + * + * @return + * TRUE if it's null otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IsNull2 +( + OCI_Resultset *rs, + const otext *name +); + +/** + * @brief + * Return the statement handle associated with a resultset handle + * + * @param rs - resultset handle + * + */ + +OCI_EXPORT OCI_Statement * OCI_API OCI_ResultsetGetStatement +( + OCI_Resultset *rs +); + +/** + * @brief + * Return the current row data length of the column at the given index in the resultset + * + * @param rs - Resultset handle + * @param index - Column position + * + * @note + * Column position starts at 1. + * + * @return + * The column current row data length or 0 if index is out of bounds + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetDataLength +( + OCI_Resultset *rs, + unsigned int index +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiPlSql PL/SQL Support + * @{ + * + * OCILIB has a strong PL/SQL support : + * + * - Blocks, procedures and function can be used with OCILIB statements. + * - Ref cursors + * - Nested tables + * - Tables (indexed by integer types) + * - Access to the server side output generated by the DBMS_OUTPUT package + * + * Stored procedures/functions calls, blocks declarations are done like regular + * SQL calls using OCI_Prepare(), OCI_Execute(), OCI_ExecuteStmt() and + * OCI_ExecuteStmtFmt() functions. + * + * All PL/SQL statements must: + * + * - start with a 'begin' or 'declare' keyword + * - end with a 'end;' keyword + * + * Binding Host arrays to PL/SQL tables is done with OCI_BindArrayXXX() calls + * + * @par Using a PL/SQL block with OCILIB + * @include plsql_block.c + * + * @par Binding host arrays to PL/SQL tables parameters of a stored procedure + * @include plsql_table.c + * + * @par Retrieve the output generated by the dbms_output package on the server + * @include output.c + * + */ + +/** + * @brief + * Enable the server output + * + * @param con - Connection handle + * @param bufsize - server buffer max size (server side) + * @param arrsize - number of lines to retrieve per server round-trip + * @param lnsize - maximum size of one line + * + * @note + * This call is equivalent to the command 'set serveroutput on' in SQL*PLUS + * + * @note + * 'bufsize' minimum value is 2000, maximum 1000000 with Oracle < 10.2g and can be unlimited above + * + * @note + * 'lnsize' maximum value is 255 with Oracle < 10g R2 and 32767 above + * + * @warning + * If OCI_ServerEnableOutput() is not called, OCI_ServerGetOutput() will return NULL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ServerEnableOutput +( + OCI_Connection *con, + unsigned int bufsize, + unsigned int arrsize, + unsigned int lnsize +); + +/** + * @brief + * Disable the server output + * + * @param con - Connection handle + * + * @note + * After this call, OCI_ServerGetOutput() will return NULL. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ServerDisableOutput +( + OCI_Connection *con +); + +/** + * @brief + * Retrieve one line of the server buffer + * + * @param con - Connection handle + * + * @note + * Internally, OCILIB gets the server buffer through an array of lines in + * order to minimize round-trips with the server + * + * @return + * return a server output buffer line or NULL if the server buffer is empty + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ServerGetOutput +( + OCI_Connection *con +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiCollections Oracle collections (VARRAYS and Nested Tables) + * @{ + * + * OCILIB supports all Oracle collections: + * + * - PL/SQL Tables: only available in PL/SQL, unbounded, sparse arrays of + homogeneous elements. + * - VARRAYS : available in SQL and PL/SQL, they are bounded arrays of + * homogeneous elements + * - Nested Tables: available in SQL and PL/SQL, they are unbounded arrays of + * homogeneous elements and can become sparse through deletions + * + * PL/SQL tables are implemented by binding regular C arrays with the array + * interface (using OCI_BindArrayOfXXX() calls) + * + * VARRAYS and Nested tables are implemented in OCILIB with the type OCI_Coll. + * It's possible to bind and fetch VARRAYS and Nested tables using OCI_Coll handle. + * + * It's also possible to declare local collections based on some database type without using queries + * + * OCI (and thus OCILIB) offers the possibility to access collection elements : + * + * - directly by index (OCI_CollGetElem() and OCI_CollSetElem()) + * - using an iterator (OCI_Iter) to iterate through the collection + * (OCI_IterGetNext(), OCI_IterGetPrev()) + * + * Collection Items are implemented through the type OCI_Elem and use the series + * of calls OCI_ElemGetXXX() and OCI_ElemSetXXX() to manipulate elements + * content values + * + * @par Example + * @include coll.c + * + */ + +/** + * @brief + * Create a local collection instance + * + * @param typinf - Type info handle of the collection type descriptor + * + * @return + * Return the collection object handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_CollCreate +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a local collection + * + * @param coll - Collection handle + * + * @warning + * Only collection created with OCI_CollCreate() should be freed + * by OCI_CollFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollFree +( + OCI_Coll *coll +); + +/** + * @brief + * Create an array of Collection object + * + * @param con - Connection handle + * @param typinf - Object type (type info handle) + * @param nbelem - number of elements in the array + * + * @note + * see OCI_ObjectCreate() for more details + * + * @return + * Return the Collection handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Coll ** OCI_API OCI_CollArrayCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Free an array of Collection objects + * + * @param colls - Array of Collection objects + * + * @warning + * Only arrays of Collection created with OCI_CollArrayCreate() + * should be freed by OCI_CollArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollArrayFree +( + OCI_Coll **colls +); + +/** + * @brief + * Assign a collection to another one + * + * @param coll - Destination Collection handle + * @param coll_src - Source Collection handle + * + * @note + * Oracle proceeds to a deep copy of the collection content + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollAssign +( + OCI_Coll *coll, + OCI_Coll *coll_src +); + +/** + * @brief + * Return the type info object associated to the collection + * + * @param coll - Collection handle + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_CollGetTypeInfo +( + OCI_Coll *coll +); + +/** + * @brief + * Return the collection type + * + * @param coll - Collection handle + * + * @note + * Current collection types are: + * + * - OCI_COLL_VARRAY: Oracle VARRAY + * - OCI_COLL_NESTED_TABLE: Oracle Nested Table + * + * @return + * Collection type or OCI_UNKNOWN if the collection handle is null + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_CollGetType +( + OCI_Coll *coll +); + +/** + * @brief + * Returns the maximum number of elements of the given collection. + * + * @param coll - Collection handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_CollGetMax +( + OCI_Coll *coll +); + +/** + * @brief + * Returns the total number of elements of the given collection. + * + * @param coll - Collection handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_CollGetSize +( + OCI_Coll *coll +); + +/** + * @brief + * Returns the current number of elements of the given collection. + * + * @note + * - For VARRAYs, it returns the same value than OCI_CollGetSize() as VARRAYs cannot contains holes + * - For Nested Tables that are spare collections that can have holes, it returns the total number + * of elements minus the total of deleted elements + * + * @param coll - Collection handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_CollGetCount +( + OCI_Coll *coll +); + +/** + * @brief + * Trims the given number of elements from the end of the collection + * + * @param coll - Collection handle + * @param nb_elem - Number of elements to trim + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollTrim +( + OCI_Coll *coll, + unsigned int nb_elem +); + +/** + * @brief + * clear all items of the given collection + * + * @param coll - Collection handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollClear +( + OCI_Coll *coll +); + +/** + * @brief + * Return the element at the given position in the collection + * + * @param coll - Collection handle + * @param index - Index of the destination element + * + * @note + * Collection indexes start at position 1. + * + * @return + * Element handle on success otherwise FALSE + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_CollGetElem +( + OCI_Coll *coll, + unsigned int index +); + +/** + * @brief + * Return the element at the given position in the collection + * + * @param coll - Collection handle + * @param index - Index of the destination element + * @param elem - Element handle to hold the collection item data + * + * @note + * Collection indexes start at position 1. + * + * @return + * Element handle on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollGetElem2 +( + OCI_Coll *coll, + unsigned int index, + OCI_Elem *elem +); + +/** + * @brief + * Assign the given element value to the element at the given position in + * the collection + * + * @param coll - Collection handle + * @param index - Index of the destination element + * @param elem - Source element handle to assign + * + * @note + * Collection indexes start at position 1. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollSetElem +( + OCI_Coll *coll, + unsigned int index, + OCI_Elem *elem +); + +/** + * @brief + * Append the given element at the end of the collection + * + * @param coll - Collection handle + * @param elem - Element handle to add + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollAppend +( + OCI_Coll *coll, + OCI_Elem *elem +); + +/** + * @brief + * Convert a collection handle value to a string + * + * @param coll - Collection handle + * @param size - Destination string length pointer in characters + * @param str - Destination string + * + * @note + * In order to compute the needed string length, call the method with a NULL string + * Then call the method again with a valid buffer + * + * @note + * The resulting string is similar to the SQL*PLUS output for collections + * For RAWs and BLOBs attributes, their binary values are converted to hexadecimal strings + * + * @warning + * This convenient method shall not be used when performance matters. It is usually called twice (buffer length + * computation) and must also care about quotes within strings. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollToText +( + OCI_Coll *coll, + unsigned int *size, + otext *str +); + +/** + * @brief + * Delete the element at the given position in the Nested Table Collection + * + * @param coll - Collection handle + * @param index - Index of the element to delete + * + * @note + * Collection indexes start at position 1. + * + * @warning + * OCI_CollDeleteElem() is only valid for nested tables. + * + * @return + * - if the input collection is a nested table, it returns TRUE if the element + * is successfully deleted otherwise FALSE on error + * - if the input collection is a VARRAY, it always returns FALSE without spawning an exception + * + */ + +OCI_EXPORT boolean OCI_API OCI_CollDeleteElem +( + OCI_Coll *coll, + unsigned int index +); + +/** + * @brief + * Create an iterator handle to iterate through a collection + * + * @param coll - Collection handle + * + * @return + * Return the iterator handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Iter * OCI_API OCI_IterCreate +( + OCI_Coll *coll +); + +/** + * @brief + * Free an iterator handle + * + * @param iter - Iterator handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IterFree +( + OCI_Iter *iter +); + +/** + * @brief + * Get the next element in the collection + * + * @param iter - Iterator handle + * + * @return + * Element handle on success otherwise NULL if: + * - Empty collection + * - Iterator already positioned on the last collection element + * - An error occurred + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_IterGetNext +( + OCI_Iter *iter +); + +/** + * @brief + * Get the previous element in the collection + * + * @param iter - Iterator handle + * + * @return + * Element handle on success otherwise NULL if: + * - Empty collection + * - Iterator already positioned on the last collection element + * - An error occurred + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_IterGetPrev +( + OCI_Iter *iter +); + +/** + * @brief + * Get the current element in the collection + * + * @param iter - Iterator handle + * + * @return + * Element handle on success otherwise NULL if: + * - Empty collection + * - Iterator already positioned on the last collection element + * - An error occurred + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_IterGetCurrent +( + OCI_Iter *iter +); + +/** + * @brief + * Create a local collection element instance based on a collection type + * descriptor + * + * @param typinf - Type info handle + * + * @return + * Return the collection element handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Elem * OCI_API OCI_ElemCreate +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a local collection element + * + * @param elem - Element handle + * + * @warning + * Only element created with OCI_ElemCreate() should be freed + * by OCI_ElemFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemFree +( + OCI_Elem *elem +); + +/** +* @brief +* Return the boolean value of the given collection element +* +* @param elem - Element handle +* +* @warning +* OCI_ElemGetBoolean() returns a valid value only for collection elements of PL/SQL boolean type +* +* @return +* boolean value or FALSE on failure +* +*/ + +OCI_EXPORT boolean OCI_API OCI_ElemGetBoolean +( + OCI_Elem *elem +); + +/** +* @brief +* Return the number value of the given collection element +* +* @param elem - Element handle +* +* @return +* number handle or NULL on failure +* +*/ + +OCI_EXPORT OCI_Number* OCI_API OCI_ElemGetNumber +( + OCI_Elem *elem +); + +/** + * @brief + * Return the short value of the given collection element + * + * @param elem - Element handle + * + * @return + * Short value or 0 on failure + * + */ + +OCI_EXPORT short OCI_API OCI_ElemGetShort +( + OCI_Elem *elem +); + +/** + * @brief + * Return the unsigned short value of the given collection element + * + * @param elem - Element handle + * + * @return + * Unsigned short value or 0 on failure + * + */ + +OCI_EXPORT unsigned short OCI_API OCI_ElemGetUnsignedShort +( + OCI_Elem *elem +); + +/** + * @brief + * Return the int value of the given collection element + * + * @param elem - Element handle + * + * @return + * Int value or 0 on failure + * + */ + +OCI_EXPORT int OCI_API OCI_ElemGetInt +( + OCI_Elem *elem +); + +/** + * @brief + * Return the unsigned int value of the given collection element + * + * @param elem - Element handle + * + * @return + * Unsigned int value or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ElemGetUnsignedInt +( + OCI_Elem *elem +); + +/** + * @brief + * Return the big int value of the given collection element + * + * @param elem - Element handle + * + * @return + * Big int value or 0 on failure + * + */ + +OCI_EXPORT big_int OCI_API OCI_ElemGetBigInt +( + OCI_Elem *elem +); + +/** + * @brief + * Return the unsigned big int value of the given collection element + * + * @param elem - Element handle + * + * @return + * Unsigned big int value or 0 on failure + * + */ + +OCI_EXPORT big_uint OCI_API OCI_ElemGetUnsignedBigInt +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Double value of the given collection element + * + * @param elem - Element handle + * + * @return + * Double value or 0 on failure + * + */ + +OCI_EXPORT double OCI_API OCI_ElemGetDouble +( + OCI_Elem *elem +); + +/** + * @brief + * Return the float value of the given collection element + * + * @param elem - Element handle + * + * @return + * Double value or 0 on failure + * + */ + +OCI_EXPORT float OCI_API OCI_ElemGetFloat +( + OCI_Elem *elem +); + +/** + * @brief + * Return the String value of the given collection element + * + * @param elem - Element handle + * + * @return + * String value or NULL on failure + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ElemGetString +( + OCI_Elem *elem +); + +/** + * @brief + * Read the RAW value of the collection element into the given buffer + * + * @param elem - Element handle + * @param value - Buffer to store the RAW value + * @param len - Size of the buffer + * + * @return + * Number of bytes read from the RAW value or 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ElemGetRaw +( + OCI_Elem *elem, + void *value, + unsigned int len +); + +/** +* @brief +* Return the raw attribute value size of the given element handle +* +* @param elem - Element handle +* +* @return +* size in bytes of the RAW value or 0 on failure or wrong attribute type +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_ElemGetRawSize +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Date value of the given collection element + * + * @param elem - Element handle + * + * @return + * Date handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_ElemGetDate +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Timestamp value of the given collection element + * + * @param elem - Element handle + * + * @return + * Timestamp handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_ElemGetTimestamp +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Interval value of the given collection element + * + * @param elem - Element handle + * + * @return + * Interval handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_ElemGetInterval +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Lob value of the given collection element + * + * @param elem - Element handle + * + * @return + * Lob handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_ElemGetLob +( + OCI_Elem *elem +); + +/** + * @brief + * Return the File value of the given collection element + * + * @param elem - Element handle + * + * @return + * File handle or NULL on failure + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_ElemGetFile +( + OCI_Elem *elem +); + +/** + * @brief + * Return the object value of the given collection element + * + * @param elem - Element handle + * + * @return + * Object handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_ElemGetObject +( + OCI_Elem *elem +); + +/** + * @brief + * Return the collection value of the given collection element + * + * @param elem - Element handle + * + * @return + * Collection handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_ElemGetColl +( + OCI_Elem *elem +); + +/** + * @brief + * Return the Ref value of the given collection element + * + * @param elem - Element handle + * + * @return + * Ref handle or NULL on failure + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_ElemGetRef +( + OCI_Elem *elem +); + +/** +* @brief +* Set a boolean value to a collection element +* +* @param elem - Element handle +* @param value - Short value +* +*@warning +* OCI_ElemSetBoolean() is only valid value only for collection elements of PL / SQL boolean type +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_ElemSetBoolean +( + OCI_Elem *elem, + boolean value +); + +/** +* @brief +* Set a number value to a collection element +* +* @param elem - Element handle +* @param value - number value +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_ElemSetNumber +( + OCI_Elem *elem, + OCI_Number *value +); + +/** + * @brief + * Set a short value to a collection element + * + * @param elem - Element handle + * @param value - Short value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetShort +( + OCI_Elem *elem, + short value +); + +/** + * @brief + * Set a unsigned short value to a collection element + * + * @param elem - Element handle + * @param value - Unsigned short value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetUnsignedShort +( + OCI_Elem *elem, + unsigned short value +); + +/** + * @brief + * Set a int value to a collection element + * + * @param elem - Element handle + * @param value - Int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetInt +( + OCI_Elem *elem, + int value +); + +/** + * @brief + * Set a unsigned int value to a collection element + * + * @param elem - Element handle + * @param value - Unsigned int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetUnsignedInt +( + OCI_Elem *elem, + unsigned int value +); + +/** + * @brief + * Set a big int value to a collection element + * + * @param elem - Element handle + * @param value - big int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetBigInt +( + OCI_Elem *elem, + big_int value +); + +/** + * @brief + * Set a unsigned big_int value to a collection element + * + * @param elem - Element handle + * @param value - Unsigned big int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetUnsignedBigInt +( + OCI_Elem *elem, + big_uint value +); + +/** + * @brief + * Set a double value to a collection element + * + * @param elem - Element handle + * @param value - Double value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetDouble +( + OCI_Elem *elem, + double value +); + +/** + * @brief + * Set a float value to a collection element + * + * @param elem - Element handle + * @param value - float value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetFloat +( + OCI_Elem *elem, + float value +); + +/** + * @brief + * Set a string value to a collection element + * + * @param elem - Element handle + * @param value - String value + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetString +( + OCI_Elem *elem, + const otext *value +); + +/** + * @brief + * Set a RAW value to a collection element + * + * @param elem - Element handle + * @param value - Raw value + * @param len - Size of the raw value + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetRaw +( + OCI_Elem *elem, + void *value, + unsigned int len +); + +/** + * @brief + * Assign a Date handle to a collection element + * + * @param elem - Element handle + * @param value - Date Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetDate +( + OCI_Elem *elem, + OCI_Date *value +); + +/** + * @brief + * Assign a Timestamp handle to a collection element + * + * @param elem - Element handle + * @param value - Timestamp Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetTimestamp +( + OCI_Elem *elem, + OCI_Timestamp *value +); + +/** + * @brief + * Assign an Interval handle to a collection element + * + * @param elem - Element handle + * @param value - Interval Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetInterval +( + OCI_Elem *elem, + OCI_Interval *value +); + +/** + * @brief + * Assign a Collection handle to a collection element + * + * @param elem - Element handle + * @param value - Collection Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetColl +( + OCI_Elem *elem, + OCI_Coll *value +); + +/** + * @brief + * Assign an Object handle to a collection element + * + * @param elem - Element handle + * @param value - Object Handle + * + * @warning + * This function assigns a copy of the object to the given attribute. + * Any further modifications of the object passed as the parameter 'value' + * will not be reflected to object 's attribute set with this call + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetObject +( + OCI_Elem *elem, + OCI_Object *value +); + +/** + * @brief + * Assign a Lob handle to a collection element + * + * @param elem - Element handle + * @param value - Lob Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetLob +( + OCI_Elem *elem, + OCI_Lob *value +); + +/** + * @brief + * Assign a File handle to a collection element + * + * @param elem - Element handle + * @param value - File Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetFile +( + OCI_Elem *elem, + OCI_File *value +); + +/** + * @brief + * Assign a Ref handle to a collection element + * + * @param elem - Element handle + * @param value - Ref Handle + * + * @note + * passing a null pointer for value calls OCI_ElemSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetRef +( + OCI_Elem *elem, + OCI_Ref *value +); + +/** + * @brief + * Check if the collection element value is null + * + * @param elem - Element handle + * + * @return + * TRUE if it's null otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemIsNull +( + OCI_Elem *elem +); + +/** + * @brief + * Set a collection element value to null + * + * @param elem - Element handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ElemSetNull +( + OCI_Elem *elem +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiFeatureReturningInto Oracle Returning feature + * @{ + * + * OCILIB supports the Oracle feature 'Returning into' for DML statements. + * + * Let's Oracle talk about this features: + * + * @par + * 'Using the RETURNING clause with a DML statement allows you to essentially + * combine two SQL statements into one, possibly saving you a server round-trip. + * This is accomplished by adding an extra clause to the traditional UPDATE, + * INSERT, and DELETE statements. The extra clause effectively adds a query to + * the DML statement. In the OCI, the values are returned to the application + * through the use of OUT bind variables.' + * + * OCILIB implements this features by providing a set of functions that allows + * to register output placeholders for the returned values. + * Once the DML is executed with OCI_Execute(), the output returned data is + * available through a regular resultset object that can be fetched. + * + * @note + * Array binding interface is also supported with 'returning into' DML statement. + * Every iteration (or row of given arrays) generates an resultset object. + * Once a resultset is fetched, the next on can be retrieved with OCI_GetNextResultset() + * + * @par + * + * @note + * OCI_Long are not supported for 'returning into' clause .This is a limitation imposed by Oracle. + * + * @note + * OCI_Column objects retrieved from output OCI_Resultset have the following + * particularities: + * + * - their names are the provided bind names to the DML statement + * (by example, ':out1'). So any call to the functions OCI_GetXXX2() + * should be aware of it + * - The columns detailed SQL attributes might be not all set or accurate. By + * example, the scale and precision are not set, the SQL type is the one + * chosen by OCILIB regarding the OCILIB object data type and might be + * slightly different from the real one. + * + * @par Example + * @include returning.c + * + */ + +/** + * @brief + * Retrieve the next available resultset + * + * @param stmt - Statement handle + * + * @note + * it is only valid for the following statements: + * - Statements executing SQL UPDATE/DELETE using a RETURNING INTO clause + * - Statements implicitly returned from PL/SQL procedure or blocks (new feature in Oracle 12cR1) using + * DBMS_SQL.RETURN_RESULT() + * + * @note + * SQL statements with a 'returning' clause can return multiple resultsets. + * When arrays of program variables are binded to the statement, Oracle will + * execute the statement for every row (iteration). + * Each iteration generates a resultset that can be fetched like regular ones. + * + * @note + * Starting withOracle 12cR1, PL/SQ procedure and blocks ca return multiple implicit resultsets + * Refer to Oracle documentation for more information. + * + * @return + * A resultset handle on success otherwise NULL + * + */ + +OCI_EXPORT OCI_Resultset * OCI_API OCI_GetNextResultset +( + OCI_Statement *stmt +); + +/** +* @brief +* Register a register output bind placeholder +* +* @param stmt - Statement handle +* @param name - Output bind name +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_RegisterNumber +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a short output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterShort +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register an unsigned short output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterUnsignedShort +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register an integer output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterInt +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register an unsigned integer output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterUnsignedInt +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a big integer output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterBigInt +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register an unsigned big integer output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterUnsignedBigInt +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a string output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param len - Max length of single string (in characters) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterString +( + OCI_Statement *stmt, + const otext *name, + unsigned int len +); + +/** + * @brief + * Register an raw output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param len - Max length of the buffer (in bytes) + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterRaw +( + OCI_Statement *stmt, + const otext *name, + unsigned int len +); + +/** + * @brief + * Register a double output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterDouble +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a float output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterFloat +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a date output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterDate +( + OCI_Statement *stmt, + const otext *name +); + +/** + * @brief + * Register a timestamp output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param type - Timestamp type + * + * @note + * See OCI_TimestampCreate() for possible values of parameter 'type' + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterTimestamp +( + OCI_Statement *stmt, + const otext *name, + unsigned int type +); + +/** + * @brief + * Register an interval output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param type - Interval type + * + * @note + * See OCI_IntervalCreate() for possible values of parameter 'type' + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterInterval +( + OCI_Statement *stmt, + const otext *name, + unsigned int type +); + +/** + * @brief + * Register an object output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param typinf - Type info handle + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterObject +( + OCI_Statement *stmt, + const otext *name, + OCI_TypeInfo *typinf +); + +/** + * @brief + * Register a lob output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param type - Lob type + * + * @note + * See OCI_LobCreate() for possible values of parameter 'type' + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterLob +( + OCI_Statement *stmt, + const otext *name, + unsigned int type +); + +/** + * @brief + * Register a file output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param type - File type + * + * @note + * See OCI_FileCreate() for possible values of parameter 'type' + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterFile +( + OCI_Statement *stmt, + const otext *name, + unsigned int type +); + +/** + * @brief + * Register a Ref output bind placeholder + * + * @param stmt - Statement handle + * @param name - Output bind name + * @param typinf - Type info handle + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RegisterRef +( + OCI_Statement *stmt, + const otext *name, + OCI_TypeInfo *typinf +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiRowIds Oracle Rowids + * @{ + * + * OCILIB supports the Oracle ROWID type through C scalar string types (otext). + * + * - ROWIDs can be retrieved from resultset with OCI_GetString() + * - ROWIDs can be binded to statements with OCI_BindString() + * + * The maximum size of an ROWID buffer is defined by the constant OCI_SIZE_ROWID + * + * @par Example + * @include rowid.c + * + * @} + */ + +/** + * @defgroup OcilibCApiStatementControl Statements control + * @{ + * + * Those functions give extra information about OCILIB statements and can modify their behavior. + * + */ + +/** + * @brief + * Return the type of a SQL statement + * + * @param stmt - Statement handle + * + * @note + * Possible values are : + * + * - OCI_CST_SELECT : select statement + * - OCI_CST_UPDATE : update statement + * - OCI_CST_DELETE : delete statement + * - OCI_CST_INSERT : insert statement + * - OCI_CST_CREATE : create statement + * - OCI_CST_DROP : drop statement + * - OCI_CST_ALTER : alter statement + * - OCI_CST_BEGIN : begin (pl/sql) statement + * - OCI_CST_DECLARE : declare (pl/sql) statement + * - OCI_CST_CALL : kpu call + * + * @return + * The statement type on success or OCI_UNKOWN on error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetStatementType +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the fetch mode of a SQL statement + * + * @param stmt - Statement handle + * @param mode - fetch mode value + * + * @warning + * OCI_SetFetchMode() MUST be called before any OCI_ExecuteXXX() call + * + * @note + * Possible values are : + * - OCI_SFM_DEFAULT + * - OCI_SFM_SCROLLABLE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetFetchMode +( + OCI_Statement *stmt, + unsigned int mode +); + +/** + * @brief + * Return the fetch mode of a SQL statement + * + * @param stmt - Statement handle + * + * @note + * See OCI_SetFetchMode() for possible values + * Default value is OCI_SFM_DEFAULT + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetFetchMode +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the binding mode of a SQL statement + * + * @param stmt - Statement handle + * @param mode - binding mode value + * + * @note + * Possible values are : + * - OCI_BIND_BY_POS : position binding + * - OCI_BIND_BY_NAME : name binding + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetBindMode +( + OCI_Statement *stmt, + unsigned int mode +); + +/** + * @brief + * Return the binding mode of a SQL statement + * + * @param stmt - Statement handle + * + * @note + * See OCI_SetBindMode() for possible values + * Default value is OCI_BIND_BY_NAME + * + * @note + * if stmt is NULL, the return value is OCI_UNKNOWN + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetBindMode +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the current bind allocation mode that will be used for subsequent binding calls + * + * @param stmt - Statement handle + * @param mode - bind allocation mode value + * + * @note + * Possible values are : + * - OCI_BAM_EXTERNAL : bind variable are allocated by user code + * - OCI_BAM_INTERNAL : bind variable are allocated internally + * + * @warning + * This call has to be made after preparing a statement as OCI_Prepare() reset it by default to OCI_BAM_EXTERNAL. + * When calling an OCI_BindXXXX() call, this value is used and stored in the OCI_Bind object created during the bind call. + * Each bind can have is own allocation mode that is returned by OCI_BindGetAllocationMode() + * OCI_SetBindAllocation() can be called before each binding call if needed, resulting having some bind allocated externally and other ones internally. + * + * @note + * Refer to the section "Binding variables and arrays" of the documention about allocation mode as OCI_BAM_INTERNAL is not compatible with all bind calls + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetBindAllocation +( + OCI_Statement *stmt, + unsigned int mode +); + +/** + * @brief + * Return the current bind allocation mode used for subsequent binding calls + * + * @param stmt - Statement handle + * + * @note + * See OCI_SetBindAllocation() for possible values + * Default value is OCI_BAM_EXTERNAL + * + * @warning + * Each OCI_Bind object has its own allocation mode that may differ from the one returned by OCI_GetBindAllocation() + * The return value of OCI_GetBindAllocation() is the mode that will be used for any subsequent OCI_BindXXXX() calls + * + * @note + * if stmt is NULL, the return value is OCI_UNKNOWN + * + */ +OCI_EXPORT unsigned int OCI_API OCI_GetBindAllocation +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the number of rows fetched per internal server fetch call + * + * @param stmt - Statement handle + * @param size - number of rows to fetch + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetFetchSize +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the number of rows fetched per internal server fetch call + * + * @param stmt - Statement handle + * + * @note + * Default value is set to constant OCI_FETCH_SIZE + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetFetchSize +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the number of rows pre-fetched by OCI Client + * + * @param stmt - Statement handle + * @param size - number of rows to pre-fetch + * + * @note + * To turn off pre-fetching, set both attributes (size and memory) to 0. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetPrefetchSize +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the number of rows pre-fetched by OCI Client + * + * @param stmt - Statement handle + * + * @note + * Default value is set to constant OCI_PREFETCH_SIZE + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetPrefetchSize +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the amount of memory pre-fetched by OCI Client + * + * @param stmt - Statement handle + * @param size - amount of memory to fetch + * + * @note + * Default value is 0 and the pre-fetch size attribute is used instead. + * When both attributes are set (pre-fetch size and memory) and pre-fetch memory + * value can hold more rows than specified by pre-fetch size, OCI uses pre-fetch + * size instead. + * + * @note + * OCILIB set pre-fetch attribute to OCI_PREFETCH_SIZE when a statement is created. + * To setup a big value for OCI_SetPrefetchMemory(), you must call + * OCI_SetPrefetchSize() to 0 to make OCI consider this attribute. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetPrefetchMemory +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the amount of memory used to retrieve rows pre-fetched by OCI Client + * + * @param stmt - Statement handle + * + * @note + * Default value is 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetPrefetchMemory +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the LONG data type piece buffer size + * + * @param stmt - Statement handle + * @param size - maximum size for long buffer + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SetLongMaxSize +( + OCI_Statement *stmt, + unsigned int size +); + +/** + * @brief + * Return the LONG data type piece buffer size + * + * @param stmt - Statement handle + * + * @note + * Default value is set to constant OCI_SIZE_LONG + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetLongMaxSize +( + OCI_Statement *stmt +); + +/** + * @brief + * Set the long data type handling mode of a SQL statement + * + * @param stmt - Statement handle + * @param mode - long mode value + * + * @note + * Possible values are : + * + * - OCI_LONG_EXPLICIT : LONGs are explicitly handled by OCI_Long type + * - OCI_LONG_IMPLICIT : LONGs are implicitly mapped to string type in the + * limits of VARCHAR2 size capacity + * + * LONG RAWs can't be handled with OCI_LONG_IMPLICIT + */ + +OCI_EXPORT boolean OCI_API OCI_SetLongMode +( + OCI_Statement *stmt, + unsigned int mode +); + +/** + * @brief + * Return the long data type handling mode of a SQL statement + * + * @param stmt - Statement handle + * + * @note + * See OCI_SetLongMode() for possible values + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_GetLongMode +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the connection handle associated with a statement handle + * + * @param stmt - Statement handle + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_StatementGetConnection +( + OCI_Statement *stmt +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiLobs Internal Large Objects (LOBs) + * @{ + * + * Large Objects (LOBs) were introduced with Oracle 8i to replace LONGs + * + * Oracle OCI supplies a set APIs to manipulate this data type. + * + * OCILIB encapsulates this API by supplying: + * + * - An OCI_Lob C type + * - A set of really easy APIs to manipulate OCI_Lob objects + * + * OCILIB currently supports 3 types of Lobs : + * + * - BLOB : Binary LOBs (replacement for LONG RAW data type) + * - CLOB : Character LOBs (replacement for LONG data type) + * - NCLOB : National Character LOBs + * + * OCI_Lob objects can be : + * + * - Created as standalone instances + * - Used for in/out binding + * - Retrieved from select statements + * - Manipulated (copy, append, ...) + * + * @par Lobs > 4 Go + * + * Oracle 10g extended lobs by increasing maximum size from 4Go to 128 To. + * + * OCILIB, with version 2.1.0, supports now this new limit. + * For handling sizes and offsets up to 128 To, 64 bit integers are requested. + * + * So, A new scalar integer type has been introduced: big_uint (elderly lobsize_t). + * This type can be a 32 bits or 64 bits integer depending on : + * - Compiler support for 64 bits integers (C99 compiler, MS compilers) + * - Oracle client version + * + * big_uint will be a 64 bits integer : + * - if the compiler supports it + * - if OCILIB is build with option OCI_IMPORT_LINKAGE and the Oracle version is >= 10.1 + * - or OCILIB is build with option OCI_IMPORT_RUNTIME (oracle version is not known at + * compilation stage) + * + * @par Example + * @include lob.c + * + */ + +/** + * @brief + * Create a local temporary Lob instance + * + * @param con - Connection handle + * @param type - Lob type + * + * Supported lob types : + * + * - OCI_BLOB : Binary Lob + * - OCI_CLOB : Character Lob + * - OCI_NCLOB ! National Character Lob + * + * @return + * Return the lob handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_LobCreate +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Free a local temporary lob + * + * @param lob - Lob handle + * + * @warning + * Only lobs created with OCI_LobCreate() should be freed by OCI_LobFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobFree +( + OCI_Lob *lob +); + +/** + * @brief + * Create an array of lob object + * + * @param con - Connection handle + * @param type - Lob type + * @param nbelem - number of elements in the array + * + * @note + * see OCI_LobCreate() for more details + * + * @return + * Return the lob handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Lob ** OCI_API OCI_LobArrayCreate +( + OCI_Connection *con, + unsigned int type, + unsigned int nbelem +); + +/** +* @brief +* Free an array of lob objects +* +* @param lobs - Array of lob objects +* +* @warning +* Only arrays of lobs created with OCI_LobArrayCreate() should be freed +* by OCI_LobArrayFree() +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_LobArrayFree +( + OCI_Lob **lobs +); + +/** + * @brief + * Return the type of the given Lob object + * + * @param lob - Lob handle + * + * @note + * For possible values, see OCI_LobCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobGetType +( + OCI_Lob *lob +); + +/** + * @brief + * Perform a seek operation on the OCI_lob content buffer + * + * @param lob - Lob handle + * @param offset - Offset from current position (bytes or characters) + * @param mode - Seek mode + * + * Parameter 'mode' can be one of the following value : + * + * - OCI_SEEK_SET : set the lob current offset to the given absolute offset + * - OCI_SEEK_END : set the lob current offset to the end of the lob + * - OCI_SEEK_CUR : move the lob current offset to the number of bytes or + * characters given by parameter 'offset' + * + * @note + * - For CLOB and CLOB, offset in characters + * - For BLOB and BFILE, offset is in bytes + * + * @note + * Position in the Lob buffer starts at 0. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobSeek +( + OCI_Lob *lob, + big_uint offset, + unsigned int mode +); + +/** + * @brief + * Return the current position in the Lob content buffer + * + * @param lob - Lob handle + * + * @return + * Lob position (starting with 0) or 0 on failure + */ + +OCI_EXPORT big_uint OCI_API OCI_LobGetOffset +( + OCI_Lob *lob +); + +/** + * @brief + * [OBSOLETE] Read a portion of a lob into the given buffer + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer (in bytes or characters) + * + * @note + * Length is expressed in : + * - Bytes for BLOBs + * - Characters for CLOBs/NCLOBS + * + * @warning + * This call is obsolete ! Use OCI_LobRead2() instead. + * + * @return + * Number of bytes/characters read on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobRead +( + OCI_Lob *lob, + void *buffer, + unsigned int len +); + +/** + * @brief + * Read a portion of a lob into the given buffer + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param char_count - [in/out] Pointer to maximum number of characters + * @param byte_count - [in/out] Pointer to maximum number of bytes + * + * @note + * In input, 'char_count' and 'byte_count' are values to read into the buffer + * In output, 'char_count' and 'byte_count' are values read into the buffer + * + * @note + * For BLOBs, only the parameter 'byte_count' is used + * For CLOBs, both parameters can be used : + * In input : + * - if 'byte_count' is set to zero, it is computed from 'char_count' + * - if 'char_count' is set to zero, it is computed from 'byte_count' + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobRead2 +( + OCI_Lob *lob, + void *buffer, + unsigned int *char_count, + unsigned int *byte_count +); + +/** + * @brief + * [OBSOLETE] Write a buffer into a LOB + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer (in bytes or characters) + * + * @note + * Length is expressed in : + * - Bytes for BLOBs + * - Characters for CLOBs/NCLOBs + * + * @warning + * This call is obsolete ! Use OCI_LobWrite2() instead. + * + * @return + * Number of bytes / characters written on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobWrite +( + OCI_Lob *lob, + void *buffer, + unsigned int len +); + +/** + * @brief + * Write a buffer into a LOB + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param char_count - [in/out] Pointer to maximum number of characters + * @param byte_count - [in/out] Pointer to maximum number of bytes + * + * @note + * In input, 'char_count' and 'byte_count' are values to write from the buffer + * In output, 'char_count' and 'byte_count' are values written from the buffer + * + * @note + * For BLOBs, only the parameter 'byte_count' is used + * For CLOBs, both parameters can be used : + * In input : + * - if 'byte_count' is set to zero, it is computed from 'char_count' + * - if 'char_count' is set to zero, it is computed from 'byte_count' + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobWrite2 +( + OCI_Lob *lob, + void *buffer, + unsigned int *char_count, + unsigned int *byte_count +); + +/** + * @brief + * Truncate the given lob to a shorter length + * + * @param lob - Lob handle + * @param size - New length (in bytes or characters) + * + * @note + * Length is expressed in : + * - Bytes for BLOBs + * - Characters for CLOBs/NCLOBs + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobTruncate +( + OCI_Lob *lob, + big_uint size +); + +/** + * @brief + * Return the actual length of a lob + * + * @param lob - Lob handle + * + * @note + * The returned value is in bytes for BLOBS and characters for CLOBS/NCLOBs + * + */ + +OCI_EXPORT big_uint OCI_API OCI_LobGetLength +( + OCI_Lob *lob +); + +/** + * @brief + * Returns the chunk size of a LOB + * + * @param lob - Lob handle + * + * @note + * This chunk size corresponds to the chunk size used by the LOB data layer + * when accessing and modifying the LOB value. According to Oracle + * documentation, performance will be improved if the application issues + * read or write requests using a multiple of this chunk size + * + * @note + * The returned value is in bytes for BLOBS and characters for CLOBS/NCLOBs + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobGetChunkSize +( + OCI_Lob *lob +); + +/** + * @brief + * Erase a portion of the lob at a given position + * + * @param lob - Lob handle + * @param offset - Absolute position in source lob + * @param len - Number of bytes or characters to erase + * + * @note + * Absolute position starts at 0. + * Erasing means that spaces overwrite the existing LOB value. + * + * @return + * Number of bytes (BLOB) or characters (CLOB/NCLOB) erased on success + * otherwise 0 on failure + * + */ + +OCI_EXPORT big_uint OCI_API OCI_LobErase +( + OCI_Lob *lob, + big_uint offset, + big_uint len +); + +/** + * @brief + * Append a buffer at the end of a LOB + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer (in bytes or characters) + * + * @note + * Length is expressed in : + * - Bytes for BLOBs + * - Characters for CLOBs + * + * @return + * Number of bytes / characters written on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LobAppend +( + OCI_Lob *lob, + void *buffer, + unsigned int len +); + +/** + * @brief + * Append a buffer at the end of a LOB + * + * @param lob - Lob handle + * @param buffer - Pointer to a buffer + * @param char_count - [in/out] Pointer to maximum number of characters + * @param byte_count - [in/out] Pointer to maximum number of bytes + * + * @note + * In input, 'char_count' and 'byte_count' are values to write from the buffer + * In output, 'char_count' and 'byte_count' are values written from the buffer + * + * @note + * For BLOBs, only the parameter 'byte_count' is used + * For CLOBs, both parameters can be used : + * In input : + * - if 'byte_count' is set to zero, it is computed from 'char_count' + * - if 'char_count' is set to zero, it is computed from 'byte_count' + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobAppend2 +( + OCI_Lob *lob, + void *buffer, + unsigned int *char_count, + unsigned int *byte_count +); + +/** + * @brief + * Append a source LOB at the end of a destination LOB + * + * @param lob - Destination Lob handle + * @param lob_src - Source Lob handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobAppendLob +( + OCI_Lob *lob, + OCI_Lob *lob_src +); + +/** + * @brief + * Check if the given lob is a temporary lob + * + * @param lob - Lob handle + * + * @return + * TRUE if it's a temporary lob otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobIsTemporary +( + OCI_Lob *lob +); + +/** + * @brief + * Copy a portion of a source LOB into a destination LOB + * + * @param lob - Destination Lob handle + * @param lob_src - Source Lob handle + * @param offset_dst - Absolute position in destination lob + * @param offset_src - Absolute position in source lob + * @param count - Number of bytes or character to copy + * + * @note + * For character LOB (CLOB/NCLOBS) the parameters count, offset_dst and + * offset_src are expressed in characters and not in bytes. + * + * @note + * Absolute position starts at 0. + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobCopy +( + OCI_Lob *lob, + OCI_Lob *lob_src, + big_uint offset_dst, + big_uint offset_src, + big_uint count +); + +/** + * @brief + * Copy a portion of a source FILE into a destination LOB + * + * @param lob - Destination Lob handle + * @param file - Source File handle + * @param offset_dst - Absolute position in destination lob + * @param offset_src - Absolute position in source file + * @param count - Number of bytes to copy + * + * @note + * - For character LOB (CLOB/NCLOB) the parameter offset_src are expressed in + * characters and not in bytes. + * - Offset_src is always in bytes + * + * @note + * Absolute position starts at 0. + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobCopyFromFile +( + OCI_Lob *lob, + OCI_File *file, + big_uint offset_dst, + big_uint offset_src, + big_uint count +); + +/** + * @brief + * Open explicitly a Lob + * + * @param lob - Lob handle + * @param mode - open mode + * + * Possible values for mode are : + * + * - OCI_LOB_READONLY : read only access + * - OCI_LOB_READWRITE : read/write access + * + * @note + * - A call to OCI_LobOpen is not necessary to manipulate a Lob. + * - If a lob hasn't been opened explicitly, triggers are fired and + * indexes updated at every read/write/append operation + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobOpen +( + OCI_Lob *lob, + unsigned int mode +); + +/** + * @brief + * Close explicitly a Lob + * + * @param lob - Lob handle + * + * @note + * - A call to OCI_LobClose is not necessary to manipulate a Lob. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobClose +( + OCI_Lob *lob +); + +/** + * @brief + * Compare two lob handles for equality + * + * @param lob - Lob handle + * @param lob2 - Lob2 handle + * + * @return + * TRUE is the lobs are not null and equal otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobIsEqual +( + OCI_Lob *lob, + OCI_Lob *lob2 +); + +/** + * @brief + * Assign a lob to another one + * + * @param lob - Destination Lob handle + * @param lob_src - Source Lob handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobAssign +( + OCI_Lob *lob, + OCI_Lob *lob_src +); + +/** + * @brief + * Return the maximum size that the lob can contain + * + * @param lob - Lob handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT big_uint OCI_API OCI_LobGetMaxSize +( + OCI_Lob *lob +); + +/** + * @brief + * Flush Lob content to the server + * + * @param lob - Lob handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobFlush +( + OCI_Lob *lob +); + +/** + * @brief + * Enable / disable buffering mode on the given lob handle + * + * @param lob - Lob handle + * @param value - Enable/disable buffering mode + * + * @note + * Oracle "LOB Buffering Subsystem" allows client applications + * to speedup read/write of small buffers on Lobs Objects. + * Check Oracle Documentation for more details on "LOB Buffering Subsystem". + * This reduces the number of network round trips and LOB versions, thereby + * improving LOB performance significantly. + * + * @warning + * According to Oracle documentation the following operations are not permitted + * on Lobs when buffering is on : OCI_LobCopy(), OCI_LobAppend, OCI_LobErase(), + * OCI_LobGetLength(), OCI_LobTruncate() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LobEnableBuffering +( + OCI_Lob *lob, + boolean value +); + +/** +* @brief +* Retrieve connection handle from the lob handle +* +* @param lob - lob handle +* +*/ + +OCI_EXPORT OCI_Connection * OCI_API OCI_LobGetConnection +( + OCI_Lob *lob +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiFiles External Large Objects (FILEs) + * @{ + * + * External Large Objects (FILEs) were introduced with Oracle 8i + * + * Oracle OCI supplies a set APIs to manipulate this data type. + * + * OCILIB encapsulates this API by supplying: + * + * - An OCI_File C type + * - A set of really easy APIs to manipulate OCI_File objects + * + * OCILIB currently supports 2 types of Lobs : + * + * - BFILE : Binary files + * - CFILE : Character files + * + * @warning + * FILEs are read-only. + * + * OCI_Lob objects can be : + * + * - Created as standalone instances + * - Used for in/out binding + * - Retrieved from select statements + * - Used for reading server files content + * + * @par Files > 4 Go + * + * - New maximum file size limit (128 To) applies to OCI_Files objects. + * - See Internal Large Objects (LOBs) section for Files > 4 Go information + * + * @par Example + * @include file.c + * + */ + +/** + * @brief + * Create a file object instance + * + * @param con - Connection handle + * @param type - File type + * + * Supported file types : + * + * - OCI_BFILE : Binary file + * - OCI_CFILE : Character file + * + * @return + * Return the lob handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_FileCreate +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Free a local File object + * + * @param file - File handle + * + * @warning + * Only Files created with OCI_FileCreate() should be freed by OCI_FileFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileFree +( + OCI_File *file +); + +/** + * @brief + * Create an array of file object + * + * @param con - Connection handle + * @param type - File type + * @param nbelem - number of elements in the array + * + * @note + * see OCI_FileCreate() for more details + * + * @return + * Return the file handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_File ** OCI_API OCI_FileArrayCreate +( + OCI_Connection *con, + unsigned int type, + unsigned int nbelem +); + +/** +* @brief +* Free an array of file objects +* +* @param files - Array of file objects +* +* @warning +* Only arrays of lobs created with OCI_FileArrayCreate() should be freed by OCI_FileArrayFree() +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_FileArrayFree +( + OCI_File **files +); + +/** + * @brief + * Return the type of the given File object + * + * @param file - File handle + * + * @note + * For possible values, see OCI_FileCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_FileGetType +( + OCI_File *file +); + +/** + * @brief + * Perform a seek operation on the OCI_File content buffer + * + * @param file - File handle + * @param offset - Offset from current position + * @param mode - Seek mode + * + * Mode parameter can be one of the following value : + * + * - OCI_SEEK_SET : set the file current offset to the given absolute offset + * - OCI_SEEK_END : set the file current offset to the end of the lob + * - OCI_SEEK_CUR : move the file current offset to the number of bytes given by + * parameter 'offset' + * + * @note + * Position in the File buffer starts at 0. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileSeek +( + OCI_File *file, + big_uint offset, + unsigned int mode +); + +/** + * @brief + * Return the current position in the file + * + * @param file - File handle + * + * @return + * File position (starting with 0) or 0 on failure + */ + +OCI_EXPORT big_uint OCI_API OCI_FileGetOffset +( + OCI_File *file +); + +/** + * @brief + * Read a portion of a file into the given buffer + * + * @param file - File handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer in bytes + * + * @return + * Number of bytes read on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_FileRead +( + OCI_File *file, + void *buffer, + unsigned int len +); + +/** + * @brief + * Return the size in bytes of a file + * + * @param file - File handle + * + */ + +OCI_EXPORT big_uint OCI_API OCI_FileGetSize +( + OCI_File *file +); + +/** + * @brief + * Check if the given file exists on server + * + * @param file - File handle + * + * @note + * For local FILEs object, OCI_LobFileSetName() must be called before to set the filename to check + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileExists +( + OCI_File *file +); + +/** + * @brief + * Set the directory and file name of FILE handle + * + * @param file - File handle + * @param dir - File directory + * @param name - File name + *in + * @note + * - For local FILEs only + * - Files fetched from resultset can't be assigned a new directory and name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileSetName +( + OCI_File *file, + const otext *dir, + const otext *name +); + +/** + * @brief + * Return the directory of the given file + * + * @param file - File handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_FileGetDirectory +( + OCI_File *file +); + +/** + * @brief + * Return the name of the given file + * + * @param file - File handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_FileGetName +( + OCI_File *file +); + +/** + * @brief + * Open a file for reading + * + * @param file - File handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileOpen +( + OCI_File *file +); + +/** + * @brief + * Check if the specified file is opened within the file handle + * + * @param file - File handle + * + * @return + * TRUE if the file was opened with this handle otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileIsOpen +( + OCI_File *file +); + +/** + * @brief + * Close a file + * + * @param file - File handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileClose +( + OCI_File *file +); + +/** + * @brief + * Compare two file handle for equality + * + * @param file - File handle + * @param file2 - File2 handle + * + * @return + * TRUE is the lobs are not null and equal otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileIsEqual +( + OCI_File *file, + OCI_File *file2 +); + +/** + * @brief + * Assign a file to another one + * + * @param file - Destination File handle + * @param file_src - Source File handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_FileAssign +( + OCI_File *file, + OCI_File *file_src +); + +/** +* @brief +* Retrieve connection handle from the file handle +* +* @param file - file handle +* +*/ + +OCI_EXPORT OCI_Connection * OCI_API OCI_FileGetConnection +( + OCI_File *file +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiLongs Long objects + * @{ + * + * Long Objects encapsulate Oracle LONGs data types and were used to store large + * buffers in Oracle database. + * + * They're still supported but are depreciated. Oracle now provides a + * newer and better way to deal with data that needs large storage : LOBs + * + * OCILIB supports this data type because it was and still is widely used + * + * OCILIB provides a set of API for manipulating LONGs that is really close to + * the one provided for LOBs. + * + * OCILIB currently supports 3 types of Long Objects: + * + * - OCI_BLONG : LONG RAW columns + * - OCI_CLONG : LONG columns + * + * OCI_Lob objects can be : + * + * - Created as standalone instances + * - Used for in/out binding + * - Retrieved from select statement + * + * @par Example + * @include long.c + * + */ + +/** + * @brief + * Create a local temporary Long instance + * + * @param stmt - Statement handle + * @param type - Long type + * + * Supported lob types : + * + * - OCI_BLONG : Binary Long + * - OCI_CLONG : Character Long + * + * @return + * Return the long handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Long * OCI_API OCI_LongCreate +( + OCI_Statement *stmt, + unsigned int type +); + +/** + * @brief + * Free a local temporary long + * + * @param lg - Long handle + * + * @warning + * Only lobs created with OCI_LongCreate() should be freed by OCI_LongFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_LongFree +( + OCI_Long *lg +); + +/** + * @brief + * Return the type of the given Long object + * + * @param lg - Long handle + * + * @note + * For possible values, see OCI_LobCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LongGetType +( + OCI_Long *lg +); + +/** + * @brief + * Read a portion of a long into the given buffer [Obsolete] + * + * @param lg - Long handle + * @param buffer - Pointer to a buffer + * @param len - Length of the buffer in bytes / characters + * + * @note + * - From version 2.0.0, this function is obsolete because OCILIB fetches now + * all data during OCIFetchNext() call + * - So, this call reads now the internal OCI_Long object allocated buffer + * - The internal buffer can be directly accessed with OCI_LongGetBuffer() + * + * @note + * - For OCI_CLONG, parameter 'len' and returned value are expressed in characters + * - For OCI_BLONG, parameter 'len' and returned value are expressed in bytes + * + * @return + * - Number of bytes/characters read on success + * - 0 if there is nothing more to read + * - 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LongRead +( + OCI_Long *lg, + void *buffer, + unsigned int len +); + +/** + * @brief + * Write a buffer into a Long + * + * @param lg - Long handle + * @param buffer - the pointer to a buffer + * @param len - the length of the buffer in bytes (OCI_BLONG) or + * character (OCI_CLONG) + * + * @return + * Number of bytes (OCI_BLONG) / character (OCI_CLONG) written on success otherwise 0 on failure + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LongWrite +( + OCI_Long *lg, + void *buffer, + unsigned int len +); + +/** + * @brief + * Return the buffer size of a long object in bytes (OCI_BLONG) or character (OCI_CLONG) + * + * @param lg - Long handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_LongGetSize +( + OCI_Long *lg +); + +/** + * @brief + * Return the internal buffer of an OCI_Long object read from a fetch sequence + * + * @param lg - Long handle + * + */ + +OCI_EXPORT void * OCI_API OCI_LongGetBuffer +( + OCI_Long *lg +); + +/** +* @} +*/ + +/** +* @defgroup OcilibCApiOracleNumber Oracle NUMBER manipulation (optional) +* @{ +* +* OCILIB encapsulates Oracle SQL all Numeric types using C native data types. +* But it also provides an optional OCI_Number handle for manipulating and accessing Oracle NUMBER type. +* OCI_Number provides management for some special value that cannot be addressed in C such as positive +* and negative infinity. +* +* @par Example +* @include number.c +* +*/ + +/** +* @brief +* Create a local number object +* +* @param con - Connection handle +* +* @note +* Parameter 'con' can be NULL in order to manipulate numbers +* independently from database connections +* +* @return +* Return the number handle on success otherwise NULL on failure +* +*/ + +OCI_EXPORT OCI_Number * OCI_API OCI_NumberCreate +( + OCI_Connection *con +); + +/** +* @brief +* Free a number object +* +* @param number - Number handle +* +* @warning +* Only Numbers created with OCI_NumberCreate() should be freed by OCI_NumberFree() +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberFree +( + OCI_Number *number +); + +/** +* @brief +* Create an array of number object +* +* @param con - Connection handle +* @param nbelem - number of elements in the array +* +* @note +* see OCI_NumberCreate() for more details +* +* @return +* Return the number handle array on success otherwise NULL on failure +* +*/ + +OCI_EXPORT OCI_Number ** OCI_API OCI_NumberArrayCreate +( + OCI_Connection *con, + unsigned int nbelem +); + +/** +* @brief +* Free an array of number objects +* +* @param numbers - Array of number objects +* +* @warning +* Only arrays of numbers created with OCI_NumberArrayCreate() should be freed by OCI_NumberArrayFree() +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberArrayFree +( + OCI_Number **numbers +); + +/** +* @brief +* Assign the value of a number handle to another one +* +* @param number - Destination number handle +* @param number_src - Source number handle +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT int OCI_API OCI_NumberAssign +( + OCI_Number *number, + OCI_Number *number_src +); + +/** +* @brief +* Convert a number value from the given number handle to a string +* +* @param number - source number handle +* @param fmt - Number format +* @param size - Destination string size in characters +* @param str - Destination date string +* +* @note +* Output string can be one the following 'magic strings': +* - '~' for positive infinity +* - '-~' for negative infinity +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberToText +( + OCI_Number *number, + const otext *fmt, + int size, + otext *str +); + +/** +* @brief +* Convert a string to a number and store it in the given number handle +* +* @param number - Destination number handle +* @param str - Source number string +* @param fmt - Number format +* +* @note +* Input string can be one the following 'magic strings': +* - '~' for positive infinity +* - '-~' for negative infinity +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberFromText +( + OCI_Number *number, + const otext *str, + const otext *fmt +); + +/** +* @brief +* Return the number value content +* +* @param number - number handle +* +* @note +* Returned content is a buffer of 22 bytes corresponding to Oracle C native +* representation of NUMBER values +* See oracle Documentation of its layout +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT unsigned char * OCI_API OCI_NumberGetContent +( + OCI_Number *number +); + +/** +* @brief +* Assign the number value content +* +* @param number - number handle +* @param content - raw number content +* +* @note +* See OCI_NumberSetContent() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberSetContent +( + OCI_Number *number, + unsigned char *content +); + +/** +* @brief +* Assign the number value with the value of a native C numeric type +* +* @param number - number handle +* @param type - native C type to assign +* @param value - pointer to value to set +* +* @note +* Argument @param type can be : +* +* - OCI_NUM_SHORT : value is a pointer to a signed short +* - OCI_NUM_USHORT : value is a pointer to an unsigned short +* - OCI_NUM_INT : value is a pointer to a signed int +* - OCI_NUM_UINT : value is a pointer to an unsigned short +* - OCI_NUM_BIGINT : value is a pointer to a signed big_int +* - OCI_NUM_BIGUINT : value is a pointer to an unsigned big_uint +* - OCI_NUM_FLOAT : value is a pointer to an float +* - OCI_NUM_DOUBLE : value is a pointer to a double +* - OCI_NUM_NUMBER : value is a pointer to a OCI_Number +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberSetValue +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Assign the number value to a native C numeric type +* +* @param number - number handle +* @param type - native C type to assign +* @param value - pointer to a native C variable +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberGetValue +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Add the value of a native C numeric type to the given number +* +* @param number - number handle +* @param type - native C type of the variable +* @param value - pointer to a native C variable to add +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberAdd +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Subtract the value of a native C numeric type to the given number +* +* @param number - number handle +* @param type - native C type of the variable +* @param value - pointer to a native C variable to subtract +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberSub +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Multiply the given number with the value of a native C numeric +* +* @param number - number handle +* @param type - native C type of the variable +* @param value - pointer to a native C variable to multiply by +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberMultiply +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** +* @brief +* Divide the given number with the value of a native C numeric +* +* @param number - number handle +* @param type - native C type of the variable +* @param value - pointer to a native C variable to divide by +* +* @note +* See OCI_NumberSetValue() for more information +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_NumberDivide +( + OCI_Number *number, + unsigned int type, + void *value +); + +/** + * @brief + * Compares two number handles + * + * @param number1 - number1 handle + * @param number2 - number2 handle + * + * @return + * - -1 if number1 is smaller than number2, + * - 0 if they are equal + * - 1 if number1 is greater than number2. + * + */ + +OCI_EXPORT int OCI_API OCI_NumberCompare +( + OCI_Number *number1, + OCI_Number *number2 +); + +/** +* @} +*/ + +/** + * @} + */ + +/** + * @defgroup OcilibCApiDatetimes Date/time manipulation + * @{ + * + * OCILIB encapsulates Oracle SQL Date data type within OCI_Date structure + * + * Basically, the OCI_Date routines are wrappers around the Oracle OCIDate APIs + * + * @par Example + * @include date.c + * + */ + +/** + * @brief + * Create a local date object + * + * @param con - Connection handle + * + * @note + * From version 2.5.0, parameter 'con' can be NULL in order to manipulate dates + * independently from database connections + * + * @return + * Return the date handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_DateCreate +( + OCI_Connection *con +); + +/** + * @brief + * Free a date object + * + * @param date - Date handle + * + * @warning + * Only dates created with OCI_DateCreate() should be freed by OCI_DateFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateFree +( + OCI_Date *date +); + +/** + * @brief + * Create an array of date object + * + * @param con - Connection handle + * @param nbelem - number of elements in the array + * + * @note + * see OCI_DateCreate() for more details + * + * @return + * Return the date handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Date ** OCI_API OCI_DateArrayCreate +( + OCI_Connection *con, + unsigned int nbelem +); + +/** + * @brief + * Free an array of date objects + * + * @param dates - Array of date objects + * + * @warning + * Only arrays of dates created with OCI_DateArrayCreate() should be freed by OCI_DateArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateArrayFree +( + OCI_Date **dates +); + +/** + * @brief + * Add or subtract days to a date handle + * + * @param date - Date handle + * @param nb - Number of days to add/remove + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateAddDays +( + OCI_Date *date, + int nb +); + +/** + * @brief + * Add or subtract months to a date handle + * + * @param date - Date handle + * @param nb - Number of months to add/remove + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateAddMonths +( + OCI_Date *date, + int nb +); + +/** + * @brief + * Assign the value of a date handle to another one + * + * @param date - Destination Date handle + * @param date_src - Source Date handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT int OCI_API OCI_DateAssign +( + OCI_Date *date, + OCI_Date *date_src +); + +/** + * @brief + * Check if the given date is valid + * + * @param date - Date handle + * + * @return + * - Zero if date is valid + * - Any other value means the date is invalid + * + */ + +OCI_EXPORT int OCI_API OCI_DateCheck +( + OCI_Date *date +); + +/** + * @brief + * Compares two date handles + * + * @param date - Date1 handle + * @param date2 - Date2 handle + * + * @return + * - -1 if date1 is smaller than date2, + * - 0 if they are equal + * - 1 if date1 is greater than date2. + * + */ + +OCI_EXPORT int OCI_API OCI_DateCompare +( + OCI_Date *date, + OCI_Date *date2 +); + +/** + * @brief + * Return the number of days betWeen two dates + * + * @param date - Date1 handle + * @param date2 - Date2 handle + * + * @return + * Number of days on success otherwise OCI_ERROR on failure + * + */ + +OCI_EXPORT int OCI_API OCI_DateDaysBetween +( + OCI_Date *date, + OCI_Date *date2 +); + +/** + * @brief + * Convert a string to a date and store it in the given date handle + * + * @param date - Destination Date handle + * @param str - Source date string + * @param fmt - Date format + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateFromText +( + OCI_Date *date, + const otext *str, + const otext *fmt +); + +/** + * @brief + * Convert a Date value from the given date handle to a string + * + * @param date - source Date handle + * @param fmt - Date format + * @param size - Destination string size in characters + * @param str - Destination date string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateToText +( + OCI_Date *date, + const otext *fmt, + int size, + otext *str +); + +/** + * @brief + * Extract the date part from a date handle + * + * @param date - Date handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * @param day - Place holder for day value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateGetDate +( + OCI_Date *date, + int *year, + int *month, + int *day +); + +/** + * @brief + * Extract the time part from a date handle + * + * @param date - Date handle + * @param hour - Place holder for hour value + * @param min - Place holder for minute value + * @param sec - Place holder for second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateGetTime +( + OCI_Date *date, + int *hour, + int *min, + int *sec +); + +/** + * @brief + * Extract the date and time parts from a date handle + * + * @param date - Date handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * @param day - Place holder for day value + * @param hour - Place holder for hour value + * @param min - Place holder for minute value + * @param sec - Place holder for second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateGetDateTime +( + OCI_Date *date, + int *year, + int *month, + int *day, + int *hour, + int *min, + int *sec +); + +/** + * @brief + * Set the date portion if the given date handle + * + * @param date - Date handle + * @param year - Year value + * @param month - Month value + * @param day - Day value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateSetDate +( + OCI_Date *date, + int year, + int month, + int day +); + +/** + * @brief + * Set the time portion if the given date handle + * + * @param date - Date handle + * @param hour - Hour value + * @param min - Minute value + * @param sec - Second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateSetTime +( + OCI_Date *date, + int hour, + int min, + int sec +); + +/** + * @brief + * Set the date and time portions if the given date handle + * + * @param date - Date handle + * @param year - Year value + * @param month - Month value + * @param day - Day value + * @param hour - Hour value + * @param min - Minute value + * @param sec - Second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateSetDateTime +( + OCI_Date *date, + int year, + int month, + int day, + int hour, + int min, + int sec +); + +/** + * @brief + * Place the last day of month (from the given date) into the given date + * + * @param date - Date handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateLastDay +( + OCI_Date *date +); + +/** + * @brief + * Gets the date of next day of the week, after a given date + * + * @param date - Date handle + * @param day - Day of the week + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateNextDay +( + OCI_Date *date, + const otext *day +); + +/** + * @brief + * Return the current system date/time into the date handle + * + * @param date - Date handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateSysDate +( + OCI_Date *date +); + +/** + * @brief + * Convert a date from one zone to another zone + * + * @param date - Date handle + * @param zone1 - Source zone + * @param zone2 - Destination zone + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateZoneToZone +( + OCI_Date *date, + const otext *zone1, + const otext *zone2 +); + +/** + * @brief + * Affect an OCI_Date handle value to ISO C time data types + * + * @param date - Date handle + * @param ptm - Pointer to a structure tm to receive date/time values + * @param pt - Pointer to a time_t to hold the date/time in the time_t format + * + * @note + * Both parameters 'ptm' and 'p' are optional but one of them has to be provided. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateToCTime +( + OCI_Date *date, + struct tm *ptm, + time_t *pt +); + +/** + * @brief + * Affect ISO C time data types values to an OCI_Date handle + * + * @param date - Date handle + * @param ptm - Pointer to a structure tm that hold the date/time value + * @param t - Value (time_t) that hold the date/time in the time_t format + * + * @note + * Both parameters 'ptm' and 'p' are optional but one of them has to be provided. + * If 'ptm' is not null, its value is affected to the OCI_Timestamp handle, + * otherwise the value of 't' is used. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DateFromCTime +( + OCI_Date *date, + struct tm *ptm, + time_t t +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiTimestamps Timestamps and intervals manipulation + * @{ + * + * OCILIB encapsulates Oracle : + * + * - SQL timestamp data type within OCI_Timestamp structure + * - SQL interval data type within OCI_Interval structure + * + * Basically, the OCI_Timestamp and OCI_Interval routines are wrappers around + * the Oracle OCIDatetime and OCIInterval APIs + * + * @par Examples + * @include timestamp.c + * + */ + +/** + * @brief + * Create a local Timestamp instance + * + * @param con - Connection handle + * @param type - Timestamp type + * + * @note + * From version 2.5.0, parameter 'con' can be NULL in order to manipulate + * timestamps independently from database connections + * + * @note + * Timestamp type can be : + * + * - OCI_TIMESTAMP : timestamp + * - OCI_TIMESTAMP_TZ : timestamp with time zone + * - OCI_TIMESTAMP_LTZ : timestamp with local time zone + * + * @return + * Return the Timestamp handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_TimestampCreate +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Free an OCI_Timestamp handle + * + * @param tmsp - Timestamp handle + * + * @warning + * Only Timestamp created with OCI_TimestampCreate() should be freed by OCI_IntervalFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampFree +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Create an array of timestamp object + * + * @param con - Connection handle + * @param type - Timestamp type + * @param nbelem - number of elements in the array + * + * @note + * see OCI_TimestampCreate() for more details + * + * @return + * Return the timestamp handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Timestamp ** OCI_API OCI_TimestampArrayCreate +( + OCI_Connection *con, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Free an array of timestamp objects + * + * @param tmsps - Array of timestamp objects + * + * @warning + * Only arrays of timestamp created with OCI_TimestampArrayCreate() + * should be freed by OCI_TimestampArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampArrayFree +( + OCI_Timestamp **tmsps +); + +/** + * @brief + * Return the type of the given Timestamp object + * + * @param tmsp - Timestamp handle + * + * @note + * For possible values, see OCI_TimestampCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TimestampGetType +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Assign the value of a timestamp handle to another one + * + * @param tmsp - Destination Timestamp handle + * @param tmsp_src - Source Timestamp handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampAssign +( + OCI_Timestamp *tmsp, + OCI_Timestamp *tmsp_src +); + +/** + * @brief + * Check if the given timestamp is valid + * + * @param tmsp - Timestamp handle + * + * @return + * - Zero if the timestamp value is valid + * - Any other value means the timestamp value is invalid + * + */ + +OCI_EXPORT int OCI_API OCI_TimestampCheck +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Compares two timestamp handles + * + * @param tmsp - Timestamp1 handle + * @param tmsp2 - Timestamp2 handle + * + * @return + * - -1 if Timestamp1 is smaller than Timestamp2, + * - 0 if they are equal + * - 1 if Timestamp1 is greater than Timestamp2. + * + */ + +OCI_EXPORT int OCI_API OCI_TimestampCompare +( + OCI_Timestamp *tmsp, + OCI_Timestamp *tmsp2 +); + +/** + * @brief + * Set a timestamp handle value + * + * @param tmsp - Timestamp handle + * @param year - Year value + * @param month - Month value + * @param day - Day value + * @param hour - hour value + * @param min - minutes value + * @param sec - seconds value + * @param fsec - fractional part of seconds value + * @param time_zone - name of a time zone to use [optional] + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampConstruct +( + OCI_Timestamp *tmsp, + int year, + int month, + int day, + int hour, + int min, + int sec, + int fsec, + const otext *time_zone +); + +/** + * @brief + * Convert one timestamp value from one type to another. + * + * @param tmsp - Timestamp handle to convert + * @param tmsp_src - Timestamp handle to use for the type conversion + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampConvert +( + OCI_Timestamp *tmsp, + OCI_Timestamp *tmsp_src +); + +/** + * @brief + * Convert a string to a timestamp and store it in the given timestamp handle + * + * @param tmsp - Destination Timestamp handle + * @param str - Source date string + * @param fmt - Date format + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampFromText +( + OCI_Timestamp *tmsp, + const otext *str, + const otext *fmt +); + +/** + * @brief + * Convert a timestamp value from the given timestamp handle to a string + * + * @param tmsp - source Timestamp handle + * @param fmt - Timestamp format + * @param size - Destination string size in characters + * @param str - Destination date string + * @param precision - Precision for fractional part of the seconds + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampToText +( + OCI_Timestamp *tmsp, + const otext *fmt, + int size, + otext *str, + int precision +); + +/** + * @brief + * Extract the date part from a timestamp handle + * + * @param tmsp - Timestamp handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * @param day - Place holder for day value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetDate +( + OCI_Timestamp *tmsp, + int *year, + int *month, + int *day +); + +/** + * @brief + * Extract the time portion from a timestamp handle + * + * @param tmsp - Timestamp handle + * @param hour - Place holder for hour value + * @param min - Place holder for minute value + * @param sec - Place holder for second value + * @param fsec - Place holder for fractional part of second value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetTime +( + OCI_Timestamp *tmsp, + int *hour, + int *min, + int *sec, + int *fsec +); + +/** + * @brief + * Extract the date and time parts from a date handle + * + * @param tmsp - Date handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * @param day - Place holder for day value + * @param hour - Place holder for hour value + * @param min - Place holder for minute value + * @param sec - Place holder for second value + * @param fsec - Place holder for fractional part of seconds value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetDateTime +( + OCI_Timestamp *tmsp, + int *year, + int *month, + int *day, + int *hour, + int *min, + int *sec, + int *fsec +); + +/** + * @brief + * Return the time zone name of a timestamp handle + * + * @param tmsp - Timestamp handle + * @param size - Destination string size in characters + * @param str - Destination zone name string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetTimeZoneName +( + OCI_Timestamp *tmsp, + int size, + otext *str +); + +/** + * @brief + * Return the time zone (hour, minute) portion of a timestamp handle + * + * @param tmsp - Timestamp handle + * @param hour - Place holder for hour value + * @param min - Place holder for min value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampGetTimeZoneOffset +( + OCI_Timestamp *tmsp, + int *hour, + int *min +); + +/** + * @brief + * Add an interval value to a timestamp value of a timestamp handle + * + * @param tmsp - Timestamp handle + * @param itv - Interval handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampIntervalAdd +( + OCI_Timestamp *tmsp, + OCI_Interval *itv +); + +/** + * @brief + * Subtract an interval value from a timestamp value of a timestamp handle + * + * @param tmsp - Timestamp handle + * @param itv - Interval handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampIntervalSub +( + OCI_Timestamp *tmsp, + OCI_Interval *itv +); + +/** + * @brief + * Store the difference of two timestamp handles into an interval handle + * + * @param tmsp - Timestamp handle (subtrahend) + * @param tmsp2 - Timestamp2 handle (minuend) + * @param itv - Interval handle + * + * @note + * The function acts like tmsp - tmsp2 = itv + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampSubtract +( + OCI_Timestamp *tmsp, + OCI_Timestamp *tmsp2, + OCI_Interval *itv +); + +/** + * @brief + * Stores the system current date and time as a timestamp value with time zone + * into the timestamp handle. + * + * @param tmsp - Timestamp handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampSysTimestamp +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Affect an OCI_Timestamp handle value to ISO C time data types + * + * @param tmsp - Timestamp handle + * @param ptm - Pointer to a structure tm to receive date/time values + * @param pt - Pointer to a time_t to hold the date/time in the time_t format + * + * @note + * Both parameters 'ptm' and 'p' are optional but one of them has to be provided. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampToCTime +( + OCI_Timestamp *tmsp, + struct tm *ptm, + time_t *pt +); + +/** + * @brief + * Affect ISO C time data types values to an OCI_Timestamp handle + * + * @param tmsp - Timestamp handle + * @param ptm - Pointer to a structure tm that hold the date/time value + * @param t - Value (time_t) that hold the date/time in the time_t format + * + * @note + * Both parameters 'ptm' and 'p' are optional but one of them has to be provided. + * If 'ptm' is not null, its value is affected to the OCI_Timestamp handle, + * otherwise the value of 't' is used. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TimestampFromCTime +( + OCI_Timestamp *tmsp, + struct tm *ptm, + time_t t +); + +/** + * @brief + * Create a local interval object + * + * @param con - Connection handle + * @param type - Type of Interval + * + * @note + * From version 2.5.0, parameter 'con' can be NULL in order to manipulate + * intervals independently from database connections + * + * @note + * Interval type can be : + * - OCI_INTERVAL_YM : year / month interval + * - OCI_INTERVAL_DS : date/ time interval + * + * @return + * Return the Interval handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_IntervalCreate +( + OCI_Connection *con, + unsigned int type +); + +/** + * @brief + * Free an OCI_Interval handle + * + * @param itv - Interval handle + * + * @warning + * Only Intervals created with OCI_IntervalCreate() should be freed by + * OCI_IntervalFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalFree +( + OCI_Interval *itv +); + +/** + * @brief + * Create an array of Interval object + * + * @param con - Connection handle + * @param type - Type of Interval + * @param nbelem - number of elements in the array + * + * @note + * see OCI_IntervalCreate() for more details + * + * @return + * Return the Interval handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Interval ** OCI_API OCI_IntervalArrayCreate +( + OCI_Connection *con, + unsigned int type, + unsigned int nbelem +); + +/** + * @brief + * Free an array of Interval objects + * + * @param itvs - Array of Interval objects + * + * @warning + * Only arrays of Interval created with OCI_IntervalArrayCreate() should be freed by + * OCI_IntervalArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalArrayFree +( + OCI_Interval **itvs +); + +/** + * @brief + * Return the type of the given Interval object + * + * @param itv - Interval handle + * + * @note + * For possible values, see OCI_IntervalCreate() + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_IntervalGetType +( + OCI_Interval *itv +); + +/** + * @brief + * Assign the value of a interval handle to another one + * + * @param itv - Destination interval handle + * @param itv_src - Source interval handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalAssign +( + OCI_Interval *itv, + OCI_Interval *itv_src +); + +/** + * @brief + * Check if the given interval is valid + * + * @param itv - Interval handle + * + * @return + * - Zero if the interval value is valid + * - Any other value means the interval value is invalid + * + */ + +OCI_EXPORT int OCI_API OCI_IntervalCheck +( + OCI_Interval *itv +); + +/** + * @brief + * Compares two interval handles + * + * @param itv - Interval1 handle + * @param itv2 - Interval2 handle + * + * @return + * - -1 if interval1 is smaller than interval2, + * - 0 if they are equal + * - 1 if interval1 is greater than interval2. + * + */ + +OCI_EXPORT int OCI_API OCI_IntervalCompare +( + OCI_Interval *itv, + OCI_Interval *itv2 +); + +/** + * @brief + * Convert a string to an interval and store it in the given interval handle + * + * @param itv - Destination interval handle + * @param str - Source date string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalFromText +( + OCI_Interval *itv, + const otext *str +); + +/** + * @brief + * Convert an interval value from the given interval handle to a string + * + * @param itv - source Interval handle + * @param leading_prec - Precision of the leading part + * @param fraction_prec - Precision of the fractional part + * @param size - Destination string size in characters + * @param str - Destination date string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalToText +( + OCI_Interval *itv, + int leading_prec, + int fraction_prec, + int size, + otext *str +); + +/** + * @brief + * Correct an interval handle value with the given time zone + * + * @param itv - Interval handle + * @param str - Time zone name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalFromTimeZone +( + OCI_Interval *itv, + const otext *str +); + +/** + * @brief + * Return the day / time portion of an interval handle + * + * @param itv - Interval handle + * @param day - Place holder for day value + * @param hour - Place holder for hours value + * @param min - Place holder for minutes value + * @param sec - Place holder for seconds value + * @param fsec - Place holder for fractional part of seconds value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalGetDaySecond +( + OCI_Interval *itv, + int *day, + int *hour, + int *min, + int *sec, + int *fsec +); + +/** + * @brief + * Return the year / month portion of an interval handle + * + * @param itv - Interval handle + * @param year - Place holder for year value + * @param month - Place holder for month value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalGetYearMonth +( + OCI_Interval *itv, + int *year, + int *month +); + +/** + * @brief + * Set the day / time portion if the given interval handle + * + * @param itv - Interval handle + * @param day - day value + * @param hour - Hour value + * @param min - Minute value + * @param sec - Second value + * @param fsec - Fractional part of the seconds + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalSetDaySecond +( + OCI_Interval *itv, + int day, + int hour, + int min, + int sec, + int fsec +); + +/** + * @brief + * Set the year / month portion if the given Interval handle + * + * @param itv - Interval handle + * @param year - Year value + * @param month - Month value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalSetYearMonth +( + OCI_Interval *itv, + int year, + int month +); + +/** + * @brief + * Adds an interval handle value to another + * + * @param itv - Interval handle from witch to add + * @param itv2 - Interval handle to add + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalAdd +( + OCI_Interval *itv, + OCI_Interval *itv2 +); + +/** + * @brief + * Subtract an interval handle value from another + * + * @param itv - Interval handle from witch to remove + * @param itv2 - Interval handle to remove + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_IntervalSubtract +( + OCI_Interval *itv, + OCI_Interval *itv2 +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiUserTypes Oracle Named Types (Oracle OBJECTs) + * @{ + * + * OCILIB implements Oracle Named types (user types and built-in types) through + * the OCI_Object type. + * + * OTT and C structures are not required to use objects in OCILIB. + * + * In order to manipulate objects attributes, OCILIB proposes a set of functions + * to get/set properties for various supported types. + * + * Objects can be: + * - Created as standalone instances (transient objects) + * - Used for binding (persistent / transient objects) + * - Retrieved from select statements (persistent / embedded objects) + * + * References (Oracle type REF) are identifiers (smart pointers) to objects and + * are implemented in OCILIB with the type OCI_Ref. + * + * OCILIB implements Oracle REFs as strong typed Reference (underlying OCI REFs + * are weaker in terms of typing). + * It means it's mandatory to provide type information to: + * - create a local OCI_Ref handle. + * - register an OCI_Ref handle for a 'returning into' clause. + * + * @note + * See Oracle Database SQL Language Reference for more details about REF data type + * + * @warning + * Prior to v3.5.0, OCILIB relied on some OCI routines to set/get objects + * attributes. these OCI calls had known bugs in Unicode mode that has been fixed in Oracle 11gR2. + * From v3.5.0, OCILIB directly sets objects attributes and thus OCILIB objects + * can now be used in Unicode mode. + * + * @par Example : Inserting a local object into a table + * @include object.c + * + * @par Example : Using Object References + * @include ref.c + * + */ + +/** + * @brief + * Create a local object instance + * + * @param con - Connection handle + * @param typinf - Object type (type info handle) + * + * @return + * Return the object handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_ObjectCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a local object + * + * @param obj - Object handle + * + * @warning + * Only object created with OCI_ObjectCreate() should be freed + * by OCI_ObjectFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectFree +( + OCI_Object *obj +); + +/** + * @brief + * Create an array of Object objects + * + * @param con - Connection handle + * @param typinf - Object type (type info handle) + * @param nbelem - number of elements in the array + * + * @note + * see OCI_ObjectCreate() for more details + * + * @return + * Return the Object handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Object ** OCI_API OCI_ObjectArrayCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Free an array of Object objects + * + * @param objs - Array of Object objects + * + * @warning + * Only arrays of Object created with OCI_ObjectArrayCreate() + * should be freed by OCI_ObjectArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectArrayFree +( + OCI_Object **objs +); + +/** + * @brief + * Assign an object to another one + * + * @param obj - Destination Object handle + * @param obj_src - Source Object handle + * + * @note + * Oracle proceeds to a deep copy of the object content + * + * @note + * The two object handles must have the same type otherwise an exception is thrown + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectAssign +( + OCI_Object *obj, + OCI_Object *obj_src +); + +/** + * @brief + * Return the type of an object instance + * + * @param obj - Object handle + * + * @note + * Possibles values are : + * + * - OCI_OBJ_PERSISTENT: persistent object from the DB + * - OCI_OBJ_TRANSIENT : local temporary object + * - OCI_OBJ_VALUE : embedded object + * + * @return + * Instance type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ObjectGetType +( + OCI_Object *obj +); + +/** + * @brief + * Retrieve an Oracle Ref handle from an object and assign it to the given + * OCILIB OCI_Ref handle + * + * @param obj - Object handle + * @param ref - Ref handle + * + * @note + * The type information of the object and the ref must be the same, otherwise + * an exception is thrown + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectGetSelfRef +( + OCI_Object *obj, + OCI_Ref *ref +); + +/** + * @brief + * Return the type info object associated to the object + * + * @param obj - Object handle + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_ObjectGetTypeInfo +( + OCI_Object *obj +); + +/** + * @brief + * Return the boolean value of the given object attribute (ONLY for PL/SQL records) + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetBoolean() returns a valid value only for PL/SQL boolean based attributes + * + * @warning + * - ONLY supported by Oracle 12c and above ! + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectGetBoolean +( + OCI_Object *obj, + const otext *attr +); + +/** +* @brief +* Return the number value of the given object attribute +* +* @param obj - Object handle +* @param attr - Attribute name +* +* @note +* If the attribute is found in the object descriptor attributes list, then a +* data type check is performed for integrity. +* OCI_ObjectGetNumber() returns a valid value only for number based attributes +* +* @return +* Attribute value or NULL on failure or wrong attribute type +* +*/ + +OCI_EXPORT OCI_Number* OCI_API OCI_ObjectGetNumber +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the short value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetShort() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT short OCI_API OCI_ObjectGetShort +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the unsigned short value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetUnsignedShort() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT unsigned short OCI_API OCI_ObjectGetUnsignedShort +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the integer value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetInt() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT int OCI_API OCI_ObjectGetInt +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the unsigned integer value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetUnsignedInt() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_ObjectGetUnsignedInt +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the big integer value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetBigInt() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT big_int OCI_API OCI_ObjectGetBigInt +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the unsigned big integer value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetUnsignedBigInt() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT big_uint OCI_API OCI_ObjectGetUnsignedBigInt +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the double value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetDouble() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0.0 on failure or wrong attribute type + * + */ + +OCI_EXPORT double OCI_API OCI_ObjectGetDouble +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the float value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetFloat() returns a valid value only for integer and number based attributes + * + * @return + * Attribute value or 0.0 on failure or wrong attribute type + * + */ + +OCI_EXPORT float OCI_API OCI_ObjectGetFloat +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the string value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * The method can return a string value for any attributes types. + * It performs implicit string conversions using the same + * mechanisms than OCI_GetString(). See its documentation for more details. + * + * @return + * Attribute value or NULL on failure + * + */ + +OCI_EXPORT const otext * OCI_API OCI_ObjectGetString +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the raw attribute value of the given object attribute into the + * given buffer + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Destination buffer + * @param len - Max size to write into buffer + + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetRaw() copies data into the buffer only for raw based attributes + * + * @return + * Number of bytes written to the buffer or 0 on failure or wrong attribute type + * + */ + +OCI_EXPORT int OCI_API OCI_ObjectGetRaw +( + OCI_Object *obj, + const otext *attr, + void *value, + unsigned int len +); + +/** +* @brief +* Return the raw attribute value size of the given object attribute into the +* given buffer +* +* @param obj - Object handle +* @param attr - Attribute name +* +* @note +* If the attribute is found in the object descriptor attributes list, then a +* data type check is performed for integrity. +* +* @return +* size in bytes of the RAW value or 0 on failure or wrong attribute type +* +*/ + +OCI_EXPORT unsigned int OCI_API OCI_ObjectGetRawSize +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the date value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetDate() returns a valid value only for date based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_ObjectGetDate +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the timestamp value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetTimestamp() returns a valid value only for timestamps based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Timestamp * OCI_API OCI_ObjectGetTimestamp +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the interval value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetInterval() returns a valid value only for intervals based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Interval * OCI_API OCI_ObjectGetInterval +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the collection value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetColl() returns a valid value only for intervals based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Coll * OCI_API OCI_ObjectGetColl +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the Ref value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetRef() returns a valid value only for Refs based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_ObjectGetRef +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the object value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetObject() returns a valid value only for object based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_ObjectGetObject +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the lob value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetLob() returns a valid value only for lobs based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_Lob * OCI_API OCI_ObjectGetLob +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Return the file value of the given object attribute + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @note + * If the attribute is found in the object descriptor attributes list, then a + * data type check is performed for integrity. + * OCI_ObjectGetFile() returns a valid value only for files based attributes + * + * @return + * Attribute value or NULL on failure or wrong attribute type + * + */ + +OCI_EXPORT OCI_File * OCI_API OCI_ObjectGetFile +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Set an object attribute of type boolean (ONLY for PL/SQL records) + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - boolean value + * + * @warning + * - ONLY supported by Oracle 12c and above ! + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetBoolean +( + OCI_Object *obj, + const otext *attr, + boolean value +); + +/** +* @brief +* Set an object attribute of type number +* +* @param obj - Object handle +* @param attr - Attribute name +* @param value - number value +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetNumber +( + OCI_Object *obj, + const otext *attr, + OCI_Number *value +); + +/** + * @brief + * Set an object attribute of type short + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Short value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetShort +( + OCI_Object *obj, + const otext *attr, + short value +); + +/** + * @brief + * Set an object attribute of type unsigned short + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Unsigned short value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedShort +( + OCI_Object *obj, + const otext *attr, + unsigned short value +); + +/** + * @brief + * Set an object attribute of type int + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetInt +( + OCI_Object *obj, + const otext *attr, + int value +); + +/** + * @brief + * Set an object attribute of type unsigned int + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Unsigned int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedInt +( + OCI_Object *obj, + const otext *attr, + unsigned int value +); + +/** + * @brief + * Set an object attribute of type big int + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Big int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetBigInt +( + OCI_Object *obj, + const otext *attr, + big_int value +); + +/** + * @brief + * Set an object attribute of type unsigned big int + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Unsigned big int value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetUnsignedBigInt +( + OCI_Object *obj, + const otext *attr, + big_uint value +); + +/** + * @brief + * Set an object attribute of type double + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Double value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetDouble +( + OCI_Object *obj, + const otext *attr, + double value +); + +/** + * @brief + * Set an object attribute of type float + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Float value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetFloat +( + OCI_Object *obj, + const otext *attr, + float value +); + +/** + * @brief + * Set an object attribute of type string + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - String value + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetString +( + OCI_Object *obj, + const otext *attr, + const otext *value +); + +/** + * @brief + * Set an object attribute of type RAW + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Raw value + * @param len - Size of the raw value + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetRaw +( + OCI_Object *obj, + const otext *attr, + void *value, + unsigned int len +); + +/** + * @brief + * Set an object attribute of type Date + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Date Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetDate +( + OCI_Object *obj, + const otext *attr, + OCI_Date *value +); + +/** + * @brief + * Set an object attribute of type Timestamp + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Timestamp Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetTimestamp +( + OCI_Object *obj, + const otext *attr, + OCI_Timestamp *value +); + +/** + * @brief + * Set an object attribute of type Interval + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Interval Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetInterval +( + OCI_Object *obj, + const otext *attr, + OCI_Interval *value +); + +/** + * @brief + * Set an object attribute of type Collection + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Collection Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetColl +( + OCI_Object *obj, + const otext *attr, + OCI_Coll *value +); + +/** + * @brief + * Set an object attribute of type Object + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Object Handle + * + * @warning + * This function assigns a copy of the object to the given attribute. + * Any further modifications of the object passed as the parameter 'value' + * will not be reflected to object 's attribute set with this call + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetObject +( + OCI_Object *obj, + const otext *attr, + OCI_Object *value +); + +/** + * @brief + * Set an object attribute of type Lob + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Lob Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetLob +( + OCI_Object *obj, + const otext *attr, + OCI_Lob *value +); + +/** + * @brief + * Set an object attribute of type File + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - File Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetFile +( + OCI_Object *obj, + const otext *attr, + OCI_File *value +); + +/** + * @brief + * Set an object attribute of type Ref + * + * @param obj - Object handle + * @param attr - Attribute name + * @param value - Ref Handle + * + * @note + * passing a null pointer for value calls OCI_ObjectSetNull() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetRef +( + OCI_Object *obj, + const otext *attr, + OCI_Ref *value +); + +/** + * @brief + * Check if an object attribute is null + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @return + * FALSE if the attribute is not null otherwise TRUE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectIsNull +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Set an object attribute to null + * + * @param obj - Object handle + * @param attr - Attribute name + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectSetNull +( + OCI_Object *obj, + const otext *attr +); + +/** + * @brief + * Retrieve the underlying C (OTT/OCI style) structure of an OCI_Object handle + * + * @param obj - Object handle + * @param pp_struct - Address of a pointer that retrieve the C structure of data + * @param pp_ind - Address of a pointer that retrieve the C structure of indicators + * + * @note + * See Oracle OCI programming guide for more details about OTT structures. + * The members of these structures are OCI data types like OCINumber, OCIString + * that requires mixing OCILIB code and raw OCI code. + * OCI Object API headers have to be included to handle this data types using OCI object functions + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectGetStruct +( + OCI_Object *obj, + void **pp_struct, + void **pp_ind +); + +/** + * @brief + * Convert an object handle value to a string + * + * @param obj - Object handle + * @param size - Destination string length pointer in characters + * @param str - Destination string + * + * @note + * In order to compute the needed string length, call the method with a NULL string + * Then call the method again with a valid buffer + * + * @note + * The resulting string is similar to the SQL*PLUS output for UDTs (user types and objects) + * For RAWs and BLOBs attributes, their binary values are converted to hexadecimal strings + * + * @warning + * This convenient method shall not be used when performance matters. It is usually called twice (buffer length + * computation) and must also care about quotes within strings. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ObjectToText +( + OCI_Object *obj, + unsigned int *size, + otext *str +); + +/** + * @brief + * Create a local Ref instance + * + * @param con - Connection handle + * @param typinf - Ref type + * + * @return + * Return the Ref handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Ref * OCI_API OCI_RefCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a local Ref + * + * @param ref - Ref handle + * + * @warning + * Only Refs created with OCI_RefCreate() should be freed + * by OCI_RefFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefFree +( + OCI_Ref *ref +); + +/** + * @brief + * Create an array of Ref object + * + * @param con - Connection handle + * @param typinf - Object type (type info handle) + * @param nbelem - number of elements in the array + * + * @note + * see OCI_RefCreate() for more details + * + * @return + * Return the Ref handle array on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Ref ** OCI_API OCI_RefArrayCreate +( + OCI_Connection *con, + OCI_TypeInfo *typinf, + unsigned int nbelem +); + +/** + * @brief + * Free an array of Ref objects + * + * @param refs - Array of Ref objects + * + * @warning + * Only arrays of Ref created with OCI_RefArrayCreate() + * should be freed by OCI_RefArrayFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefArrayFree +( + OCI_Ref **refs +); + +/** + * @brief + * Assign a Ref to another one + * + * @param ref - Destination Ref handle + * @param ref_src - Source Ref handle + * + * @note + * The two Ref handles must have the same type otherwise an exception is thrown + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefAssign +( + OCI_Ref *ref, + OCI_Ref *ref_src +); + +/** + * @brief + * Return the type info object associated to the Ref + * + * @param ref - Ref handle + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_RefGetTypeInfo +( + OCI_Ref *ref +); + +/** + * @brief + * Returns the object pointed by the Ref handle. + * + * @param ref - Ref handle + * + * @return + * The object handle is the ref is not null otherwise NULL + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_RefGetObject +( + OCI_Ref *ref +); + +/** + * @brief + * Check if the Ref points to an object or not. + * + * @param ref - Ref handle + * + * @return + * TRUE if it does not point to a valid object otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefIsNull +( + OCI_Ref *ref +); + +/** + * @brief + * Nullify the given Ref handle + * + * @param ref - Ref handle + * + * @note + * this call clears the reference to object pointed by the Ref handle. + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_RefSetNull +( + OCI_Ref *ref +); + +/** + * @brief + * Returns the size of the hex representation of the given Ref handle + * + * @param ref - Ref handle + * + * @note + * the returned size is the number of character needed to store the + * hex representation of the Ref that can be retrieved with OCI_RefToText() + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_RefGetHexSize +( + OCI_Ref *ref +); + +/** + * @brief + * Converts a Ref handle value to a hexadecimal string. + * + * @param ref - Ref handle + * @param size - Destination string size in characters + * @param str - Destination string + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_RefToText +( + OCI_Ref *ref, + unsigned int size, + otext *str +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiAbort Aborting long operations + * @{ + * + * The Oracle OCI provides the ability to establish a server connection in : + * + * - blocking mode: each call to an OCI function returns control to the + * application when the call completes + * - non-blocking mode (based on polling paradigm) : the application have to + * call each function until its has completed its job + * + * OCILIB implements OCI in blocking mode. The application has to wait for OCI + * calls to complete to continue. + * + * Some operations can be long to be processed by the server. + * + * In order to cancel the current pending call, OCILIB provides OCI_Break() that + * cancel the last internal OCI Call and then raise an OCI abortion error code. + * + * @note + * Any call to OCI_Break() has to be done from a separate thread because the + * thread that has executed a long OCI call is waiting for its OCI call to complete. + * + * @par Example + * @include abort.c + * + */ + +/** + * @brief + * Perform an immediate abort of any currently Oracle OCI call + * + * @param con - connection handle + * + * @note + * The current call will abort and generate an error + * + * @return + * Returns FALSE if connection handle is NULL otherwise TRUE + */ + +OCI_EXPORT boolean OCI_API OCI_Break +( + OCI_Connection *con +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiMetadata Describing Schema Meta data and Objects + * @{ + * + * + * @par Example + * @include desc.c + * + */ + +/** + * @brief + * Retrieve the available type info information + * + * @param con - Connection handle + * @param name - Table/view name to query for + * @param type - Type of object + * + * @note + * Possible values for parameter type are : + * + * - OCI_UNKNOWN + * - OCI_TIF_TABLE + * - OCI_TIF_VIEW + * - OCI_TIF_TYPE + * + * @return + * - Type info handle on success + = - NULL if the object does not exist + * - NULL on failure + * + */ + +OCI_EXPORT OCI_TypeInfo * OCI_API OCI_TypeInfoGet +( + OCI_Connection *con, + const otext *name, + unsigned int type +); + +/** + * @brief + * Return the type of the type info object + * + * @param typinf - Type info handle + * + * @note + * Possible values for parameter type are : + * + * - OCI_UNKNOWM + * - OCI_TIF_TABLE + * - OCI_TIF_VIEW + * - OCI_TIF_TYPE + * + * @return + * Object type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TypeInfoGetType +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Retrieve connection handle from the type info handle + * + * @param typinf - Type info handle + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_TypeInfoGetConnection +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a type info object + * + * @param typinf - Type info handle + * + * @note + * this call is optional. + * OCI_TypeInfo object are internally tracked and + * automatically freed when their related connection is freed + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_TypeInfoFree +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Return the number of columns of a table/view/object + * + * @param typinf - Type info handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_TypeInfoGetColumnCount +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Return the column object handle at the given index in the table + * + * @param typinf - Type info handle + * @param index - Column position + * + * @return + * - Column handle on success + * - NULL if index is out of bounds or on error + * + */ + +OCI_EXPORT OCI_Column * OCI_API OCI_TypeInfoGetColumn +( + OCI_TypeInfo *typinf, + unsigned int index +); + +/** + * @brief + * Return the name described by the type info object + * + * @param typinf - Type info handle + * + */ + +OCI_EXPORT const otext * OCI_API OCI_TypeInfoGetName +( + OCI_TypeInfo *typinf +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiFormatting Formatted functions + * @{ + * + * OCILIB offers some smart routines that takes a variable number of arguments + * in order to minimize OCILIB function calls and reduce the amount of code lines + * + * On Windows platforms, the target programming language must support the __cdecl + * calling convention + * + * @note + * OCI_Immediate() and OCI_ImmediateFmt() support all OCILIB supported types + * for output result, except : + * - OCI_Long + * - OCI_Statement + * If a query output result contains one of these unsupported types, the function returns FALSE + * + * @note + * In the parameter list, every output placeholder MUST be preceded by + * an integer parameter that indicates the type of the placeholder + * in order to handle correctly the given pointer. + * + * Possible values for indicating placeholders type : + * + * - OCI_ARG_SHORT ------> short * + * - OCI_ARG_USHORT -----> unsigned short * + * - OCI_ARG_INT --------> int * + * - OCI_ARG_UINT -------> unsigned int* + * - OCI_ARG_BIGINT -----> big_int * + * - OCI_ARG_BIGUINT ----> unsigned big_int * + * - OCI_ARG_DOUBLE ----> double * + * - OCI_ARG_FLOAT ------> float * + * - OCI_ARG_NUMBER -----> OCI_Number * + * - OCI_ARG_TEXT -------> otext * + * - OCI_ARG_RAW --------> void * + * - OCI_ARG_DATETIME ---> OCI_Date * + * - OCI_ARG_LOB --------> OCI_Lob * + * - OCI_ARG_FILE -------> OCI_File * + * - OCI_ARG_TIMESTAMP --> OCI_Timestamp * + * - OCI_ARG_INTERVAL ---> OCI_Interval * + * - OCI_ARG_OBJECT -----> OCI_Object * + * - OCI_ARG_COLLECTION -> OCI_Coll * + * - OCI_ARG_REF --------> OCI_Ref * + * + * @note + * For output strings and Raws, returned data is copied to the given buffer + * instead of returning a pointer the real data. + * So these buffers must be big enough to hold the column content. No size check is performed. + * + * - For strings, only the real string is copied. + * - For Raws, the number of bytes copied is the column size + * + * @warning + * Input parameters for formatted function only support a restricted set of data types ! + * + * Supported input identifiers : + * + * - '%s' : (otext *) ----------> input string (quotes are added) + * - '%m' : (otext *) ----------> meta data string (no quotes added) + * - '%t' : (OCI_Date *) -------> Date + * - '%p' : (OCI_Timestamp *) --> timestamp + * - '%v' : (OCI_Interval *) ---> Interval + * - '%i' : (int) --------------> signed 32 bits integer + * - '%u' : (unsigned int) -----> unsigned 32 bits integer + * - '%li' : (big_int) ----------> signed 64 bits integer + * - '%lu' : (big_uint) ---------> unsigned 64 bits integer + * - '%hi' : (short) ------------> signed 16 bits integer + * - '%hu' : (unsigned short) ---> unsigned 16 bits integer + * - '%g' : (double, float ) ---> Numerics + * - '%n' : (OCI_Number *) -----> Number + * - '%r' : (OCI_Ref *) --------> Reference + * - '%o' : (OCI_Object *) -----> Object (not implemented yet) + * - '%c' : (OCI_Coll *) -------> collection (not implemented yet) + * + * @par Example + * @include format.c + * + */ + +/** + * @brief + * Perform 3 calls (prepare+execute+fetch) in 1 call + * + * @param con - Connection handle + * @param sql - SQL statement + * @param ... - List of program variables address to store the result of fetch operation + * + * @note + * Every output parameter MUST be preceded by an integer parameter that indicates the type + * of the placeholder in order to handle correctly the given pointer. + * + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_Immediate +( + OCI_Connection *con, + const otext *sql, + ... +); + +/** + * @brief + * Performs 4 call (prepare+bind+execute+fetch) in 1 call + * + * @param con - Connection handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL followed by the + * output variables addresses for the fetch operation + * + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_ImmediateFmt +( + OCI_Connection *con, + const otext *sql, + ... +); + +/** + * @brief + * Prepare a formatted SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_PrepareFmt +( + OCI_Statement *stmt, + const otext *sql, + ... +); + +/** + * @brief + * Execute a formatted SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL + * + * @return + * TRUE on success otherwise FALSE + * + * @warning + * If a SQL warning occurs: + * - the function returns TRUE + * - the SQL warning triggers the global error handler with an OCI_Error having its OCI_ErrorGetType() + * attribute set to OCI_ERR_WARNING + * - If OCILIB is initialized with the OCI_ENV_CONTEXT mode, OCI_GetLastError() will return the OCI_Error + * object corresponding to the warning + * + */ + +OCI_EXPORT boolean OCI_ExecuteStmtFmt +( + OCI_Statement *stmt, + const otext *sql, + ... +); + +/** + * @brief + * Parse a formatted SQL statement or PL/SQL block. + * + * @param stmt - Statement handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL + * + * @note + * This call sends the SQL or PL/SQL command to the server for parsing only. + * The command is not executed. + * This call is only useful to check is a command is valid or not. + * + * @note + * This call prepares the statement (internal call to OCI_Prepare()) and ask + * the Oracle server to parse its SQL or PL/SQL command. + * OCI_Execute() can be call after OCI_ParseFmt() in order to execute the + * statement, which means that the server will re-parse again the command. + * + * @warning + * Do not use OCI_ParseFmt() unless you're only interested in the parsing result + * because the statement will be parsed again when executed and thus leading to + * unnecessary server round-trips and less performance + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_ParseFmt +( + OCI_Statement *stmt, + const otext *sql, + ... +); + +/** + * @brief + * Describe the select list of a formatted SQL select statement. + * + * @param stmt - Statement handle + * @param sql - SQL statement + * @param ... - List of program values to format the SQL + * + * @note + * This call sends the SELECT SQL order to the server for retrieving the + * description of the select order only. + * The command is not executed. + * This call is only useful to retrieve information on the associated resultset + * Call OCI_GetResultet() after OCI_Describe() to access to SELECT list + * information + * + * @note + * This call prepares the statement (internal call to OCI_Prepare()) and ask + * the Oracle server to describe the output SELECT list. + * OCI_Execute() can be call after OCI_Desbribe() in order to execute the + * statement, which means that the server will parse, and describe again the SQL + * order. + * + * @warning + * Do not use OCI_Desbribe() unless you're only interested in the resultset + * information because the statement will be parsed again when executed and thus + * leading to unnecessary server round-trips and less performance + * + * @return + * TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_DescribeFmt +( + OCI_Statement *stmt, + const otext *sql, + ... +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiHashTables Hash tables + * @{ + * + * OCILIB uses hash tables internally for index/name columns mapping. + * + * OCILIB makes public its hash table’s implementation public for general purpose + * uses. + * + * OCI_HashTable objects manage string keys / values that can be : + * + * - integers + * - strings + * - pointers + * + * This hash table implementation : + * + * - handle collisions + * - allows multiple values per key + * + * @par Internal conception + * + * - The hash table is composed of an array of slots. + * - Each slot can hold a linked list of entries (one per key) + * - Each entry can hold a linked list of values + * + * @note + * - The internal hash function computes the index in the array where the entry + * has to be inserted/looked up. + * + * + * @note + * Collisions are handled by chaining method. + * + * @include hash.c + * + */ + +/** + * @brief + * Create a hash table + * + * @param size - size of the hash table + * @param type - type of the hash table + * + * @note + * Parameter can be one of the following values : + * + * - OCI_HASH_STRING : string values + * - OCI_HASH_INTEGER : integer values + * - OCI_HASH_POINTER : pointer values + * + * @return + * Hash handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_HashTable * OCI_API OCI_HashCreate +( + unsigned int size, + unsigned int type +); + +/** + * @brief + * Destroy a hash table + * + * @param table - Table handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_HashFree +( + OCI_HashTable *table +); + +/** + * @brief + * Return the size of the hash table + * + * @param table - Table handle + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_HashGetSize +( + OCI_HashTable *table +); + +/** + * @brief + * Return the type of the hash table + * + * @param table - Table handle + * + * @note + * the return value can be one of the following values : + * + * - OCI_HASH_STRING : string values + * - OCI_HASH_INTEGER : integer values + * - OCI_HASH_POINTER : pointer values + * + * @return + * Hash table data type or OCI_UNKNOWN the input handle is NULL + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_HashGetType +( + OCI_HashTable *table +); + +/** + * @brief + * Add a pair string key / string value to the hash table + * + * @param table - Table handle + * @param key - String key + * @param value - string value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_HashAddString +( + OCI_HashTable *table, + const otext *key, + const otext *value +); + +/** + * @brief + * Return the string value associated to the given key + * + * @param table - Table handle + * @param key - String key + * + * @return + * Stored string associated with the key otherwise NULL + * + */ + +OCI_EXPORT const otext * OCI_API OCI_HashGetString +( + OCI_HashTable *table, + const otext *key +); + +/** + * @brief + * Adds a pair string key / integer value to the hash table + * + * @param table - Table handle + * @param key - String key + * @param value - Integer value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_HashAddInt +( + OCI_HashTable *table, + const otext *key, + int value +); + +/** + * @brief + * Return the integer value associated to the given key + * + * @param table - Table handle + * @param key - String key + * + * @return + * Stored integer associated with the key otherwise 0 + * + */ + +OCI_EXPORT int OCI_API OCI_HashGetInt +( + OCI_HashTable *table, + const otext *key +); + +/** + * @brief + * Adds a pair string key / pointer value to the hash table + * + * @param table - Table handle + * @param key - String key + * @param value - Pointer value + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_HashAddPointer +( + OCI_HashTable *table, + const otext *key, + void *value +); + +/** + * @brief + * Return a pointer associated with the given key + * + * @param table - Table handle + * @param key - String key + * + * @return + * Stored pointer associated with the key otherwise NULL + * + */ + +OCI_EXPORT void * OCI_API OCI_HashGetPointer +( + OCI_HashTable *table, + const otext *key +); + +/** + * @brief + * Lookup for an entry matching the key in the table + * + * @param table - Table handle + * @param key - String key + * @param create - Do create the entry if not exists + * + * @return + * Entry handle if key found/added otherwise NULL + * + */ + +OCI_EXPORT OCI_HashEntry * OCI_API OCI_HashLookup +( + OCI_HashTable *table, + const otext *key, + boolean create +); + +/** + * @brief + * Return the first hash slot that matches the key + * + * @param table - Table handle + * @param key - String key + * + * @return + * Slot handle if key found otherwise NULL + * + */ + +OCI_EXPORT OCI_HashValue * OCI_API OCI_HashGetValue +( + OCI_HashTable *table, + const otext *key +); + +/** + * @brief + * Return the entry slot of the hash table internal list at the given position + * + * @param table - Table handle + * @param index - index + * + * @warning + * Index start at at + * + * @return + * Slot handle otherwise NULL + * + */ + +OCI_EXPORT OCI_HashEntry * OCI_API OCI_HashGetEntry +( + OCI_HashTable *table, + unsigned int index +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiThreading Threads and mutexes + * @{ + * + * Oracle proposes a portable implementation of Mutex and Thread objects + * + * OCILIB implements these OCI features for portable multi-threading support. + * + * Mutexes are designed for mutual exclusion between thread in order to lock resources temporarily + * + * Thread keys can be seen as process-wide variables that have a thread-specific + * values. It allows to create a unique key identified by a name (string) that + * can store values specific to each thread. + * + * OCILIB exposes the types OCI_Mutex, OCI_Thread + * + * @warning + * OCILIB MUST be initialized with OCI_ENV_THREADED to enable threads support + * + * @warning + * OCI_Thread relies on Oracle API which uses natives threading capabilities of + * the supported platform + * + * @warning + * Using OCI_Mutex : + * - On Microsoft Windows, a thread can call OCI_MutexAcquire() more than once + * without any blocking. Just be sure that there is an OCI_MutexRelease() for + * every OCI_MutexAcquire() call + * - On Unix systems, a thread MUST call OCI_MutexRelease() after every call to + * OCI_MutexAcquire() in order to be able to call OCI_MutexAcquire() again. If + * not, it will be blocked... + * + * @par Example + * @include thread.c + * + */ + +/** + * @brief + * Create a Mutex object + * + * @return + * Mutex handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Mutex * OCI_API OCI_MutexCreate +( + void +); + +/** + * @brief + * Destroy a mutex object + * + * @param mutex - Mutex handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MutexFree +( + OCI_Mutex *mutex +); + +/** + * @brief + * Acquire a mutex lock + * + * @param mutex - Mutex handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MutexAcquire +( + OCI_Mutex *mutex +); + +/** + * @brief + * Release a mutex lock + * + * @param mutex - Mutex handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MutexRelease +( + OCI_Mutex *mutex +); + +/** + * @brief + * Create a Thread object + * + * @return + * Thread handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Thread * OCI_API OCI_ThreadCreate +( + void +); + +/** + * @brief + * Destroy a thread object + * + * @param thread - Thread handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadFree +( + OCI_Thread *thread +); + +/** + * @brief + * Execute the given routine within the given thread object + * + * @param thread - Thread handle + * @param proc - routine to execute + * @param arg - parameter to pass to the routine + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadRun +( + OCI_Thread *thread, + POCI_THREAD proc, + void *arg +); + +/** + * @brief + * Join the given thread + * + * @param thread - Thread handle + * + * @note + * This function waits for the given thread to finish + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadJoin +( + OCI_Thread *thread +); + +/** + * @brief + * Create a thread key object + * + * @param name - Thread key name + * @param destfunc - Thread key value destructor function + * + * @note + * Parameter proc is optional. It's called when the thread terminates to allow + * the program to deal with the thread specific value of the key + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadKeyCreate +( + const otext *name, + POCI_THREADKEYDEST destfunc +); + +/** + * @brief + * Set a thread key value + * + * @param name - Thread key name + * @param value - user value to set + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_ThreadKeySetValue +( + const otext *name, + void *value +); + +/** + * @brief + * Get a thread key value + * + * @param name - Thread key name + * + * @return + * Thread key value on success otherwise FALSE + * + */ + +OCI_EXPORT void * OCI_API OCI_ThreadKeyGetValue +( + const otext *name +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApidirectPath Direct Path loading + * @{ + * + * OCILIB (from version 3.2.0) support the OCI direct Path API. + * + * Actual implementation of direct path API does not support the following + * elements : + * - Objects data types (User Defined Types and Object References) + * - Object tables + * - Nested tables + * - SQL String functions + * + * All scalar data types (numerics, characters and date/time), including LOBs + * and LONG types are supported + * + * @par Oracle direct API features (from Oracle Documentation) + * + * The direct path load interface allows an application to access the direct path + * load engine of the Oracle database server to perform the functions of the + * Oracle SQL*Loader utility. + * This functionality provides the ability to load data from external files + * into Oracle database objects, either a table or a partition of a partitioned + * table. + * The OCI direct path load interface has the ability to load multiple rows by + * loading a direct path stream which contains data for multiple rows. + * + * @par Oracle direct API limitation (from Oracle Documentation) + * The direct path load interface has the following limitations which are the + * same as SQL*Loader: + * - triggers are not supported + * - check constraints are not supported + * - referential integrity constraints are not supported + * - clustered tables are not supported + * - loading of remote objects is not supported + * - user-defined types are not supported + * - LOBs must be specified after all scalar columns + * - LONGs must be specified last + * + * @warning + * + * Its recommended to use direct path interface with an Oracle client that is + * the same version than the database. With version < 10g, it is mandatory + * regarding that it causes segmentation faults and it's known from Oracle that + * advices to use the same version for client and server (see metalink KB) + * + * @par How to use direct path + * + * - 1 : Create a direct path handle with OCI_DirPathCreate() + * - 2 : Set (optional) some direct path load attributes + * - 3 : Describe the columns to load with OCI_DirPathSetColumn() + * - 4 : Populate data with OCI_DirPathSetEntry() + * - 5 : Convert the data with OCI_DirPathConvert() + * - 6 : Load the data into the database with OCI_DirPathLoad() + * - 7 : Repeat step 4,5,6 + reset the stream with OCI_DirPathReset() until all + * rows has been loaded + * - 8 : Commit the load with OCI_DirPathFinish() + * - 9 : Free the direct path handle with OCI_DirPathFree() + * + * @par Example + * @include dirpath.c + * + */ + +/** + * @brief + * Create a direct path object + * + * @param typinf - Table type info handle + * @param partition - Partition name + * @param nb_cols - Number of columns to load + * @param nb_rows - Maximum of rows to handle per load operation + * + * @note + * Retrieve the table type info handle with OCI_TypeInfoGet(). + * The partition name is not mandatory + * + * @note + * Parameter 'nb_rows' is ignored for Oracle 8i. Prior to Oracle 9i, it's the + * OCI client that decides of the number of rows to process per convert/load calls. + * From Oracle 9i, OCI allows application to specify this value. Note that, the + * OCI client might not accept the input value. After OCI_DirPathPrepare() has + * been successfully called, OCI_DirPathGetMaxRows() returns the final number + * of rows used for the given direct path operation. + * + * @return + * Return the direct path handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_DirPath * OCI_API OCI_DirPathCreate +( + OCI_TypeInfo *typinf, + const otext *partition, + unsigned int nb_cols, + unsigned int nb_rows +); + +/** + * @brief + * Free an OCI_DirPath handle + * + * @param dp - Direct path Handle + * + * @return + * TRUE on success otherwise FALSE + * + */ +OCI_EXPORT boolean OCI_API OCI_DirPathFree +( + OCI_DirPath *dp +); + +/** + * @brief + * Describe a column to load into the given table + * + * @param dp - Direct path Handle + * @param index - Column index + * @param name - Column name + * @param maxsize - Maximum input value size for a column entry + * @param format - Date or numeric format to use + * + * @note + * An error is thrown if : + * - If the column specified by the 'name' parameter is not found in the table + * referenced by the type info handle passed to OCI_DirPathCreate() + * - the index is out of bounds (= 0 or >= number of columns) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetColumn +( + OCI_DirPath *dp, + unsigned int index, + const otext *name, + unsigned int maxsize, + const otext *format +); + +/** + * @brief + * Prepares the OCI direct path load interface before any rows can be converted + * or loaded + * + * @param dp - Direct path Handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathPrepare +( + OCI_DirPath *dp +); + +/** + * @brief + * Set the value of the given row/column array entry + * + * @param dp - Direct path Handle + * @param row - Row index + * @param index - Column index + * @param value - Value to set + * @param size - Size of the input value + * @param complete - Is the entry content fully provided ? + * + * @note + * Rows and columns indexes start at 1. + * + * @note + * The 'size' parameter is expressed in number of : + * - bytes for binary columns + * - characters for other columns + * + * @note + * Direct path support piece loading for LONGs and LOBs columns. When filling + * these columns, it's possible to provide input buffer piece by piece. In order + * to do so : + * - set the 'complete' parameter to FALSE + * - set the 'size' parameter to the piece size + * - Repeat calls to OCI_DirPathSetEntry() until the data is totally provided + * - The last call that set the last piece or an entry must specify the value + * TRUE for the 'complete' parameter + * + * @warning + * Current Direct Path OCILIB implementation DOES NOT support setting entry + * content piece by piece as mentioned above. It was planned in the original design + * but not supported yet. So, always set the complete parameter to TRUE. + * Setting entries content piece by piece may be supported in future releases + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetEntry +( + OCI_DirPath *dp, + unsigned int row, + unsigned int index, + void *value, + unsigned size, + boolean complete +); + +/** + * @brief + * Convert provided user data to the direct path stream format + * + * @param dp - Direct path Handle + * + * @return + * Possible return values : + * - OCI_DPR_COMPLETE : load has been successful + * - OCI_DPR_ERROR : an error happened while loading data + * - OCI_DPR_FULL : the internal stream is full + * - OCI_DPR_PARTIAL : a column hasn't been fully filled yet + * - OCI_DPR_EMPTY : no data was found to convert + * + * @note + * - When using conversion mode OCI_DCM_DEFAULT, OCI_DirPathConvert() stops when + * any error is encountered and returns OCI_DPR_ERROR + * - When using conversion mode OCI_DCM_FORCE, OCI_DirPathConvert() does not stop + * on errors. Instead it discards any erred rows and returns OCI_DPR_COMPLETE once + * all rows are processed. + * + * @note + * List of faulted rows and columns can be retrieved using OCI_DirPathGetErrorRow() and + * OCI_DirPathGetErrorColumn() + * + * @note + * OCI_DirPathGetAffectedRows() returns the number of rows converted in the last call. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathConvert +( + OCI_DirPath *dp +); + +/** + * @brief + * Loads the data converted to direct path stream format + * + * @param dp - Direct path Handle + * + * @return + * Possible return values : + * - OCI_DPR_COMPLETE : conversion has been successful + * - OCI_DPR_ERROR : an error happened while converting data + * - OCI_DPR_FULL : the internal stream is full + * - OCI_DPR_PARTIAL : a column hasn't been fully filled yet + * - OCI_DPR_EMPTY : no data was found to load + * + * @note + * List of faulted rows can be retrieved using OCI_DirPathGetErrorRow() + * + * @note + * OCI_DirPathGetAffectedRows() returns the number of rows successfully loaded in the last call. + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathLoad +( + OCI_DirPath *dp +); + +/** + * @brief + * Reset internal arrays and streams to prepare another load + * + * @param dp - Direct path Handle + * + * @note + * Once some data have been converted or loaded, OCI_DirPathReset() resets + * internal OCI structures in order to prepare another load operation + * (set entries, convert and load) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathReset +( + OCI_DirPath *dp +); + +/** + * @brief + * Terminate a direct path operation and commit changes into the database + * + * @param dp - Direct path Handle + * + * @warning + * The direct path handle cannot be used anymore after this call for any more + * loading operations and must be freed with OCI_DirPathFree(). + * + * @note + * Some properties functions of the direct path handle, such as + * OCI_DirPathGetRowCount() can be called on a terminated direct path handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathFinish +( + OCI_DirPath *dp +); + +/** + * @brief + * Terminate a direct path operation without committing changes + * + * @param dp - Direct path Handle + * + * @note + * Any pending loaded data are canceled. + * Any load completion operations, such as index maintenance operations, are not performed. + * + * @warning + * The direct path handle cannot be used anymore after this call for any more + * loading operations and must be freed with OCI_DirPathFree(). + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathAbort +( + OCI_DirPath *dp +); + +/** + * @brief + * Execute a data save-point (server side) + * + * @param dp - Direct path Handle + * + * @note + * Executing a data save-point is not allowed for LOBs + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSave +( + OCI_DirPath *dp +); + +/** + * @brief + * Flushes a partially loaded row from server + * + * @param dp - Direct path Handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathFlushRow +( + OCI_DirPath *dp +); + +/** + * @brief + * Set the current number of rows to convert and load + * + * @param dp - Direct path Handle + * @param nb_rows - Number of row to process + * + * @warning + * An OCILIB error will be thrown if the value exceeds the maximum number of + * rows in the internals arrays + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetCurrentRows +( + OCI_DirPath *dp, + unsigned int nb_rows +); + +/** + * @brief + * Return the current number of rows used in the OCILIB internal + * arrays of rows + * + * @param dp - Direct path Handle + * + * @return + * Internal current array size on SUCCESS otherwise 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetCurrentRows +( + OCI_DirPath *dp +); + +/** + * @brief + * Return the maximum number of rows allocated in the OCI and OCILIB + * internal arrays of rows + * + * @param dp - Direct path Handle + * + * @return + * Internal maximum array size on SUCCESS otherwise 0 + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetMaxRows +( + OCI_DirPath *dp +); + +/** + * @brief + * Set the default date format string for input conversion + * + * @param dp - Direct path Handle + * @param format - date format + * + * @note + * For string to date conversion, Oracle uses : + * - Column date format + * - Default date format (modified by this call) + * - Default global support environment setting + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetDateFormat +( + OCI_DirPath *dp, + const otext *format +); + +/** + * @brief + * Set the parallel loading mode + * + * @param dp - Direct path Handle + * @param value - enable/disable parallel mode + * + * @note + * Default value is FALSE. + * + * @note + * Setting the value to TRUE allows multiple load sessions to load the same + * segment concurrently + * + * @par Parallel loading mode (From Oracle documentation) + * + * A direct load operation requires that the object being loaded is locked to + * prevent DML on the object. + * Note that queries are lock-free and are allowed while the object is being loaded. + * - For a table load, if the option is set to: + * - FALSE, then the table DML X-Lock is acquired. + * - TRUE, then the table DML S-Lock is acquired. + * - For a partition load, if the option is set to: + * - FALSE, then the table DML SX-Lock and partition DML X-Lock is acquired. + * - TRUE, then the table DML SS-Lock and partition DML S-Lock is acquired. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetParallel +( + OCI_DirPath *dp, + boolean value +); + +/** + * @brief + * Set the logging mode for the loading operation + * + * @param dp - Direct path Handle + * @param value - enable/disable logging + * + * @par Logging mode (from Oracle Documentation) + * + * The NOLOG attribute of each segment determines whether image redo or + * invalidation redo is generated: + * - FALSE : Use the attribute of the segment being loaded. + * - TRUE : No logging. Overrides DDL statement, if necessary. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetNoLog +( + OCI_DirPath *dp, + boolean value +); + +/** + * @brief + * Set number of elements in the date cache + * + * @param dp - Direct path Handle + * @param size - Buffer size + * + * @note + * Default value is 0. + * + * @note + * Setting the value to 0 disables the cache + * + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetCacheSize +( + OCI_DirPath *dp, + unsigned int size +); + +/** + * @brief + * Set the size of the internal stream transfer buffer + * + * @param dp - Direct path Handle + * @param size - Buffer size + * + * @note + * Default value is 64KB. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetBufferSize +( + OCI_DirPath *dp, + unsigned int size +); + +/** + * @brief + * Set the direct path conversion mode + * + * @param dp - Direct path Handle + * @param mode - Conversion mode + * + * @note + * Possible values for parameter 'mode' : + * - OCI_DCM_DEFAULT : conversion fails on error + * - OCI_DCM_FORCE : conversion does not fail on error + * + * @note + * See OCI_DirPathConvert() for conversion mode details + * + * @note + * Default value is OCI_DCM_DEFAULT + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DirPathSetConvertMode +( + OCI_DirPath *dp, + unsigned int mode +); + +/** + * @brief + * Return the number of rows successfully loaded into the database so far + * + * @param dp - Direct path Handle + * + * @note + * Insertions are committed with OCI_DirPathFinish() + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetRowCount +( + OCI_DirPath *dp +); + +/** + * @brief + * return the number of rows successfully processed during in the last + * conversion or loading call + * + * @param dp - Direct path Handle + * + * @note + * This function called after : + * + * - OCI_DirPathConvert(), returns the number of converted rows + * - OCI_DirPathload(), returns the number of loaded rows + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetAffectedRows +( + OCI_DirPath *dp +); + +/** + * @brief + * Return the index of a column which caused an error during data conversion + * + * @param dp - Direct path Handle + * + * @warning + * Direct path column indexes start at 1. + * + * @note + * Errors may happen while data is converted to direct path stream format + * using OCI_DirPathConvert(). + * When using conversion mode OCI_DCM_DEFAULT, OCI_DirPathConvert() returns + * OCI_DPR_ERROR on error. OCI_DirPathGetErrorColumn() returns the column index + * that caused the error + * When using conversion mode OCI_DCM_FORCE, OCI_DirPathConvert() returns + * OCI_DPR_COMPLETE even on errors. In order to retrieve the list of all column + * indexes that have erred, the application can call OCI_DirPathGetErrorColumn() + * repeatedly until it returns 0. + * + * @note + * The internal value is reset to 0 when calling OCI_DirPathConvert() + * + * @return + * 0 is no error occurs otherwise the index of the given column which caused an + * error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetErrorColumn +( + OCI_DirPath *dp +); + +/** + * @brief + * Return the index of a row which caused an error during data conversion + * + * @param dp - Direct path Handle + * + * @warning + * Direct path row indexes start at 1. + * + * @note + * Errors may happen : + * - while data is converted to direct path stream format using OCI_DirPathConvert() + * - while data is loaded to database using OCI_DirPathLoad() + * + * @note + * When using conversion mode OCI_DCM_DEFAULT, OCI_DirPathConvert() returns + * OCI_DPR_ERROR on error. OCI_DirPathGetErrorRow() returns the row index that + * caused the error. + * When using conversion mode OCI_DCM_FORCE, OCI_DirPathConvert() returns + * OCI_DPR_COMPLETE even on errors. In order to retrieve the list of all row + * indexes that have erred, the application can call OCI_DirPathGetErrorRow() + * repeatedly until it returns 0. + * + * @note + * After a call to OCI_DirPathLoad(), in order to retrieve the list of all faulted rows + * indexes, the application can call OCI_DirPathGetErrorRow() repeatedly until it returns 0. + * + * @note + * The internal value is reset to 0 when calling OCI_DirPathConvert(), + * OCI_DirPathReset() or OCI_DirPathLoad() + * + * @return + * 0 is no error occurs otherwise the index of the given row which caused an + * error + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DirPathGetErrorRow +( + OCI_DirPath *dp +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiAdvancedQueuing Oracle Advanced Queuing (A/Q) + * @{ + * + * OCILIB supports Oracle Advanced Queues features + * + * Let's Oracle talk about this features ! + * + * @par Oracle Queues (from Oracle Streams - Advanced Queuing User's Guide) + * + * Oracle Streams AQ provides database-integrated message queuing functionality. + * It is built on top of Oracle Streams and leverages the functions of Oracle + * Database so that messages can be stored persistently, propagated between + * queues on different computers and databases, and transmitted using Oracle + * Net Services and HTTP(S). + * Because Oracle Streams AQ is implemented in database tables, all operational + * benefits of high availability, scalability, and reliability are also + * applicable to queue data. Standard database features such as recovery, + * restart, and security are supported by Oracle Streams AQ. You can use + * database development and management tools such as Oracle Enterprise Manager + * to monitor queues. Like other database tables, queue tables can be imported + * and exported. + * + * @par OCILIB implementation + * + * OCILIB provides a (nearly) full C implementation of Advanced Queues available in + * Oracle OCI and proposes the following data types : + * - OCI_Msg : Implementation of message to enqueue/dequeue from/to queues + * - OCI_Enqueue : Implementation of enqueuing process + * - OCI_Dequeue : Implementation of dequeuing process + * - OCI_Agent : Implementation of Advanced queues Agents + * + * OCILIB support AQ messages notification with Oracle Client 10gR2 or above + * + * Note that the only AQ features not supported yet by OCILIB are : + * - Payloads of type AnyData + * - Enqueuing/dequeuing arrays of messages + * - Optional delivery mode introduced in 10gR2 + * + * OCILIB provides as well a C API to administrate queues and queue tables initially + * reserved to PL/SQL and Java (wrappers around PL/SQL calls). + * This API, based on internal PL/SQL calls wrapping the DBMS_AQADM packages procedures, allow the + * following actions : + * - create, alter, drop and purge queue tables (OCI_QueueTableXXX calls) + * - create, alter, drop, start, stop queues (OCI_QueueXXX calls) + * + * Note that the user connected to the database needs particular privileges to manipulate or + * administrate queues (See Oracle Streams - Advanced Queuing User's Guide for more informations + * on these privileges) + * + *@par Example + * @include queue.c + * + */ + +/** + * @brief + * Create a message object based on the given payload type + * + * @param typinf - Type info handle + * + * @note + * OCILIB supports 2 type of message payload : + * - Oracle types (UDT) + * - RAW data + * + * @note + * Oracle Type AnyData is not supported in the current version of OCILIB + * + * @note + * the parameter 'typinf' indicates the type of payload : + * - For object payload, retrieve the object type information handle with + * OCI_TypeInfoGet() using the object type name + * - For RAW payload, you MUST pass the object type information retrieved with + * OCI_TypeInfoGet() using "SYS.RAW" as object type name + * + * @warning + * Newly created Message handles have NULL payloads. + * For Message handling Objects payloads, OCI_MsgGetObject() returns NULL until an object handle is + * assigned to the message. + * + * @note + * When a local OCI_Msg handle is enqueued, it keeps its attributes. If it's enqueued again, another + * identical message is posted into the queue. + * To reset a message and empty all its properties, call OCI_MsgReset() + * Note that OCI_MsgReset() clears the message payload. + * + * @return + * Return the message handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Msg * OCI_API OCI_MsgCreate +( + OCI_TypeInfo *typinf +); + +/** + * @brief + * Free a message object + * + * @param msg - Message handle + * + * @warning + * Only message handles created with OCI_MsgCreate() should be freed by OCI_MsgFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgFree +( + OCI_Msg *msg +); + +/** + * @brief + * Reset all attributes of a message object + * + * @param msg - Message handle + * + * @note + * This function calls OCI_MsgSetxxx() with default or NULL attributes + * + * @warning + * OCI_MsgReset() clears the message payload and set it to NULL + * For messages handling objects payloads, OCI_MsgSetObject() must be called again to assign a + * payload. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgReset +( + OCI_Msg *msg +); + +/** + * @brief + * Get the object payload of the given message + * + * @param msg - Message handle + * + * @return + * Return the object handle on success otherwise NULL on failure or if payload is NULL + * + */ + +OCI_EXPORT OCI_Object * OCI_API OCI_MsgGetObject +( + OCI_Msg *msg +); + +/** + * @brief + * Set the object payload of the given message + * + * @param msg - Message handle + * @param obj - Object handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetObject +( + OCI_Msg *msg, + OCI_Object *obj +); + +/** + * @brief + * Get the RAW payload of the given message + * + * @param msg - Message handle + * @param raw - Input buffer + * @param size - Input buffer maximum size + * + * @note + * On output, parameter 'size' holds the number of bytes copied into the given buffer + * + * @return + * TRUE on success otherwise FALSE on failure or if payload is object based. + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgGetRaw +( + OCI_Msg *msg, + void *raw, + unsigned int *size +); + +/** + * @brief + * Set the RAW payload of the given message + * + * @param msg - Message handle + * @param raw - Raw data + * @param size - Raw data size + * + * @return + * TRUE on success otherwise FALSE on failure or if payload is object based. + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetRaw +( + OCI_Msg *msg, + const void *raw, + unsigned int size +); + +/** + * @brief + * Return the number of attempts that have been made to dequeue the message + * + * @param msg - Message handle + * + */ + +OCI_EXPORT int OCI_API OCI_MsgGetAttemptCount +( + OCI_Msg *msg +); + +/** + * @brief + * Return the number of seconds that a message is delayed for dequeuing + * + * @param msg - Message handle + * + * @note + * see OCI_MsgSetEnqueueDelay() for more details + * + */ + +OCI_EXPORT int OCI_API OCI_MsgGetEnqueueDelay +( + OCI_Msg *msg +); + +/** + * @brief + * set the number of seconds to delay the enqueued message + * + * @param msg - Message handle + * @param value - Delay in seconds + * + * @note + * The delay represents the number of seconds after which a message is available for dequeuing. + * When the message is enqueued, its state is set to OCI_AMS_WAITING. + * When the delay expires, its state is set to OCI_AMS_READY. + * + * @note + * If parameter 'value' is set to zero (default value), the message will be immediately available + * for dequeuing + * + * @warning + * Dequeuing by Message ID overrides the delay specification. + * + * @warning + * Delaying processing requires the queue monitor to be started. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetEnqueueDelay +( + OCI_Msg *msg, + int value +); + +/** + * @brief + * return the time the message was enqueued + * + * @param msg - Message handle + * + * @note + * Only use this function for message dequeued from queues + * + */ + +OCI_EXPORT OCI_Date * OCI_API OCI_MsgGetEnqueueTime +( + OCI_Msg *msg +); + +/** + * @brief + * Return the duration that the message is available for dequeuing + * + * @param msg - Message handle + * + * @note + * see OCI_MsgSetExpiration() for more details + * + */ + +OCI_EXPORT int OCI_API OCI_MsgGetExpiration +( + OCI_Msg *msg +); + +/** + * @brief + * set the duration that the message is available for dequeuing + * + * @param msg - Message handle + * @param value - duration in seconds + * + * @note + * This parameter is an offset from the delay (see OCI_MsgSetEnqueueDelay()) + * While waiting for expiration, the message state is set to OCI_AMS_READY. + * If the message is not dequeued before it expires, it will be moved to the exception queue + * with the state OCI_AMS_EXPIRED. + * + * @note + * If parameter 'value' is set to -1 (default value), the message will not expire + * + * @warning + * Expiration processing requires the queue monitor to be started. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetExpiration +( + OCI_Msg *msg, + int value +); + +/** + * @brief + * Return the state of the message at the time of the dequeue + * + * @param msg - Message handle + * + * @return + * - OCI_UNKNOWN : the function has failed to get the message state + * - OCI_AMS_READY : the message is ready to be processed + * - OCI_AMS_WAITING : the message delay has not yet completed + * - OCI_AMS_PROCESSED : the message has been processed + * - OCI_AMS_EXPIRED : the message has moved to exception queue + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_MsgGetState +( + OCI_Msg *msg +); + +/** + * @brief + * Return the priority of the message + * + * @param msg - Message handle + * + * @note + * see OCI_MsgSetPriority() for more details + * + */ + +OCI_EXPORT int OCI_API OCI_MsgGetPriority +( + OCI_Msg *msg +); + +/** + * @brief + * Set the priority of the message + * + * @param msg - Message handle + * @param value - Message priority + * + * @note + * - The priority can be any number, including negative numbers. + * - A smaller number indicates higher priority. + * - Default value is zero. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetPriority +( + OCI_Msg *msg, + int value +); + +/** + * @brief + * Return the ID of the message + * + * @param msg - Message handle + * @param id - Input buffer + * @param len - Input buffer maximum size + * + * @note + * The message ID is : + * - generated when the message is enqueued in the queue + * - retrieved when the message is dequeued from the queue + * + * @note + * On output, parameter 'len' holds the number of bytes copied into the given buffer + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgGetID +( + OCI_Msg *msg, + void *id, + unsigned int *len +); + +/** + * @brief + * Return the original ID of the message in the last queue that generated this message + * + * @param msg - Message handle + * @param id - Input buffer + * @param len - Input buffer maximum size + * + * @warning + * When a message is propagated from/to different queues, this ID is the one generated for the + * message in the previous queue. + * + * @note + * On output, parameter 'len' holds the number of bytes copied into the given buffer + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgGetOriginalID +( + OCI_Msg *msg, + void *id, + unsigned int *len +); + +/** + * @brief + * Set the original ID of the message in the last queue that generated this message + * + * @param msg - Message handle + * @param id - Message ID + * @param len - Message ID size + * + * @warning + * When a message is propagated from/to different queues, this ID is the one generated for the + * message in the previous queue. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetOriginalID +( + OCI_Msg *msg, + const void *id, + unsigned int len +); + +/** + * @brief + * Return the original sender of a message + * + * @param msg - Message handle + * + * @return + * Sender Handle (OCI_Agent *) on success (if set at enqueue time) otherwise NULL + * + */ + +OCI_EXPORT OCI_Agent * OCI_API OCI_MsgGetSender +( + OCI_Msg *msg +); + +/** + * @brief + * Set the original sender of a message + * + * @param msg - Message handle + * @param sender - Message sender + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetSender +( + OCI_Msg *msg, + OCI_Agent *sender +); + +/** + * @brief + * Set the recipient list of a message to enqueue + * + * @param msg - Message handle + * @param consumers - Recipients list (array of agent handles) + * @param count - Number of recipients + * + * @warning + * This function should only be used for queues which allow multiple consumers. + * The default recipients are the queue subscribers. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetConsumers +( + OCI_Msg *msg, + OCI_Agent **consumers, + unsigned int count +); + +/** + * @brief + * Get the correlation identifier of the message + * + * @param msg - Message handle + * + * @note + * see OCI_MsgSetCorrelation() for more details + * + */ + +OCI_EXPORT const otext * OCI_API OCI_MsgGetCorrelation +( + OCI_Msg *msg +); + +/** + * @brief + * set the correlation identifier of the message + * + * @param msg - Message handle + * @param correlation - Message correlation text + * + * @note + * see OCI_DequeueSetCorrelation() for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetCorrelation +( + OCI_Msg *msg, + const otext *correlation +); + +/** + * @brief + * Get the Exception queue name of the message + * + * @param msg - Message handle + * + * @warning + * When calling this function on a message retrieved with OCI_DequeueGet(), the returned value is + * NULL if the default exception queue associated with the current queue is used (e.g. no user + * defined specified at enqueue time for the message) + * + * @note + * see OCI_MsgSetExceptionQueue() for more details + * + */ +OCI_EXPORT const otext * OCI_API OCI_MsgGetExceptionQueue +( + OCI_Msg *msg +); + +/** + * @brief + * Set the name of the queue to which the message is moved to if it cannot be + * processed successfully + * + * @param msg - Message handle + * @param queue - Exception queue name + * + * @warning + * From Oracle Documentation : + * + * "Messages are moved into exception queues in two cases : + * - If the number of unsuccessful dequeue attempts has exceeded the attribute 'max_retries' of + * given queue + * - if the message has expired. + * + * All messages in the exception queue are in the EXPIRED state. + * + * The default is the exception queue associated with the queue table. + * + * If the exception queue specified does not exist at the time of the move the message will be + * moved to the default exception queue associated with the queue table and a warning will be + * logged in the alert file. + * + * This attribute must refer to a valid queue name." + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_MsgSetExceptionQueue +( + OCI_Msg *msg, + const otext *queue +); + +/** + * @brief + * Create a Enqueue object for the given queue + * + * @param typinf - Type info handle + * @param name - Queue name + * + * @note + * OCILIB supports 2 type of message payload : + * - Oracle types (UDT) + * - RAW data + * + * @note + * Oracle Type AnyData is not supported in the current version of OCILIB + * + * @note + * the parameter 'typinf' indicates the type of payload to enqueue to the given queue : + * - For object payload, retrieve the object type information handle with + * OCI_TypeInfoGet() using the object type name + * - For RAW payload, you MUST pass the object type information retrieved with + * OCI_TypeInfoGet() using "SYS.RAW" as object type name + * + * @return + * Return the Enqueue handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Enqueue * OCI_API OCI_EnqueueCreate +( + OCI_TypeInfo *typinf, + const otext *name +); + +/** + * @brief + * Free a Enqueue object + * + * @param enqueue - Enqueue handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueueFree +( + OCI_Enqueue *enqueue +); + +/** + * @brief + * Enqueue a message on the queue associated to the Enqueue object + * + * @param enqueue - Enqueue handle + * @param msg - Message handle to enqueue + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueuePut +( + OCI_Enqueue *enqueue, + OCI_Msg *msg +); + +/** +* @brief +* Set the enqueuing sequence of messages to put in the queue +* +* @param enqueue - Enqueue handle +* @param sequence - enqueuing sequence +* +* @note +* Possible values for parameter 'sequence' : +* - OCI_ASD_BEFORE : enqueue message before another message +* - OCI_ASD_TOP : enqueue message before all messages +* +* @note +* Default value is OCI_ASD_TOP +* +* @note +* if the parameter 'sequence' is set to OCI_ASD_BEFORE, the application must +* call OCI_EnqueueSetRelativeMsgID() before enqueuing the next message in the queue. +* +* @note +* In order to stop enqueuing message using a sequence deviation, call +* OCI_EnqueueSetSequenceDeviation() with the value OCI_ASD_TOP +* +* @return +* TRUE on success otherwise FALSE +* +*/ + +OCI_EXPORT boolean OCI_API OCI_EnqueueSetSequenceDeviation +( + OCI_Enqueue *enqueue, + unsigned int sequence +); + +/** + * @brief + * Return the sequence deviation of messages to enqueue to the queue + * + * @param enqueue - Enqueue handle + * + * @note + * see OCI_EnqueueSetSequenceDeviation() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_EnqueueGetSequenceDeviation +( + OCI_Enqueue *enqueue +); + +/** + * @brief + * Set whether the new message is enqueued as part of the current transaction + * + * @param enqueue - Enqueue handle + * @param visibility - Enqueuing visibility + * + * @note + * Possible values for parameter 'visibility' : + * - OCI_AMV_IMMEDIATE : enqueue is an independent transaction + * - OCI_AMV_ON_COMMIT : enqueue is part of current transaction + * + * @note + * Default value is OCI_AMV_ON_COMMIT + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueueSetVisibility +( + OCI_Enqueue *enqueue, + unsigned int visibility +); + +/** + * @brief + * Get the enqueuing/locking behavior + * + * @param enqueue - Enqueue handle + * + * @note + * see OCI_EnqueueSetVisibility() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_EnqueueGetVisibility +( + OCI_Enqueue *enqueue +); + +/** + * @brief + * Set a message identifier to use for enqueuing messages using a sequence deviation + * + * @param enqueue - Enqueue handle + * @param id - message identifier + * @param len - pointer to message identifier length + * + * @note + * This call is only valid if OCI_EnqueueSetSequenceDeviation() has been called + * with the value OCI_ASD_BEFORE + * + * @warning + * if the function cannot assign the message id, the content of the parameter 'len' is set to zero. + * + * @note + * see OCI_EnqueueSetSequenceDeviation() for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueueSetRelativeMsgID +( + OCI_Enqueue *enqueue, + const void *id, + unsigned int len +); + +/** + * @brief + * Get the current associated message identifier used for enqueuing messages + * using a sequence deviation + * + * @param enqueue - Enqueue handle + * @param id - buffer to receive the message identifier + * @param len - pointer to buffer max length + * + * @warning + * When the function returns, parameter 'len' hold the number of bytes assigned to parameter 'id' + * + * @note + * see OCI_EnqueueGetRelativeMsgID() for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_EnqueueGetRelativeMsgID +( + OCI_Enqueue *enqueue, + void *id, + unsigned int *len +); + +/** + * @brief + * Create a Dequeue object for the given queue + * + * @param typinf - Type info handle + * @param name - Queue name + * + * @note + * OCILIB supports 2 type of message payload : + * - Oracle types (UDT) + * - RAW data + * + * @note + * Oracle Type AnyData is not supported in the current version of OCILIB + * + * @note + * the parameter 'typinf' indicates the type of payload to dequeue from the given queue : + * - For object payload, retrieve the object type information handle with + * OCI_TypeInfoGet() using the object type name + * - For RAW payload, you MUST pass the object type information retrieved with + * OCI_TypeInfoGet() using "SYS.RAW" as object type name + * + * @return + * Return the Dequeue handle on success otherwise NULL on failure + * + */ + +OCI_EXPORT OCI_Dequeue * OCI_API OCI_DequeueCreate +( + OCI_TypeInfo *typinf, + const otext *name +); + +/** + * @brief + * Free a Dequeue object + * + * @param dequeue - Dequeue handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueFree +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Dequeue messages from the given queue + * + * @param dequeue - Dequeue handle + * + * @warning + * The returned message is handled by the dequeue object. + * Do not release it with OCI_MsgFree() + * + * @warning + * When dequeuing from a multiple consumer queue, you need + * to set the navigation mode to OCI_ADN_FIRST_MSG using + * OCI_DequeueSetNavigation() + * + * @return + * Message handle on success otherwise NULL on failure or on timeout + * + */ + +OCI_EXPORT OCI_Msg * OCI_API OCI_DequeueGet +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Subscribe for asynchronous messages notifications + * + * @param dequeue - Dequeue handle + * @param port - Port to use for notifications + * @param timeout - notification timeout + * @param callback - User handler callback fired when messages are ready to be dequeued + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * asynchronous messages notifications + * + * @note + * Requires Oracle Client 10gR2 or above + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSubscribe +( + OCI_Dequeue *dequeue, + unsigned int port, + unsigned int timeout, + POCI_NOTIFY_AQ callback +); + +/** + * @brief + * Unsubscribe for asynchronous messages notifications + * + * @param dequeue - Dequeue handle + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueUnsubscribe +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the current consumer name to retrieve message for. + * + * @param dequeue - Dequeue handle + * @param consumer - consumer name + * + * @warning + * If a queue is not set up for multiple consumers, OCI_DequeueSetConsumer() + * should not be called or called with parameter 'consumer' set to NULL + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetConsumer +( + OCI_Dequeue *dequeue, + const otext *consumer +); + +/** + * @brief + * Get the current consumer name associated with the dequeuing process. + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetConsumer() for more details + * + */ + +OCI_EXPORT const otext * OCI_API OCI_DequeueGetConsumer +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * set the correlation identifier of the message to be dequeued + * + * @param dequeue - Dequeue handle + * @param pattern - correlation identifier + * + * @note + * Special pattern matching characters, such as "%" or "_" can be used. + * If more than one message satisfies the pattern, the order of dequeuing is undetermined. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetCorrelation +( + OCI_Dequeue *dequeue, + const otext *pattern +); + +/** + * @brief + * Get the correlation identifier of the message to be dequeued + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetCorrelation() for more details + * + */ + +OCI_EXPORT const otext * OCI_API OCI_DequeueGetCorrelation +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the message identifier of the message to be dequeued + * + * @param dequeue - Dequeue handle + * @param id - message identifier + * @param len - size of the message identifier + * + * @warning + * if the function cannot assign the message id, the content of the parameter 'len' is set to zero. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetRelativeMsgID +( + OCI_Dequeue *dequeue, + const void *id, + unsigned int len +); + +/** + * @brief + * Get the message identifier of the message to be dequeued + * + * @param dequeue - Dequeue handle + * @param id - message identifier + * @param len - size of the message identifier + * + * @warning + * When the function returns, parameter 'len' hold the number of bytes assigned to parameter 'id' + * + * @note + * see OCI_DequeueSetRelativeMsgID() for more details + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueGetRelativeMsgID +( + OCI_Dequeue *dequeue, + void *id, + unsigned int *len +); + +/** + * @brief + * Set whether the new message is dequeued as part of the current transaction + * + * @param dequeue - Dequeue handle + * @param visibility - dequeuing mode + * + * @warning + * The visibility parameter is ignored when using the OCI_ADM_BROWSE dequeuing + * mode (see OCI_DequeueSetMode()) + * + * @note + * Possible values for parameter 'mode' : + * - OCI_AMV_IMMEDIATE : dequeue is an independent transaction + * - OCI_AMV_ON_COMMIT : dequeue is part of current transaction + * + * @note + * Default value is OCI_AMV_ON_COMMIT + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetVisibility +( + OCI_Dequeue *dequeue, + unsigned int visibility +); + +/** + * @brief + * Get the dequeuing/locking behavior + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetVisibility() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DequeueGetVisibility +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the dequeuing/locking behavior + * + * @param dequeue - Dequeue handle + * @param mode - dequeuing mode + * + * @note + * Possible values for parameter 'mode' : + * - OCI_ADM_BROWSE : read message without acquiring a lock + * - OCI_ADM_LOCKED : read and obtain write lock on message + * - OCI_ADM_REMOVE : read the message and delete it + * - OCI_ADM_REMOVE_NODATA : confirm receipt of the message, but do not + * deliver the actual message content + * + * @note + * Default value is OCI_ADM_REMOVE + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetMode +( + OCI_Dequeue *dequeue, + unsigned int mode +); + +/** + * @brief + * Get the dequeuing/locking behavior + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetMode() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DequeueGetMode +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the position of messages to be retrieved. + * + * @param dequeue - Dequeue handle + * @param position - navigation position + * + * @note + * The dequeuing uses the following sequence : + * - find messages using the navigation position + * - apply search criteria (message correlation) + * - get message + * + * @note + * Possible values for parameter 'position' : + * - OCI_ADN_FIRST_MSG : retrieves the first message which is available + * - OCI_ADN_NEXT_MSG : retrieves the next message which is available + * - OCI_ADN_NEXT_TRANSACTION : skips the remainder of the current transaction + * group (if any) and retrieves the first message + * of the next transaction group. + * + * @note + * Default value is OCI_ADN_NEXT_MSG + * + * @warning + * OCI_ADN_NEXT_TRANSACTION can only be used if message grouping is enabled for the given queue. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetNavigation +( + OCI_Dequeue *dequeue, + unsigned int position +); + +/** + * @brief + * Return the navigation position of messages to retrieve from the queue + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetNavigation() for more details + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_DequeueGetNavigation +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * set the time that OCIDequeueGet() waits for messages if no messages are + * currently available + * + * @param dequeue - Dequeue handle + * @param timeout - timeout in seconds + * + *@note + * - Any positive values in seconds are valid. + * - The value 0 is accepted and means OCIDequeueGet() does not wait for + * messages and returns immediately if no messages are available + * - The value -1 is accepted and means OCIDequeueGet() waits for ever (until + * a message is available in the queue) + * + * @note + * Default value is -1 (wait for ever) + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetWaitTime +( + OCI_Dequeue *dequeue, + int timeout +); + +/** + * @brief + * Return the time that OCIDequeueGet() waits for messages if no messages are currently available + * + * @param dequeue - Dequeue handle + * + * @note + * see OCI_DequeueSetWaitTime() for more details + * + */ + +OCI_EXPORT int OCI_API OCI_DequeueGetWaitTime +( + OCI_Dequeue *dequeue +); + +/** + * @brief + * Set the Agent list to listen to message for + * + * @param dequeue - Dequeue handle + * @param consumers - Agent handle array + * @param count - Number of agents the array + * + * @return + * return TRUE on success otherwise FALSE + */ + +OCI_EXPORT boolean OCI_API OCI_DequeueSetAgentList +( + OCI_Dequeue *dequeue, + OCI_Agent **consumers, + unsigned int count +); + +/** + * @brief + * Listen for messages that match any recipient of the associated Agent list + * + * @param dequeue - Dequeue handle + * @param timeout - Timeout in second + * + * @note + * If an Agent handle is returned, messages are available for this agent. + * In order to retrieve its messages : + * - call OCI_DequeueSetConsumer() with the name of agent using OCI_AgentGetName() + * - call OCI_DequeueGet() to dequeue it's pending messages + * + * @warning + * The return value is valid only until: + * - OCIDequeueListen() is called again + * - OCI_DequeueFree(à is called to free the Dequeue object + * So Do not store the handle value across calls to OCIDequeueListen() + * + * @return + * An Agent handle for who messages are available on success otherwise NULL + */ + +OCI_EXPORT OCI_Agent * OCI_API OCI_DequeueListen +( + OCI_Dequeue *dequeue, + int timeout +); + +/** + * @brief + * Create an AQ agent object + * + * @param con - Connection handle + * @param name - Agent name + * @param address - Agent address + * + * @note + * An AQ agent object is : + * - used as recipient information when enqueuing a message + * - used as sender information when dequeuing a message + * - used for listening message only from identified senders + * + * @note + * the AQ agent address can be any Oracle identifier, up to 128 bytes. + * the AQ agent name can be any Oracle identifier, up to 30 bytes. + * + * @return + * AQ agent handle on success otherwise NULL + * + */ + +OCI_EXPORT OCI_Agent * OCI_API OCI_AgentCreate +( + OCI_Connection *con, + const otext *name, + const otext *address +); + +/** + * @brief + * Free an AQ agent object + * + * @param agent - AQ agent handle + * + * @warning + * Only AQ agent handle created with OCI_AgentCreate() should be freed by OCI_AgentFree() + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_AgentFree +( + OCI_Agent *agent +); + +/** + * @brief + * Set the given AQ agent name + * + * @param agent - AQ agent handle + * @param name - AQ agent name + * + * @note + * the AQ agent name is used to identified an message send or recipient when enqueuing/dequeuing + * a message + * + * @note + * the AQ agent name can be any Oracle identifier, up to 30 bytes. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_AgentSetName +( + OCI_Agent *agent, + const otext *name +); + +/** + * @brief + * Get the given AQ agent name + * + * @param agent - AQ agent handle + * + * @return + * AQ agent name on success otherwise NULL on failure + * + */ + +OCI_EXPORT const otext * OCI_API OCI_AgentGetName +( + OCI_Agent *agent +); + +/** + * @brief + * Set the given AQ agent address + * + * @param agent - AQ agent handle + * @param address - AQ agent address + * + * @note + * the parameter 'address' must be of the form : [schema.]queue_name[\@dblink] + * + * @note + * the AQ agent address can be any Oracle identifier, up to 128 bytes. + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_AgentSetAddress +( + OCI_Agent *agent, + const otext *address +); + +/** + * @brief + * Get the given AQ agent address + * + * @param agent - AQ agent handle + * + * @note + * See OCI_AgentSetAddress() + * + * @return + * AQ agent address on success otherwise NULL on failure + * + */ + +OCI_EXPORT const otext * OCI_API OCI_AgentGetAddress +( + OCI_Agent *agent +); + +/** + * @brief + * Create a queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * @param queue_table - Queue table name + * @param queue_type - Queue type + * @param max_retries - Maximum number of attempts to dequeue a message + * @param retry_delay - Number of seconds between attempts to dequeue a message + * @param retention_time - number of seconds a message is retained in the queue table after + * being dequeued from the queue + * @param dependency_tracking - Parameter reserved for future use by Oracle (MUST be set to FALSE) + * @param comment - Description of the queue + * + * @note + * Parameter 'queue_name' can specify the schema where to create to queue ([schema.]queue_name) + * Queue names cannot be longer than 24 characters (Oracle limit for user queues) + * + * @note + * Possible values for parameter 'queue_type' : + * - OCI_AQT_NORMAL : Normal queue + * - OCI_AQT_EXCEPTION : Exception queue + * - OCI_AQT_NON_PERSISTENT : Non persistent queue + * + * To set default values, pass : + * - queue_type : OCI_AQT_NORMAL + * - max_retries : 0 + * - retry_delay : 0 + * - retention_time : 0 + * - comment : NULL + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.CREATE_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueCreate +( + OCI_Connection *con, + const otext *queue_name, + const otext *queue_table, + unsigned int queue_type, + unsigned int max_retries, + unsigned int retry_delay, + unsigned int retention_time, + boolean dependency_tracking, + const otext *comment +); + +/** + * @brief + * Alter the given queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * @param max_retries - Maximum number of attempts to dequeue a message + * @param retry_delay - Number of seconds between attempts to dequeue a message + * @param retention_time - number of seconds a message is retained in the queue table after + * being dequeued from the queue + * @param comment - Description of the queue + * + * @note + * See OCI_QueueCreate() for more details + * + * @warning + * This function updates all attributes handled in the parameter list ! + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.ALTER_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueAlter +( + OCI_Connection *con, + const otext *queue_name, + unsigned int max_retries, + unsigned int retry_delay, + unsigned int retention_time, + const otext *comment +); + +/** + * @brief + * Drop the given queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * + * @warning + * A queue can be dropped only if it has been stopped before. + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.DROP_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueDrop +( + OCI_Connection *con, + const otext *queue_name +); + +/** + * @brief + * Start the given queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * @param enqueue - Enable enqueue + * @param dequeue - Enable dequeue + * + * @warning + * For exception queues, only enqueuing is allowed + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.START_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueStart +( + OCI_Connection *con, + const otext *queue_name, + boolean enqueue, + boolean dequeue +); + +/** + * @brief + * Stop enqueuing or dequeuing or both on the given queue + * + * @param con - Connection handle + * @param queue_name - Queue name + * @param enqueue - Disable enqueue + * @param dequeue - Disable dequeue + * @param wait - Wait for current pending enqueues/dequeues + * + * @warning + * A queue cannot be stopped if there are pending transactions against the queue. + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.STOP_QUEUE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueStop +( + OCI_Connection *con, + const otext *queue_name, + boolean enqueue, + boolean dequeue, + boolean wait +); + +/** + * @brief + * Create a queue table for messages of the given type + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param queue_payload_type - Message type name + * @param storage_clause - Additional clauses for the table storage + * @param sort_list - Additional columns name to use for sorting + * @param multiple_consumers - Enable multiple consumers for each messages + * @param message_grouping - Specifies if messages are grouped within a transaction + * @param comment - Description of the queue table + * @param primary_instance - primary owner (instance) of the queue table + * @param secondary_instance - Owner of the queue table if the primary instance is not available + * @param compatible - lowest database version with which the queue table is compatible + * + * @note + * Parameter 'queue_table' can specify the schema where to create to queue table ([schema.]queue_table) + * Queue table names cannot be longer than 24 characters (Oracle limit for user queue tables) + * + * @note + * Possible values for parameter 'queue_payload_type' : + * - For Oracle types (UDT) : use the type name ([schema.].type_name) + * - For RAW data : use "SYS.RAW" or "RAW" + * + * @note + * Possible values for parameter 'message_grouping' : + * - OCI_AGM_NONE : each message is treated individually + * - OCI_AGM_TRANSACTIONNAL : all messages enqueued in one transaction are considered part of + * the same group and can be dequeued as a group of related messages. + * + * @note + * Possible values for parameter 'compatible' : + * - "8.0", "8.1", "10.0" + * + * To set default values, pass : + * - storage_clause : NULL + * - sort_list : NULL + * - message_grouping : OCI_AGM_NONE + * - comment : NULL + * - primary_instance : 0 + * - primary_instance : 0 + * - compatible : NULL + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.CREATE_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTableCreate +( + OCI_Connection *con, + const otext *queue_table, + const otext *queue_payload_type, + const otext *storage_clause, + const otext *sort_list, + boolean multiple_consumers, + unsigned int message_grouping, + const otext *comment, + unsigned int primary_instance, + unsigned int secondary_instance, + const otext *compatible +); + +/** + * @brief + * Alter the given queue table + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param comment - Description of the queue table + * @param primary_instance - primary owner (instance) of the queue table + * @param secondary_instance - Owner of the queue table if the primary instance is not available + * + * @note + * See OCI_QueueTableCreate() from more details + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.ALTER_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTableAlter +( + OCI_Connection *con, + const otext *queue_table, + const otext *comment, + unsigned int primary_instance, + unsigned int secondary_instance +); + +/** + * @brief + * Drop the given queue table + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param force - Force the deletion of objects related to the queue table + * + * @note + * Possible values for 'force' : + * - TRUE : all queues using the queue table and their associated propagation schedules are + * dropped automatically + * - FALSE : All the queues using the given queue table must be stopped and dropped before the + * queue table can be dropped. + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.DROP_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTableDrop +( + OCI_Connection *con, + const otext *queue_table, + boolean force +); + +/** + * @brief + * Purge messages from the given queue table + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param purge_condition - Optional SQL based conditions (see notes) + * @param block - Lock all queues using the queue table while doing the purge + * @param delivery_mode - Type of message to purge + * + * @note + * Possible values for parameter 'delivery_mode' : + * - OCI_APM_BUFFERED : purge only buffered messages + * - OCI_APM_PERSISTENT : purge only persistent messages + * - OCI_APM_ALL : purge all messages + * + * @note + * For more information about the SQL purge conditions, refer to + * Oracle Streams - Advanced Queuing User's Guide for more details + * + * @warning + * This feature is only available from ORacle 10gR2. + * This function does nothing and returns TRUE is the server version is < Oracle 10gR2 + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.PURGE_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTablePurge +( + OCI_Connection *con, + const otext *queue_table, + const otext *purge_condition, + boolean block, + unsigned int delivery_mode +); + +/** + * @brief + * Migrate a queue table from one version to another + * + * @param con - Connection handle + * @param queue_table - Queue table name + * @param compatible - Database version with witch the queue table has to migrate + * + * @note + * Possible values for parameter 'compatible' : + * - "8.0", "8.1", "10.0" + * + * @note + * this call wraps the PL/SQL procedure DBMS_AQADM.MIGRATE_QUEUE_TABLE(). + * Refer to Oracle Streams - Advanced Queuing User's Guide for more details + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_QueueTableMigrate +( + OCI_Connection *con, + const otext *queue_table, + const otext *compatible +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiSubscriptions Database Change notifications (DCN or CQN) + * @{ + * + * OCILIB supports Oracle 10gR2 feature Database Change Notifications (DCN) + * also named Continuous Query Notifications (CQN) + * + * This features allows a client application to register notifications + * when some changes are made in a database : + * - Database status changes : startup and shutdown + * - Database objects changes : + * - DDL changes : alter or drop actions + * - DML changes : insert, delete, update actions + * + * This feature can be really useful in applications that hold + * a cache of data. Instead of refreshing data periodically by + * connecting to the server, the application could only refresh + * modified data when necessary or perform specific tasks depending on + * the events. It saves application time, network traffic and can help + * the design of the application logic. + * + * The database status change notification is also interesting to be + * informed of instance startup / shutdown + * + * Check Oracle documentation for more details about this feature + * + * @note + * No active database connection is required to receive the + * notifications as they are handled by the Oracle client using a + * dedicated socket connection to the server + * + * @par Database changes + * + * The client application can be notified of any database status + * change (single DB or multiple DB in a RAC environment). + * + * @par Object changes + * + * The notifications of object changes are based on the registration + * of a query ('select' SQL statement). + * + * Oracle server will notify of any changes of any object that is + * part of the statement result set. + * + * Registering a statement will notify about any changes on its + * result set rows performed after the registration of the query. + * + * The query can be a simple 'select * from table' or a complex + * query involving many tables and/or criteria in the where clause. + * + * For Object changes, the notification can be at : + * - At Object level : only the object name (schema + object) is given + * - At row level : same that object level + RowID of the altered row + * + * @warning + * Trying to use this features with a client/server version < 10gR2 will raise an error + * + * @par Example + * @include notification.c + * + */ + +/** + * @brief + * Register a notification against the given database + * + * @param con - Connection handle + * @param name - Notification name + * @param type - Subscription type + * @param handler - User handler callback + * @param port - Port to use for notifications + * @param timeout - notification timeout + * + * @note + * Parameter 'type' can be one of the following values : + * + * - OCI_CNT_OBJECTS : request for changes at objects (e.g. tables) level (DDL / DML) + * - OCI_CNT_ROWS : request for changes at rows level (DML) + * - OCI_CNT_DATABASES : request for changes at database level (startup, shutdown) + * - OCI_CNT_ALL : request for all changes + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @note + * Requires Oracle Client 10gR2 or above + * + * @note + * Subscription handles are automatically managed by the library + * + * @return + * Subscription handle on success or NULL on failure + * + */ + +OCI_EXPORT OCI_Subscription * OCI_API OCI_SubscriptionRegister +( + OCI_Connection *con, + const otext *name, + unsigned int type, + POCI_NOTIFY handler, + unsigned int port, + unsigned int timeout +); + +/** + * @brief + * Unregister a previously registered notification + * + * @param sub - Subscription handle + * + * @note + * OCI_Cleanup() will automatically unregister any registered subscriptions + * + * @note + * If the database connection passed to OCI_SubscriptionRegister() + * has been closed by the time that the application calls + * OCI_SubscriptionUnregister, the library internally reconnects + * to the given database, performs the unregistration and then disconnects + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SubscriptionUnregister +( + OCI_Subscription *sub +); + +/** + * @brief + * Add a statement to the notification to monitor + * + * @param sub - Subscription handle + * @param stmt - Statement handle + * + * @note + * The given statement must be prepared but not executed before being passed to this function. + * OCI_SubscriptionAddStatement() executes the statement and register it for notifications + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @note + * The given statement must hold a 'SELECT' SQL statement + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_SubscriptionAddStatement +( + OCI_Subscription *sub, + OCI_Statement *stmt +); + +/** + * @brief + * Return the name of the given registered subscription + * + * @param sub - Subscription handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT const otext * OCI_API OCI_SubscriptionGetName +( + OCI_Subscription *sub +); + +/** + * @brief + * Return the port used by the notification + * + * @param sub - Subscription handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_SubscriptionGetPort +( + OCI_Subscription *sub +); + +/** + * @brief + * Return the timeout of the given registered subscription + * + * @param sub - Subscription handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_SubscriptionGetTimeout +( + OCI_Subscription *sub +); + +/** + * @brief + * Return the connection handle associated with a subscription handle + * + * @param sub - Subscription handle + * + * @note + * It may return a NULL handle if the connection used in OCI_SubscriptionRegister has been closed. + * + */ + +OCI_EXPORT OCI_Connection * OCI_API OCI_SubscriptionGetConnection +( +OCI_Subscription *sub +); + +/** + * @brief + * Return the type of event reported by a notification + * + * @param event - Event handle + * + * @note + * The returned value can be one of the following values : + * + * - OCI_ENT_STARTUP : a database has been started up + * - OCI_ENT_SHUTDOWN : a database has been shut down + * - OCI_ENT_SHUTDOWN_ANY : a database has been shut down (RAC) + * - OCI_ENT_DROP_DATABASE : a database has been dropped + * - OCI_ENT_DEREGISTER : the notification is timed out + * - OCI_ENT_OBJECT_CHANGED : a database object has been modified + * + * @note + * OCI_EventGetDatabase() returns the affected database + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @note + * OCI_EventGetObject() returns the affected object + * ('schema_name'.'object_name') + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_EventGetType +( + OCI_Event *event +); + +/** + * @brief + * Return the type of operation reported by a notification + * + * @param event - Event handle + * + * @note + * This call is only valid when OCI_EventGetType() reports the + * event type OCI_ENT_OBJECT_CHANGED + * + * @note + * The returned value can be one of the following values : + * + * - OCI_ONT_INSERT : an insert has been performed + * - OCI_ONT_UPDATE : an update has been performed + * - OCI_ONT_DELETE : a delete has been performed + * - OCI_ONT_ALTER : an alter has been performed + * - OCI_ONT_DROP : a drop has been performed + * - OCI_ONT_GENERIC : generic undefined action + * + * @note + * OCI_EventGetDatabase() returns the affected database + * + * @note + * OCI_EventGetObject() returns the affected object ('schema_name'.'object_name') + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + * @note + * if OCI_CNT_ROWS is passed to OCI_SubscriptionRegister(), + * the rowid of the altered row can be retrieved with OCI_EventGetRowid() + * + */ + +OCI_EXPORT unsigned int OCI_API OCI_EventGetOperation +( + OCI_Event *event +); + +/** + * @brief + * Return the name of the database that generated the event + * + * @param event - Event handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT const otext * OCI_API OCI_EventGetDatabase +( + OCI_Event *event +); + +/** + * @brief + * Return the name of the object that generated the event + * + * @param event - Event handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT const otext * OCI_API OCI_EventGetObject +( + OCI_Event *event +); + +/** + * @brief + * Return the rowid of the altered database object row + * + * @param event - Event handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT const otext * OCI_API OCI_EventGetRowid +( + OCI_Event *event +); + +/** + * @brief + * Return the subscription handle that generated this event + * + * @param event - Event handle + * + * @note + * OCI_ENV_EVENTS flag must be passed to OCI_Initialize() to be able to use + * subscriptions + * + */ + +OCI_EXPORT OCI_Subscription * OCI_API OCI_EventGetSubscription +( + OCI_Event *event +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiInstancesManagement Remote Instance startup/shutdown + * @{ + * + * OCILIB supports Oracle 11g client features for manipulating remote Oracle instances. + * + * Oracle instances (on the same computer or on a remote server) can be : + * + * - started with OCI_DatabaseStartup() + * - shutdown with OCI_DatabaseShutdown() + * + * Several options are handled for this actions + * + * @par Example + * @include instance.c + * + */ + +/** + * @brief + * Start a database instance + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param sess_mode - Session mode + * @param start_mode - Start mode + * @param start_flag - Start flags + * @param spfile - Client-side spfile to start up the database (optional) + * + * Possible values for parameter sess_mode : + * - OCI_SESSION_SYSDBA + * - OCI_SESSION_SYSOPER + * + * @note + * External credentials are supported by supplying a null value for the 'user' and 'pwd' parameters + * If the param 'db' is NULL then a connection to the default local DB is done + * + * Possible (combined) values for parameter start_mode : + * - OCI_DB_SPM_START : start the instance + * - OCI_DB_SPM_MOUNT : mount the instance + * - OCI_DB_SPM_OPEN : open the instance + * - OCI_DB_SPM_FULL : start, mount and open the instance + * + * Possible (combined) values for parameter start_flag : + * - OCI_DB_SPF_DEFAULT : default startup + * - OCI_DB_SPF_FORCE : shuts down a running instance (if needed) using + * ABORT command and starts a new instance + * - OCI_DB_SPF_RESTRICT : allows database access only to users with both + * CREATE SESSION and RESTRICTED SESSION privileges + * + * @note + * If the client side spfile is not provided, the database is started with its server-side spfile + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DatabaseStartup +( + const otext *db, + const otext *user, + const otext *pwd, + unsigned int sess_mode, + unsigned int start_mode, + unsigned int start_flag, + const otext *spfile +); + +/** + * @brief + * Shutdown a database instance + * + * @param db - Oracle Service Name + * @param user - Oracle User name + * @param pwd - Oracle User password + * @param sess_mode - Session mode + * @param shut_mode - Shutdown mode + * @param shut_flag - Shutdown flag + * + * + * @warning + * Possible values for parameter sess_mode : + * - OCI_SESSION_SYSDBA + * - OCI_SESSION_SYSOPER + * + * @note + * External credentials are supported by supplying a null value for the 'user' and 'pwd' parameters + * If the param 'db' is NULL then a connection to the default local DB is done + * + * Possible (combined) values for parameter shut_mode : + * - OCI_DB_SDM_SHUTDOWN : shutdown the instance + * - OCI_DB_SDM_CLOSE : close the instance + * - OCI_DB_SDM_DISMOUNT : dismount the instance + * - OCI_DB_SDM_FULL : shutdown, close and dismount the instance + * + * Possible (exclusive) value for parameter shut_flag (from Oracle documentation) : + * - OCI_DB_SDF_DEFAULT : + * - Further connects are prohibited. + * - Waits for users to disconnect from the database + * - OCI_DB_SDF_TRANS : + * - Further connects are prohibited + * - No new transactions are allowed. + * - Waits for active transactions to complete + * - OCI_DB_SDF_TRANS_LOCAL : + * - Further connects are prohibited + * - No new transactions are allowed. + * - Waits only for local transactions to complete + * - OCI_DB_SDF_IMMEDIATE : + * - Does not wait for current calls to complete or users to disconnect from the database. + * - All uncommitted transactions are terminated and rolled back + * - OCI_DB_SDF_ABORT : + * - Does not wait for current calls to complete or users to disconnect from the database. + * - All uncommitted transactions are terminated and are not rolled back. + * - This is the fastest possible way to shut down the database, but the next + * database startup may require instance recovery. + * - Therefore, this option should be used only in unusual circumstances + * + * @return + * TRUE on success otherwise FALSE + * + */ + +OCI_EXPORT boolean OCI_API OCI_DatabaseShutdown +( + const otext *db, + const otext *user, + const otext *pwd, + unsigned int sess_mode, + unsigned int shut_mode, + unsigned int shut_flag +); + +/** + * @} + */ + +/** + * @defgroup OcilibCApiRawHandles Using OCI Handles directly + * @{ + * + * OCILIB conception was focused on a full but closed encapsulation of OCI. + * + * All OCI headers, data types, prototypes are imported internally + * (linkage or runtime import). + * + * OCILIB public interface exposes only ISO C scalar types and OCILIB objects + * + * OCI is a wide and rich API that can deals with hundreds of options ! + * + * OCILIB tries to implements most of it. But, sometimes in really specific + * contexts, it might be necessary to directly call OCI APIs in order to use + * uncovered OCI functionalities or options + * + * OCILIB proposes now a set of functions to retrieve its internal OCI handles + * + * @warning + * + * The OCILIB author strongly advises against the use of internal handles, + * unless there is no other way to accomplish the task + * + * @warning + * + * Using these handles for direct application calls to OCI might lead + * to OCILIB instability or crash if handles are incorrectly used ! + * + */ + +/** + * @brief + * Return the OCI Environment Handle (OCIEnv *) of OCILIB library + * + * @return + * OCI Environment handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetEnvironment +( + void +); + +/** + * @brief + * Return the OCI Context Handle (OCISvcCtx *) of an OCILIB OCI_Connection object + * + * @param con - Connection handle + * + * @return + * OCI Context handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetContext +( + OCI_Connection *con +); + +/** + * @brief + * Return the OCI Server Handle (OCIServer *) of an OCILIB OCI_Connection object + * + * @param con - Connection handle + * + * @return + * OCI Server handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetServer +( + OCI_Connection *con +); + +/** + * @brief + * Return the OCI Error Handle (OCIError *) of an OCILIB OCI_Connection object + * + * @param con - Connection handle + * + * @return + * OCI Error handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetError +( + OCI_Connection *con +); + +/** + * @brief + * Return the OCI Session Handle (OCISession *) of an OCILIB OCI_Connection object + * + * @param con - Connection handle + * + * @return + * OCI Session handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetSession +( + OCI_Connection *con +); + +/** + * @brief + * Return the OCI Transaction Handle (OCITrans *) of an OCILIB OCI_Transaction object + * + * @param trans - Transaction handle + * + * @return + * OCI Transaction handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetTransaction +( + OCI_Transaction *trans +); + +/** + * @brief + * Return the OCI Statement Handle (OCIStmt *) of an OCILIB OCI_Statement object + * + * @param stmt - Statement handle + * + * @return + * OCI Statement handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetStatement +( + OCI_Statement *stmt +); + +/** + * @brief + * Return the OCI LobLocator Handle (OCILobLocator *) of an OCILIB OCI_Lob object + * + * @param lob - Lob handle + * + * @return + * OCI LobLocator handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetLob +( + OCI_Lob *lob +); + +/** + * @brief + * Return the OCI LobLocator Handle (OCILobLocator *) of an OCILIB OCI_File object + * + * @param file - File handle + * + * @return + * OCI LobLocator handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetFile +( + OCI_File *file +); + +/** + * @brief + * Return the OCI Date Handle (OCIDate *) of an OCILIB OCI_Date object + * + * @param date - Date handle + * + * @return + * OCI Date handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetDate +( + OCI_Date *date +); + +/** + * @brief + * Return the OCI Date time Handle (OCIDatetime *) of an OCILIB OCI_Timestamp object + * + * @param tmsp - Timestamp handle + * + * @return + * OCI Date time handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetTimestamp +( + OCI_Timestamp *tmsp +); + +/** + * @brief + * Return OCI Interval Handle (OCIInterval *) of an OCILIB OCI_Interval object + * + * @param itv - Interval handle + * + * @return + * OCI Interval handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetInterval +( + OCI_Interval *itv +); + +/** + * @brief + * Return OCI Object Handle (void *) of an OCILIB OCI_Object object + * + * @param obj - Object handle + * + * @return + * OCI Object handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetObject +( + OCI_Object *obj +); + +/** + * @brief + * Return OCI Collection Handle (OCIColl *) of an OCILIB OCI_Coll object + * + * @param coll - Collection handle + * + * @return + * OCI Collection handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetColl +( + OCI_Coll *coll +); + +/** + * @brief + * Return OCI Ref Handle (OCIRef *) of an OCILIB OCI_Ref object + * + * @param ref - Ref handle + * + * @return + * OCI Ref handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetRef +( + OCI_Ref *ref +); + +/** + * @brief + * Return OCI Mutex handle (OCIThreadMutex *) of an OCILIB OCI_Mutex object + * + * @param mutex - Mutex handle + * + * @return + * OCI Mutex handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetMutex +( + OCI_Mutex *mutex +); + +/** + * @brief + * Return OCI Thread ID (OCIThreadId *) of an OCILIB OCI_Thread object + * + * @param thread - Thread handle + * + * @return + * OCI Thread ID otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetThreadID +( + OCI_Thread *thread +); + +/** + * @brief + * Return OCI Thread handle (OCIThreadHandle *) of an OCILIB OCI_Thread object + * + * @param thread - Thread handle + * + * @return + * OCI Thread handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetThread +( + OCI_Thread *thread +); + +/** + * @brief + * Return OCI DirectPath Context handle (OCIDirPathCtx *) of an OCILIB OCI_DirPath object + * + * @param dp - DirectPath handle + * + * @return + * OCI DirectPath Context handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetDirPathCtx +( + OCI_DirPath *dp +); + +/** + * @brief + * Return OCI DirectPath Column array handle (OCIDirPathColArray *) of an OCILIB OCI_DirPath object + * + * @param dp - DirectPath handle + * + * @return + * OCI DirectPath Column array handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetDirPathColArray +( + OCI_DirPath *dp +); + +/** + * @brief + * Return OCI DirectPath Stream handle (OCIDirPathStream *) of an OCILIB OCI_DirPath object + * + * @param dp - DirectPath handle + * + * @return + * OCI DirectPath Stream handle otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetDirPathStream +( + OCI_DirPath *dp +); + +/** + * @brief + * Return OCI Subscription handle (OCISubscription *) of an OCILIB OCI_Subscription object + * + * @param sub - Subscription handle + * + * @return + * OCI Subscription otherwise NULL + * + */ + +OCI_EXPORT const void * OCI_API OCI_HandleGetSubscription +( + OCI_Subscription *sub +); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +/** +* @defgroup OcilibCApiEnvironmentVariables Environment Variables +* @{ +* +* Some environment variables can be defined in order to activate specific features +* They must have one of the following values (case insensitive) for being enabled : "TRUE", "1" +* +* - "OCILIB_WORKAROUND_UTF16_COLUMN_NAME": This variable enables an experimental workaround for the Oracle bug 9838993: +* - When calling OCI_GetResultset(), OCILIB queries column names against the Oracle Client +* - Unicode builds of OCILIB initialize Oracle client into UTF16 mode +* - In such environments, a memory leak occurs when statements are re-executed multiple times followed by OCI_GetResultset() +* - This workaround retrieves column names using direct access to undocumented Oracle structures instead of using buggy Oracle calls +* - As Oracle undocumented structures may change upon versions, this workaround is provided as-is in case the Oracle bug represents an real issue for applications +* - This workaround has been tested with 32bit and 64bit Oracle 12g clients and Unicode OCILIB builds +*/ + +#define VAR_OCILIB_WORKAROUND_UTF16_COLUMN_NAME "OCILIB_WORKAROUND_UTF16_COLUMN_NAME" + +/** +* @} +*/ + +/** + * @defgroup OcilibCApiDemoApplication OCILIB main demo application code + * @{ + * + * Portable Main demo application header + * @include ocilib_demo.h + * + * Portable Main demo application source + * @include ocilib_demo.c + * + * @} + */ + +/* Compatibility with sources built with older versions of OCILIB */ + +/* macros added in version 2.3.0 */ + +#define OCI_CreateConnection OCI_ConnectionCreate +#define OCI_FreeConnection OCI_ConnectionFree +#define OCI_CreateStatement OCI_StatementCreate +#define OCI_FreeStatement OCI_StatementFree + +/* macros added in version 2.4.0 */ + +#define OCI_CreateTransaction OCI_TransactionCreate +#define OCI_FreeTransaction OCI_TransactionFree +#define OCI_CreateHashTable OCI_HashCreate +#define OCI_FreeHashTable OCI_HashFree + +/* macros added in version 3.0.0 */ + +#define OCI_GetColumnName OCI_ColumnGetName +#define OCI_GetColumnType OCI_ColumnGetType +#define OCI_GetColumnCharsetForm OCI_ColumnGetCharsetForm +#define OCI_GetColumnSQLType OCI_ColumnGetSQLType +#define OCI_GetColumnFullSQLType OCI_ColumnGetFullSQLType +#define OCI_GetColumnSize OCI_ColumnGetSize +#define OCI_GetColumnScale OCI_ColumnGetScale +#define OCI_GetColumnPrecision OCI_ColumnGetPrecision +#define OCI_GetColumnFractionnalPrecision OCI_ColumnGetFractionnalPrecision +#define OCI_GetColumnLeadingPrecision OCI_ColumnGetLeadingPrecision +#define OCI_GetColumnNullable OCI_ColumnGetNullable +#define OCI_GetColumnCharUsed OCI_ColumnGetCharUsed + +#define OCI_GetFormatDate(s) OCI_GetDefaultFormatDate(OCI_StatementGetConnection(s)) +#define OCI_SetFormatDate(s, f) OCI_SetDefaultFormatDate(OCI_StatementGetConnection(s), f) + +#define OCI_ERR_API OCI_ERR_ORACLE + +/* macros added in version 3.2.0 */ + +#define OCI_ERR_NOT_SUPPORTED OCI_ERR_DATATYPE_NOT_SUPPORTED +#define OCI_SCHEMA_TABLE OCI_TIF_TABLE +#define OCI_SCHEMA_VIEW OCI_TIF_VIEW +#define OCI_SCHEMA_TYPE OCI_TIF_TYPE + +#define OCI_Schema OCI_TypeInfo + +#define OCI_SchemaGet OCI_TypeInfoGet +#define OCI_SchemaFree OCI_TypeInfoFree +#define OCI_SchemaGetColumnCount OCI_TypeInfoGetColumnCount +#define OCI_SchemaGetColumn OCI_TypeInfoGetColumn +#define OCI_SchemaGetName OCI_TypeInfoGetName + +#define OCI_ColumnGetFractionnalPrecision OCI_ColumnGetFractionalPrecision + +/* macro added in version 3.3.0 */ + +/** + * @brief + * [OBSOLETE] Set the bind variable at the given index to null + * + * @param stmt - Statement handle + * @param index - Index of the bind variable + * + * @warning + * This call is obsolete ! Use OCI_BindSetNull() instead. + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Index starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +#define OCI_SetNull(stmt, index) \ + OCI_BindSetNull(OCI_GetBind(stmt, index)) + +/** + * @brief + * [OBSOLETE] Set the bind variable of the given name to null + * + * @param stmt - Statement handle + * @param name - Bind variable name + * + * @warning + * This call is obsolete ! Use OCI_BindSetNull() instead. + * + * @note + * There is no notion of null value in C. + * it's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + */ + +#define OCI_SetNull2(stmt, name) \ + OCI_BindSetNull(OCI_GetBind2(stmt, name)) + +/** + * @brief + * [OBSOLETE] Set to null the bind variable at the given position in an input array + * + * @param stmt - Statement handle + * @param index - Index of the bind variable + * @param position - Position in the array + * + * @warning + * This call is obsolete ! Use OCI_BindSetNullAtPos() instead. + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Index and Position starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + * + */ + +#define OCI_SetNullAtPos(stmt, index, position) \ + OCI_BindSetNullAtPos(OCI_GetBind(stmt, index), position) + +/** + * @brief + * [OBSOLETE] Set to null the bind variable of the given name in an input array + * + * @param stmt - Statement handle + * @param name - Bind variable name + * @param position - Position in the array + * + * @warning + * This call is obsolete ! Use OCI_BindSetNullAtPos() instead. + * + * @note + * There is no notion of null value in C. + * It's necessary to explicitly tell Oracle that the bind has a null value. + * It must be done before an OCI_Execute() call + * + * @warning + * Position starts with 1 + * + * @note + * For handled based data types (non scalar types), OCILIB performs an extra + * check on handles and set the bind status to null is the handle is null + * + * @return + * TRUE on success otherwise FALSE + * + */ + +#define OCI_SetNullAtPos2(stmt, name, position) \ + OCI_BindSetNullAtPos(OCI_GetBind2(stmt, name), position) + +/* macro added in version 3.4.0 */ + +#define OCI_8 OCI_8_1 +#define OCI_9 OCI_9_0 +#define OCI_10 OCI_10_1 +#define OCI_11 OCI_11_1 + +/* macro added in version 3.6.0 */ + +#define OCI_CHAR_UNICODE OCI_CHAR_WIDE +#define OCI_CSF_CHARSET OCI_CSF_DEFAULT + +/* macro added in version 3.7.0 */ + +#define OCI_ConnPool OCI_Pool + +#define OCI_ConnPoolCreate(db, us, pw, mo, mi, ma, in) \ + OCI_PoolCreate(db, us, pw, OCI_POOL_CONNECTION, mo, mi, ma, in) + +#define OCI_ConnPoolGetConnection(p) \ + OCI_PoolGetConnection(p, NULL) + +#define OCI_ConnPoolFree OCI_PoolFree +#define OCI_ConnPoolGetTimeout OCI_PoolGetConnection +#define OCI_ConnPoolSetTimeout OCI_PoolSetTimeout +#define OCI_ConnPoolGetNoWait OCI_PoolGetNoWait +#define OCI_ConnPoolSetNoWait OCI_PoolSetNoWait +#define OCI_ConnPoolGetBusyCount OCI_PoolGetBusyCount +#define OCI_ConnPoolGetOpenedCount OCI_PoolGetOpenedCount +#define OCI_ConnPoolGetMin OCI_PoolGetMin +#define OCI_ConnPoolGetMax OCI_PoolGetMax +#define OCI_ConnPoolGetIncrement OCI_PoolGetIncrement + +/* macro added in version 3.8.0 */ + +#define OCI_ObjectGetTimeStamp OCI_ObjectGetTimestamp +#define OCI_ElemGetTimeStamp OCI_ElemGetTimestamp +#define OCI_TimestampSysTimeStamp OCI_TimestampSysTimestamp + +/* macro added in version 4.0.0 */ + +#define OCI_CollSetAt OCI_CollSetElem +#define OCI_CollGetAt OCI_CollGetElem +#define OCI_CollGetAt2 OCI_CollGetElem2 + +#define OCI_GetCharsetMetaData OCI_GetCharset +#define OCI_GetCharsetUserData OCI_GetCharset +#define OCI_SIZE_TRACE_INF0 OCI_SIZE_TRACE_INFO + +#define MT(x) OTEXT(x) +#define mtext otext +#define DT(x) OTEXT(x) +#define dtext otext + +#define mtsdup ostrdup +#define mtscpy ostrcpy +#define mtsncpy ostrncpy +#define mtscat ostrcat +#define mtsncat ostrncat +#define mtslen ostrlen +#define mtscmp ostrcmp +#define mtscasecmp ostrcasecmp +#define mtsprintf osprintf +#define mtstol ostrtol +#define mtsscanf osscanf + +#define dtsdup ostrdup +#define dtscpy ostrcpy +#define dtsncpy ostrncpy +#define dtscat ostrcat +#define dtsncat ostrncat +#define dtslen ostrlen +#define dtscmp ostrcmp +#define dtscasecmp ostrcasecmp +#define dtsprintf osprintf +#define dtstol ostrtol +#define dtsscanf osscanf + +/* macro added in version 4.1.0 */ + +#define OCI_SetDefaultFormatDate(con, fmt) OCI_SetFormat(con, OCI_FMT_DATE, fmt) +#define OCI_SetDefaultFormatNumeric(con, fmt) OCI_SetFormat(con, OCI_FMT_NUMERIC, fmt) + +#define OCI_GetDefaultFormatDate(con) OCI_GetFormat(con, OCI_FMT_DATE) +#define OCI_GetDefaultFormatNumeric(con) OCI_GetFormat(con, OCI_FMT_NUMERIC) + +#define OCI_STRING_FORMAT_NUM_BIN OCI_STRING_FORMAT_NUM_BDOUBLE + +/** + * @} + */ + +#endif /* OCILIB_H_INCLUDED */ + diff --git a/ocilib/4.4.0/Linux-x86_64/libocilib.so.4 b/ocilib/4.4.0/Linux-x86_64/libocilib.so.4 new file mode 100755 index 0000000000000000000000000000000000000000..8808902793b62f9cba57453d0ae93459e2f40272 Binary files /dev/null and b/ocilib/4.4.0/Linux-x86_64/libocilib.so.4 differ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qgrow.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qgrow.h new file mode 100755 index 0000000000000000000000000000000000000000..bad982832ab4b87eb95bdec4de207e8b35f102c9 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qgrow.h @@ -0,0 +1,99 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Grow container that handles growable objects. + * + * @file qgrow.h + */ + +#ifndef QGROW_H +#define QGROW_H + +#include +#include +#include +#include "qlist.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qgrow_s qgrow_t; + +/* public functions */ +enum { + QGROW_THREADSAFE = (QLIST_THREADSAFE) /*!< make it thread-safe */ +}; + +extern qgrow_t *qgrow(int options); + +extern bool qgrow_add(qgrow_t *grow, const void *object, size_t size); +extern bool qgrow_addstr(qgrow_t *grow, const char *str); +extern bool qgrow_addstrf(qgrow_t *grow, const char *format, ...); + +extern size_t qgrow_size(qgrow_t *grow); +extern size_t qgrow_datasize(qgrow_t *grow); + +extern void *qgrow_toarray(qgrow_t *grow, size_t *size); +extern char *qgrow_tostring(qgrow_t *grow); + +extern void qgrow_clear(qgrow_t *grow); +extern bool qgrow_debug(qgrow_t *grow, FILE *out); +extern void qgrow_free(qgrow_t *grow); + +/** + * qgrow container object + */ +struct qgrow_s { + /* capsulated member functions */ + bool (*add) (qgrow_t *grow, const void *data, size_t size); + bool (*addstr) (qgrow_t *grow, const char *str); + bool (*addstrf) (qgrow_t *grow, const char *format, ...); + + size_t (*size) (qgrow_t *grow); + size_t (*datasize) (qgrow_t *grow); + + void *(*toarray) (qgrow_t *grow, size_t *size); + char *(*tostring) (qgrow_t *grow); + + void (*clear) (qgrow_t *grow); + bool (*debug) (qgrow_t *grow, FILE *out); + + void (*free) (qgrow_t *grow); + + /* private variables - do not access directly */ + qlist_t *list; /*!< data container */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QGROW_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qhasharr.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qhasharr.h new file mode 100755 index 0000000000000000000000000000000000000000..9a6278fe54a41e84fe1c4ed1aa0daddc8cb1b228 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qhasharr.h @@ -0,0 +1,174 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Static Hash Table container that works in preallocated fixed size memory. + * + * @file qhasharr.h + */ + +#ifndef QHASHARR_H +#define QHASHARR_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* tunable knobs */ +#define Q_HASHARR_NAMESIZE (16) /*!< knob for maximum key size. */ +#define Q_HASHARR_DATASIZE (32) /*!< knob for maximum data size in a slot. */ + +/* types */ +typedef struct qhasharr_s qhasharr_t; +typedef struct qhasharr_slot_s qhasharr_slot_t; +typedef struct qhasharr_data_s qhasharr_data_t; +typedef struct qhasharr_obj_s qhasharr_obj_t; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->put(tbl, ...); // easier to switch the container type to other kinds. + * - qhasharr_put(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qhasharr_t *qhasharr(void *memory, size_t memsize); +extern size_t qhasharr_calculate_memsize(int max); + +extern bool qhasharr_put(qhasharr_t *tbl, const char *key, const void *value, + size_t size); +extern bool qhasharr_putstr(qhasharr_t *tbl, const char *key, const char *str); +extern bool qhasharr_putstrf(qhasharr_t *tbl, const char *key, const char *format, ...); +extern bool qhasharr_put_by_obj(qhasharr_t *tbl, const void *name, size_t namesize, + const void *data, size_t datasize); + +extern void *qhasharr_get(qhasharr_t *tbl, const char *key, size_t *size); +extern char *qhasharr_getstr(qhasharr_t *tbl, const char *key); +extern void *qhasharr_get_by_obj(qhasharr_t *tbl, const void *name, size_t namesize, + size_t *datasize); + +extern bool qhasharr_remove(qhasharr_t *tbl, const char *key); +extern bool qhasharr_remove_by_obj(qhasharr_t *tbl, const char *name, size_t namesize); +extern bool qhasharr_remove_by_idx(qhasharr_t *tbl, int idx); + +extern bool qhasharr_getnext(qhasharr_t *tbl, qhasharr_obj_t *obj, int *idx); + +extern int qhasharr_size(qhasharr_t *tbl, int *maxslots, int *usedslots); +extern void qhasharr_clear(qhasharr_t *tbl); +extern bool qhasharr_debug(qhasharr_t *tbl, FILE *out); + +extern void qhasharr_free(qhasharr_t *tbl); + + +/** + * qhasharr container object + */ +struct qhasharr_s { + /* encapsulated member functions */ + bool (*put) (qhasharr_t *tbl, const char *key, const void *value, + size_t size); + bool (*putstr) (qhasharr_t *tbl, const char *key, const char *str); + bool (*putstrf) (qhasharr_t *tbl, const char *key, const char *format, ...); + bool (*put_by_obj) (qhasharr_t *tbl, const void *name, size_t namesize, + const void *data, size_t datasize); + + void *(*get) (qhasharr_t *tbl, const char *key, size_t *size); + char *(*getstr) (qhasharr_t *tbl, const char *key); + void *(*get_by_obj) (qhasharr_t *tbl, const void *name, size_t namesize, + size_t *datasize); + + bool (*remove) (qhasharr_t *tbl, const char *key); + bool (*remove_by_obj) (qhasharr_t *tbl, const char *name, size_t namesize); + bool (*remove_by_idx) (qhasharr_t *tbl, int idx); + + bool (*getnext) (qhasharr_t *tbl, qhasharr_obj_t *obj, int *idx); + + int (*size) (qhasharr_t *tbl, int *maxslots, int *usedslots); + void (*clear) (qhasharr_t *tbl); + bool (*debug) (qhasharr_t *tbl, FILE *out); + + void (*free) (qhasharr_t *tbl); + + /* private variables */ + qhasharr_data_t *data; +}; + +/** + * qhasharr internal data slot structure + */ +struct qhasharr_slot_s { + short count; /*!< hash collision counter. 0 indicates empty slot, + -1 is used for collision resolution, -2 is used for + indicating linked block */ + uint32_t hash; /*!< key hash */ + uint8_t datasize; /*!< value size in this slot*/ + int link; /*!< next link */ + + union { + /*!< key/value data */ + struct Q_HASHARR_SLOT_KEYVAL { + uint8_t data[Q_HASHARR_DATASIZE]; /*!< value */ + uint8_t name[Q_HASHARR_NAMESIZE]; /*!< key string, can be cut */ + uint16_t namesize; /*!< original key length */ + uint8_t namemd5[16]; /*!< md5 hash of the key */ + } pair; + + /*!< extended data block, used only when the count value is -2 */ + struct Q_HASHARR_SLOT_EXT { + uint8_t data[sizeof(struct Q_HASHARR_SLOT_KEYVAL)]; + } ext; + } data; +}; + +/** + * qhasharr memory structure + */ +struct qhasharr_data_s { + int maxslots; /*!< number of maximum slots */ + int usedslots; /*!< number of used slots */ + int num; /*!< number of stored keys */ +}; + +/** + * qhasharr named-object data structure for user return + */ +struct qhasharr_obj_s { + void *name; /*!< name */ + size_t namesize; /*!< name size */ + void *data; /*!< data */ + size_t datasize; /*!< data size */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QHASHARR_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qhashtbl.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qhashtbl.h new file mode 100755 index 0000000000000000000000000000000000000000..ac8602925b7c4e0c1dbbf25865d59dfed702f5dc --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qhashtbl.h @@ -0,0 +1,135 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Hash Table container. + * + * @file qhashtbl.h + */ + +#ifndef QHASHTBL_H +#define QHASHTBL_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qhashtbl_s qhashtbl_t; +typedef struct qhashtbl_obj_s qhashtbl_obj_t; + +enum { + QHASHTBL_THREADSAFE = (0x01) /*!< make it thread-safe */ +}; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->put(tbl, ...); // easier to switch the container type to other kinds. + * - qhashtbl_put(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qhashtbl_t *qhashtbl(size_t range, int options); /*!< qhashtbl constructor */ + +extern bool qhashtbl_put(qhashtbl_t *tbl, const char *name, const void *data, size_t size); +extern bool qhashtbl_putstr(qhashtbl_t *tbl, const char *name, const char *str); +extern bool qhashtbl_putstrf(qhashtbl_t *tbl, const char *name, const char *format, ...); +extern bool qhashtbl_putint(qhashtbl_t *tbl, const char *name, int64_t num); + +extern void *qhashtbl_get(qhashtbl_t *tbl, const char *name, size_t *size, bool newmem); +extern char *qhashtbl_getstr(qhashtbl_t *tbl, const char *name, bool newmem); +extern int64_t qhashtbl_getint(qhashtbl_t *tbl, const char *name); + +extern bool qhashtbl_remove(qhashtbl_t *tbl, const char *name); + +extern bool qhashtbl_getnext(qhashtbl_t *tbl, qhashtbl_obj_t *obj, bool newmem); + +extern size_t qhashtbl_size(qhashtbl_t *tbl); +extern void qhashtbl_clear(qhashtbl_t *tbl); +extern bool qhashtbl_debug(qhashtbl_t *tbl, FILE *out); + +extern void qhashtbl_lock(qhashtbl_t *tbl); +extern void qhashtbl_unlock(qhashtbl_t *tbl); + +extern void qhashtbl_free(qhashtbl_t *tbl); + +/** + * qhashtbl container object structure + */ +struct qhashtbl_s { + /* encapsulated member functions */ + bool (*put) (qhashtbl_t *tbl, const char *name, const void *data, size_t size); + bool (*putstr) (qhashtbl_t *tbl, const char *name, const char *str); + bool (*putstrf) (qhashtbl_t *tbl, const char *name, const char *format, ...); + bool (*putint) (qhashtbl_t *tbl, const char *name, const int64_t num); + + void *(*get) (qhashtbl_t *tbl, const char *name, size_t *size, bool newmem); + char *(*getstr) (qhashtbl_t *tbl, const char *name, bool newmem); + int64_t (*getint) (qhashtbl_t *tbl, const char *name); + + bool (*remove) (qhashtbl_t *tbl, const char *name); + + bool (*getnext) (qhashtbl_t *tbl, qhashtbl_obj_t *obj, bool newmem); + + size_t (*size) (qhashtbl_t *tbl); + void (*clear) (qhashtbl_t *tbl); + bool (*debug) (qhashtbl_t *tbl, FILE *out); + + void (*lock) (qhashtbl_t *tbl); + void (*unlock) (qhashtbl_t *tbl); + + void (*free) (qhashtbl_t *tbl); + + /* private variables - do not access directly */ + void *qmutex; /*!< initialized when QHASHTBL_THREADSAFE is given */ + size_t num; /*!< number of objects in this table */ + size_t range; /*!< hash range, vertical number of slots */ + qhashtbl_obj_t **slots; /*!< slot pointer container */ +}; + +/** + * qhashtbl object data structure + */ +struct qhashtbl_obj_s { + uint32_t hash; /*!< 32bit-hash value of object name */ + char *name; /*!< object name */ + void *data; /*!< data */ + size_t size; /*!< data size */ + + qhashtbl_obj_t *next; /*!< for chaining next collision object */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QHASHTBL_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qlist.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qlist.h new file mode 100755 index 0000000000000000000000000000000000000000..acf40e5ce124a4a786973bcb52acebba9556e164 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qlist.h @@ -0,0 +1,161 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Doubly Linked-list container. + * + * @file qlist.h + */ + +#ifndef QLIST_H +#define QLIST_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +enum { + QLIST_THREADSAFE = (0x01) /*!< make it thread-safe */ +}; + +/* types */ +typedef struct qlist_s qlist_t; +typedef struct qlist_obj_s qlist_obj_t; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->addlast(tbl, ...); // easier to switch the container type to other kinds. + * - qlist_addlast(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qlist_t *qlist(int options); /*!< qlist constructor */ +extern size_t qlist_setsize(qlist_t *list, size_t max); + +extern bool qlist_addfirst(qlist_t *list, const void *data, size_t size); +extern bool qlist_addlast(qlist_t *list, const void *data, size_t size); +extern bool qlist_addat(qlist_t *list, int index, const void *data, size_t size); + +extern void *qlist_getfirst(qlist_t *list, size_t *size, bool newmem); +extern void *qlist_getlast(qlist_t *list, size_t *size, bool newmem); +extern void *qlist_getat(qlist_t *list, int index, size_t *size, bool newmem); + +extern void *qlist_popfirst(qlist_t *list, size_t *size); +extern void *qlist_poplast(qlist_t *list, size_t *size); +extern void *qlist_popat(qlist_t *list, int index, size_t *size); + +extern bool qlist_removefirst(qlist_t *list); +extern bool qlist_removelast(qlist_t *list); +extern bool qlist_removeat(qlist_t *list, int index); + +extern bool qlist_getnext(qlist_t *list, qlist_obj_t *obj, bool newmem); + +extern size_t qlist_size(qlist_t *list); +extern size_t qlist_datasize(qlist_t *list); +extern void qlist_reverse(qlist_t *list); +extern void qlist_clear(qlist_t *list); + +extern void *qlist_toarray(qlist_t *list, size_t *size); +extern char *qlist_tostring(qlist_t *list); +extern bool qlist_debug(qlist_t *list, FILE *out); + +extern void qlist_lock(qlist_t *list); +extern void qlist_unlock(qlist_t *list); + +extern void qlist_free(qlist_t *list); + +/** + * qlist container object + */ +struct qlist_s { + /* encapsulated member functions */ + size_t (*setsize)(qlist_t *list, size_t max); + + bool (*addfirst)(qlist_t *list, const void *data, size_t size); + bool (*addlast)(qlist_t *list, const void *data, size_t size); + bool (*addat)(qlist_t *list, int index, const void *data, size_t size); + + void *(*getfirst)(qlist_t *list, size_t *size, bool newmem); + void *(*getlast)(qlist_t *list, size_t *size, bool newmem); + void *(*getat)(qlist_t *list, int index, size_t *size, bool newmem); + + void *(*popfirst)(qlist_t *list, size_t *size); + void *(*poplast)(qlist_t *list, size_t *size); + void *(*popat)(qlist_t *list, int index, size_t *size); + + bool (*removefirst)(qlist_t *list); + bool (*removelast)(qlist_t *list); + bool (*removeat)(qlist_t *list, int index); + + bool (*getnext)(qlist_t *list, qlist_obj_t *obj, bool newmem); + + void (*reverse)(qlist_t *list); + void (*clear)(qlist_t *list); + + size_t (*size)(qlist_t *list); + size_t (*datasize)(qlist_t *list); + + void *(*toarray)(qlist_t *list, size_t *size); + char *(*tostring)(qlist_t *list); + bool (*debug)(qlist_t *list, FILE *out); + + void (*lock)(qlist_t *list); + void (*unlock)(qlist_t *list); + + void (*free)(qlist_t *list); + + /* private variables - do not access directly */ + void *qmutex; /*!< initialized when QLIST_OPT_THREADSAFE is given */ + size_t num; /*!< number of elements */ + size_t max; /*!< maximum number of elements. 0 means no limit */ + size_t datasum; /*!< total sum of data size, does not include name size */ + + qlist_obj_t *first; /*!< first object pointer */ + qlist_obj_t *last; /*!< last object pointer */ +}; + +/** + * qlist node data structure. + */ +struct qlist_obj_s { + void *data; /*!< data */ + size_t size; /*!< data size */ + + qlist_obj_t *prev; /*!< previous link */ + qlist_obj_t *next; /*!< next link */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QLIST_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qlisttbl.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qlisttbl.h new file mode 100755 index 0000000000000000000000000000000000000000..fc3947478bc5ec59ab34f087bbe31d873419170c --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qlisttbl.h @@ -0,0 +1,180 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * List container with key/value pair in doubly linked data structure. + * + * @file qlisttbl.h + */ + +#ifndef QLISTTBL_H +#define QLISTTBL_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qlisttbl_s qlisttbl_t; +typedef struct qlisttbl_obj_s qlisttbl_obj_t; +typedef struct qlisttbl_data_s qlisttbl_data_t; + +enum { + QLISTTBL_THREADSAFE = (0x01), /*!< make it thread-safe */ + QLISTTBL_UNIQUE = (0x01 << 1), /*!< keys are unique */ + QLISTTBL_CASEINSENSITIVE = (0x01 << 2), /*!< keys are case insensitive */ + QLISTTBL_INSERTTOP = (0x01 << 3), /*!< insert new key at the top */ + QLISTTBL_LOOKUPFORWARD = (0x01 << 4), /*!< find key from the top (default: backward) */ +}; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->put(tbl, ...); // easier to switch the container type to other kinds. + * - qlisttbl_put(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qlisttbl_t *qlisttbl(int options); /*!< qlisttbl constructor */ + +extern bool qlisttbl_put(qlisttbl_t *tbl, const char *name, const void *data, size_t size); +extern bool qlisttbl_putstr(qlisttbl_t *tbl, const char *name, const char *str); +extern bool qlisttbl_putstrf(qlisttbl_t *tbl, const char *name, const char *format, ...); +extern bool qlisttbl_putint(qlisttbl_t *tbl, const char *name, int64_t num); + +extern void *qlisttbl_get(qlisttbl_t *tbl, const char *name, size_t *size, bool newmem); +extern char *qlisttbl_getstr(qlisttbl_t *tbl, const char *name, bool newmem); +extern int64_t qlisttbl_getint(qlisttbl_t *tbl, const char *name); + +extern qlisttbl_data_t *qlisttbl_getmulti(qlisttbl_t *tbl, const char *name, bool newmem, size_t *numobjs); +extern void qlisttbl_freemulti(qlisttbl_data_t *objs); + +extern size_t qlisttbl_remove(qlisttbl_t *tbl, const char *name); +extern bool qlisttbl_removeobj(qlisttbl_t *tbl, const qlisttbl_obj_t *obj); + +extern bool qlisttbl_getnext(qlisttbl_t *tbl, qlisttbl_obj_t *obj, const char *name, bool newmem); + +extern size_t qlisttbl_size(qlisttbl_t *tbl); +extern void qlisttbl_sort(qlisttbl_t *tbl, const bool reverse); +extern void qlisttbl_clear(qlisttbl_t *tbl); +extern bool qlisttbl_save(qlisttbl_t *tbl, const char *filepath, char sepchar, bool encode); +extern ssize_t qlisttbl_load(qlisttbl_t *tbl, const char *filepath, char sepchar, bool decode); + +extern bool qlisttbl_debug(qlisttbl_t *tbl, FILE *out); + +extern void qlisttbl_lock(qlisttbl_t *tbl); +extern void qlisttbl_unlock(qlisttbl_t *tbl); + +extern void qlisttbl_free(qlisttbl_t *tbl); + + + +/** + * qlisttbl container structure + */ +struct qlisttbl_s { + /* capsulated member functions */ + bool (*put) (qlisttbl_t *tbl, const char *name, const void *data, size_t size); + bool (*putstr) (qlisttbl_t *tbl, const char *name, const char *str); + bool (*putstrf) (qlisttbl_t *tbl, const char *name, const char *format, ...); + bool (*putint) (qlisttbl_t *tbl, const char *name, int64_t num); + + void *(*get) (qlisttbl_t *tbl, const char *name, size_t *size, bool newmem); + char *(*getstr) (qlisttbl_t *tbl, const char *name, bool newmem); + int64_t (*getint) (qlisttbl_t *tbl, const char *name); + + qlisttbl_data_t *(*getmulti) (qlisttbl_t *tbl, const char *name, bool newmem, size_t *numobjs); + void (*freemulti) (qlisttbl_data_t *objs); + + size_t (*remove) (qlisttbl_t *tbl, const char *name); + bool (*removeobj) (qlisttbl_t *tbl, const qlisttbl_obj_t *obj); + + bool (*getnext) (qlisttbl_t *tbl, qlisttbl_obj_t *obj, const char *name, bool newmem); + + size_t (*size) (qlisttbl_t *tbl); + void (*sort) (qlisttbl_t *tbl, const bool reverse); + void (*clear) (qlisttbl_t *tbl); + + bool (*save) (qlisttbl_t *tbl, const char *filepath, char sepchar, + bool encode); + ssize_t (*load) (qlisttbl_t *tbl, const char *filepath, char sepchar, + bool decode); + bool (*debug) (qlisttbl_t *tbl, FILE *out); + + void (*lock) (qlisttbl_t *tbl); + void (*unlock) (qlisttbl_t *tbl); + + void (*free) (qlisttbl_t *tbl); + + /* private methods */ + bool (*namematch) (qlisttbl_obj_t *obj, const char *name, uint32_t hash); + int (*namecmp) (const char *s1, const char *s2); + + /* private variables - do not access directly */ + bool unique; /*!< keys are unique */ + bool caseinsensitive; /*!< case insensitive key comparison */ + bool keepsorted; /*!< keep table in sorted (default: insertion order) */ + bool inserttop; /*!< add new key at the top. (default: bottom) */ + bool lookupforward; /*!< find keys from the top. (default: backward) */ + + void *qmutex; /*!< initialized when QLISTTBL_OPT_THREADSAFE is given */ + size_t num; /*!< number of elements */ + qlisttbl_obj_t *first; /*!< first object pointer */ + qlisttbl_obj_t *last; /*!< last object pointer */ +}; + +/** + * qlisttbl node object data structure + */ +struct qlisttbl_obj_s { + uint32_t hash; /*!< 32bit-hash value of object name */ + char *name; /*!< object name */ + void *data; /*!< data */ + size_t size; /*!< data size */ + + qlisttbl_obj_t *prev; /*!< previous link */ + qlisttbl_obj_t *next; /*!< next link */ +}; + +/** + * qlisttbl value data structure for user return + */ +struct qlisttbl_data_s { + void *data; /*!< data */ + size_t size; /*!< data size */ + uint8_t type; /*!< data type, internal use */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QLISTTBL_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qqueue.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qqueue.h new file mode 100755 index 0000000000000000000000000000000000000000..40e14f02e0253822564b8a237d11b8b224cb1450 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qqueue.h @@ -0,0 +1,116 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Queue container. + * + * @file qqueue.h + */ + +#ifndef QQUEUE_H +#define QQUEUE_H + +#include +#include +#include +#include "qlist.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qqueue_s qqueue_t; + +enum { + QQUEUE_THREADSAFE = (QLIST_THREADSAFE) /*!< make it thread-safe */ +}; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->push(tbl, ...); // easier to switch the container type to other kinds. + * - qqueue_push(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qqueue_t *qqueue(int options); +extern size_t qqueue_setsize(qqueue_t *queue, size_t max); + +extern bool qqueue_push(qqueue_t *queue, const void *data, size_t size); +extern bool qqueue_pushstr(qqueue_t *queue, const char *str); +extern bool qqueue_pushint(qqueue_t *queue, int64_t num); + +extern void *qqueue_pop(qqueue_t *queue, size_t *size); +extern char *qqueue_popstr(qqueue_t *queue); +extern int64_t qqueue_popint(qqueue_t *queue); +extern void *qqueue_popat(qqueue_t *queue, int index, size_t *size); + +extern void *qqueue_get(qqueue_t *queue, size_t *size, bool newmem); +extern char *qqueue_getstr(qqueue_t *queue); +extern int64_t qqueue_getint(qqueue_t *queue); +extern void *qqueue_getat(qqueue_t *queue, int index, size_t *size, bool newmem); + +extern size_t qqueue_size(qqueue_t *queue); +extern void qqueue_clear(qqueue_t *queue); +extern bool qqueue_debug(qqueue_t *queue, FILE *out); +extern void qqueue_free(qqueue_t *queue); + +/** + * qqueue container object structure + */ +struct qqueue_s { + /* encapsulated member functions */ + size_t (*setsize) (qqueue_t *stack, size_t max); + + bool (*push) (qqueue_t *stack, const void *data, size_t size); + bool (*pushstr) (qqueue_t *stack, const char *str); + bool (*pushint) (qqueue_t *stack, int64_t num); + + void *(*pop) (qqueue_t *stack, size_t *size); + char *(*popstr) (qqueue_t *stack); + int64_t (*popint) (qqueue_t *stack); + void *(*popat) (qqueue_t *stack, int index, size_t *size); + + void *(*get) (qqueue_t *stack, size_t *size, bool newmem); + char *(*getstr) (qqueue_t *stack); + int64_t (*getint) (qqueue_t *stack); + void *(*getat) (qqueue_t *stack, int index, size_t *size, bool newmem); + + size_t (*size) (qqueue_t *stack); + void (*clear) (qqueue_t *stack); + bool (*debug) (qqueue_t *stack, FILE *out); + void (*free) (qqueue_t *stack); + + /* private variables - do not access directly */ + qlist_t *list; /*!< data container */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QQUEUE_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qstack.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qstack.h new file mode 100755 index 0000000000000000000000000000000000000000..e18eaffc9eb9d0cf21cc986e45174c498067c1f9 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qstack.h @@ -0,0 +1,116 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * LIFO Stack container. + * + * @file qstack.h + */ + +#ifndef QSTACK_H +#define QSTACK_H + +#include +#include +#include +#include "qlist.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qstack_s qstack_t; + +enum { + QSTACK_THREADSAFE = (QLIST_THREADSAFE) /*!< make it thread-safe */ +}; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->push(tbl, ...); // easier to switch the container type to other kinds. + * - qstack_push(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qstack_t *qstack(int options); +extern size_t qstack_setsize(qstack_t *stack, size_t max); + +extern bool qstack_push(qstack_t *stack, const void *data, size_t size); +extern bool qstack_pushstr(qstack_t *stack, const char *str); +extern bool qstack_pushint(qstack_t *stack, int64_t num); + +extern void *qstack_pop(qstack_t *stack, size_t *size); +extern char *qstack_popstr(qstack_t *stack); +extern int64_t qstack_popint(qstack_t *stack); +extern void *qstack_popat(qstack_t *stack, int index, size_t *size); + +extern void *qstack_get(qstack_t *stack, size_t *size, bool newmem); +extern char *qstack_getstr(qstack_t *stack); +extern int64_t qstack_getint(qstack_t *stack); +extern void *qstack_getat(qstack_t *stack, int index, size_t *size, bool newmem); + +extern size_t qstack_size(qstack_t *stack); +extern void qstack_clear(qstack_t *stack); +extern bool qstack_debug(qstack_t *stack, FILE *out); +extern void qstack_free(qstack_t *stack); + +/** + * qstack container object structure + */ +struct qstack_s { + /* encapsulated member functions */ + size_t (*setsize) (qstack_t *stack, size_t max); + + bool (*push) (qstack_t *stack, const void *data, size_t size); + bool (*pushstr) (qstack_t *stack, const char *str); + bool (*pushint) (qstack_t *stack, int64_t num); + + void *(*pop) (qstack_t *stack, size_t *size); + char *(*popstr) (qstack_t *stack); + int64_t (*popint) (qstack_t *stack); + void *(*popat) (qstack_t *stack, int index, size_t *size); + + void *(*get) (qstack_t *stack, size_t *size, bool newmem); + char *(*getstr) (qstack_t *stack); + int64_t (*getint) (qstack_t *stack); + void *(*getat) (qstack_t *stack, int index, size_t *size, bool newmem); + + size_t (*size) (qstack_t *stack); + void (*clear) (qstack_t *stack); + bool (*debug) (qstack_t *stack, FILE *out); + void (*free) (qstack_t *stack); + + /* private variables - do not access directly */ + qlist_t *list; /*!< data container */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QSTACK_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qtreetbl.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qtreetbl.h new file mode 100755 index 0000000000000000000000000000000000000000..95f49696828277d317ff5bc906606b8151f1a85d --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qtreetbl.h @@ -0,0 +1,182 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Tree Table container that implements "Left-Leaning Red-Black" Binary Search Tree algorithm. + * + * @file qtreetbl.h + */ + +#ifndef QTREETBL_H +#define QTREETBL_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qtreetbl_s qtreetbl_t; +typedef struct qtreetbl_obj_s qtreetbl_obj_t; + +/* public functions */ +enum { + QTREETBL_THREADSAFE = (0x01) /*!< make it thread-safe */ +}; + +extern qtreetbl_t *qtreetbl(int options); /*!< qtreetbl constructor */ + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->put(tbl, ...); // easier to switch the container type to other kinds. + * - qtreetbl_put(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern void qtreetbl_set_compare( + qtreetbl_t *tbl, + int (*cmp)(const void *name1, size_t namesize1, const void *name2, + size_t namesize2)); + +extern bool qtreetbl_put(qtreetbl_t *tbl, const char *name, const void *data, + size_t datasize); +extern bool qtreetbl_putstr(qtreetbl_t *tbl, const char *name, const char *str); +extern bool qtreetbl_putstrf(qtreetbl_t *tbl, const char *name, + const char *format, ...); +extern bool qtreetbl_put_by_obj(qtreetbl_t *tbl, const void *name, + size_t namesize, const void *data, + size_t datasize); + +extern void *qtreetbl_get(qtreetbl_t *tbl, const char *name, size_t *datasize, +bool newmem); +extern char *qtreetbl_getstr(qtreetbl_t *tbl, const char *name, + const bool newmem); +extern void *qtreetbl_get_by_obj(qtreetbl_t *tbl, const char *name, + size_t namesize, size_t *datasize, bool newmem); + +extern bool qtreetbl_remove(qtreetbl_t *tbl, const char *name); +extern bool qtreetbl_remove_by_obj(qtreetbl_t *tbl, const void *name, + size_t namesize); + +extern bool qtreetbl_getnext(qtreetbl_t *tbl, qtreetbl_obj_t *obj, + const bool newmem); + +extern void *qtreetbl_find_min(qtreetbl_t *tbl, size_t *namesize); +extern void *qtreetbl_find_max(qtreetbl_t *tbl, size_t *namesize); +extern qtreetbl_obj_t qtreetbl_find_nearest(qtreetbl_t *tbl, const void *name, + size_t namesize, bool newmem); + +extern size_t qtreetbl_size(qtreetbl_t *tbl); +extern void qtreetbl_clear(qtreetbl_t *tbl); + +extern void qtreetbl_lock(qtreetbl_t *tbl); +extern void qtreetbl_unlock(qtreetbl_t *tbl); + +extern void qtreetbl_free(qtreetbl_t *tbl); + +extern int qtreetbl_byte_cmp(const void *name1, size_t namesize1, + const void *name2, size_t namesize2); +extern bool qtreetbl_debug(qtreetbl_t *tbl, FILE *out); + +/** + * qtreetbl container object + */ +struct qtreetbl_s { + /* encapsulated member functions */ + void (*set_compare)( + qtreetbl_t *tbl, + int (*cmp)(const void *name1, size_t namesize1, const void *name2, + size_t namesize2)); + bool (*put)(qtreetbl_t *tbl, const char *name, const void *data, + size_t size); + bool (*putstr)(qtreetbl_t *tbl, const char *name, const char *str); + bool (*putstrf)(qtreetbl_t *tbl, const char *name, const char *format, ...); + bool (*put_by_obj)(qtreetbl_t *tbl, const void *name, size_t namesize, + const void *data, size_t datasize); + + void *(*get)(qtreetbl_t *tbl, const char *name, size_t *datasize, + bool newmem); + char *(*getstr)(qtreetbl_t *tbl, const char *name, bool newmem); + void *(*get_by_obj)(qtreetbl_t *tbl, const char *name, size_t namesize, + size_t *datasize, bool newmem); + + bool (*remove)(qtreetbl_t *tbl, const char *name); + bool (*remove_by_obj)(qtreetbl_t *tbl, const void *name, size_t namesize); + + bool (*getnext)(qtreetbl_t *tbl, qtreetbl_obj_t *obj, const bool newmem); + + void *(*find_min)(qtreetbl_t *tbl, size_t *namesize); + void *(*find_max)(qtreetbl_t *tbl, size_t *namesize); + qtreetbl_obj_t (*find_nearest)(qtreetbl_t *tbl, const void *name, + size_t namesize, bool newmem); + + size_t (*size)(qtreetbl_t *tbl); + void (*clear)(qtreetbl_t *tbl); + bool (*debug)(qtreetbl_t *tbl, FILE *out); + + void (*lock)(qtreetbl_t *tbl); + void (*unlock)(qtreetbl_t *tbl); + + void (*free)(qtreetbl_t *tbl); + + /* private member functions */ + int (*compare)(const void *name1, size_t namesize1, const void *name2, + size_t namesize2); + + /* private variables - do not access directly */ + void *qmutex; /*!< initialized when QTREETBL_THREADSAFE is given */ + qtreetbl_obj_t *root; /*!< root node */ + size_t num; /*!< number of objects */ + uint8_t tid; /*!< travel id sequencer */ +}; + +/** + * qtreetbl object data structure + */ +struct qtreetbl_obj_s { + void *name; /*!< name of key */ + size_t namesize; /*!< name size */ + void *data; /*!< data */ + size_t datasize; /*!< data size */ + + bool red; /*!< true if upper link is red */ + qtreetbl_obj_t *left; /*!< left node */ + qtreetbl_obj_t *right; /*!< right node */ + + qtreetbl_obj_t *next; /*!< temporary use for tree traversal */ + uint8_t tid; /*!< temporary use for tree traversal */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QTREETBL_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qvector.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qvector.h new file mode 100755 index 0000000000000000000000000000000000000000..f60e383f03b6ac08da0737c9d40f20b331da88cd --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/containers/qvector.h @@ -0,0 +1,160 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ +/* This code is written and updated by following people and released under + * the same license as above qLibc license. + * Copyright (c) 2015 Zhenjiang Xie - https://github.com/Charles0429 + *****************************************************************************/ + +/** + * Vector container. + * + * @file qvector.h + */ + +#ifndef QVECTOR_H +#define QVECTOR_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qvector_s qvector_t; +typedef struct qvector_obj_s qvector_obj_t; + +/* public functions */ +enum { + QVECTOR_THREADSAFE = (0x01), /*!< make it thread-safe */ + QVECTOR_RESIZE_DOUBLE = (0x02), /*!< double the size when vector is full*/ + QVECTOR_RESIZE_LINEAR = (0x04), /*!< add the size with initial num when vector is full*/ + QVECTOR_RESIZE_EXACT = (0x08) /*!< add up as much as needed*/ +}; + +extern qvector_t *qvector(size_t max, size_t objsize, int options); + +extern bool qvector_addfirst(qvector_t *vector, const void *data); +extern bool qvector_addlast(qvector_t *vector, const void *data); +extern bool qvector_addat(qvector_t *vector, int index, const void *data); + +extern void *qvector_getfirst(qvector_t *vector, bool newmem); +extern void *qvector_getlast(qvector_t *vector, bool newmem); +extern void *qvector_getat(qvector_t *vector, int index, bool newmem); + +extern bool qvector_setfirst(qvector_t *vector, const void *data); +extern bool qvector_setlast(qvector_t *vector, const void *data); +extern bool qvector_setat(qvector_t *vector, int index, const void *data); + +extern void *qvector_popfirst(qvector_t *vector); +extern void *qvector_poplast(qvector_t *vector); +extern void *qvector_popat(qvector_t *vector, int index); + +extern bool qvector_removefirst(qvector_t *vector); +extern bool qvector_removelast(qvector_t *vector); +extern bool qvector_removeat(qvector_t *vector, int index); + +extern size_t qvector_size(qvector_t *vector); +extern bool qvector_resize(qvector_t *vector, size_t newmax); + +extern void *qvector_toarray(qvector_t *vector, size_t *size); + +extern void qvector_lock(qvector_t *vector); +extern void qvector_unlock(qvector_t *vector); + +extern void qvector_clear(qvector_t *vector); +extern bool qvector_debug(qvector_t *vector, FILE *out); +extern void qvector_free(qvector_t *vector); + +extern void qvector_reverse(qvector_t *vector); +extern bool qvector_getnext(qvector_t *vector, qvector_obj_t *obj, bool newmem); + +/** + * qvector container object + */ +struct qvector_s { + /* capsulated member functions */ + + bool (*addfirst)(qvector_t *vector, const void *object); + bool (*addlast)(qvector_t *vector, const void *data); + bool (*addat)(qvector_t *vector, int index, const void *data); + + void *(*getfirst)(qvector_t *vector, bool newmem); + void *(*getlast)(qvector_t *vector, bool newmem); + void *(*getat)(qvector_t *vector, int index, bool newmem); + + bool (*setfirst)(qvector_t *vector, const void *data); + bool (*setlast)(qvector_t *vector, const void *data); + bool (*setat)(qvector_t *vector, int index, const void *data); + + void *(*popfirst)(qvector_t *vector); + void *(*poplast)(qvector_t *vector); + void *(*popat)(qvector_t *vector, int index); + + bool (*removefirst)(qvector_t *vector); + bool (*removelast)(qvector_t *vector); + bool (*removeat)(qvector_t *vector, int index); + + size_t (*size)(qvector_t *vector); + bool (*resize)(qvector_t *vector, size_t newmax); + + void *(*toarray)(qvector_t *vector, size_t *size); + + void (*lock)(qvector_t *vector); + void (*unlock)(qvector_t *vector); + + void (*clear)(qvector_t *vector); + bool (*debug)(qvector_t *vector, FILE *out); + void (*free)(qvector_t *vector); + + void (*reverse)(qvector_t *vector); + bool (*getnext)(qvector_t *vector, qvector_obj_t *obj, bool newmem); + + /* private variables - do not access directly */ + void *qmutex; + void *data; + size_t num; /*number of elements*/ + size_t objsize; /*the size of each element*/ + size_t max; /*allocated number of elements*/ + int options; + size_t initnum; +}; + +struct qvector_obj_s { + void *data; + int index; +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QVECTOR_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qaconf.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qaconf.h new file mode 100755 index 0000000000000000000000000000000000000000..e61962fe97327e9950753020b8a268c839fd4d62 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qaconf.h @@ -0,0 +1,229 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * Apache-style Configuration File Parser. + * + * This is a qLibc extension implementing Apache-style configuration file + * parser. + * + * @file qaconf.h + */ + +#ifndef QACONF_H +#define QACONF_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qaconf_s qaconf_t; +typedef struct qaconf_option_s qaconf_option_t; +typedef struct qaconf_cbdata_s qaconf_cbdata_t; +typedef char *(qaconf_cb_t) (qaconf_cbdata_t *data, void *userdata); + +/* public functions */ +extern qaconf_t *qaconf(void); + +/* user's callback function prototype */ +#define QAC_CB(func) char *func(qaconf_cbdata_t *data, void *userdata) +#define QAC_TAKEn(n) (n) + +/* parser option flags */ +enum { + QAC_CASEINSENSITIVE = (1), + QAC_IGNOREUNKNOWN = (2), // Ignore unknown option directives. +}; + +/** + * Argument type check + * + * uint32_t type 32bit variable is used for passing argument types. + * notused bool float int #arg + * ---- ---====== ---- --== ==== ---- ---- + * rrrr rrBb bbbb Ffff ffIi iiii aaaa aaaa (32bit mask) + * (6bit) (6bit) (6bit) (6bit) (8bit) + * + * r : Not Used + * B : Consider all arguments as BOOL type unless individually specified. + * b : Flaged argument(1~5) must be bool type. + * F : Consider all arguments as FLOAT type unless individually specified. + * f : Flaged argument(1~5) must be float type. + * I : Consider all arguments as INTEGER type unless individually specified. + * i : Flaged argument(1~5) must be integer type. + * a : Number of arguments (0~254). + * Value 255 means take any number of arguments. + * + * An option takes 1 argument. + * QAC_TAKE_STR <= String(any) type + * QAC_TAKE_INT <= Integer type + * QAC_TAKE_FLOAT <= Float type + * QAC_TAKE_BOOL <= Bool type + * + * QAC_TAKE1 <= equivalent to QAC_TAKE_STR + * QAC_TAKE1 | QAC_A1_BOOL <= equivalent to QAC_TAKE_BOOL + * + * An option takes 2 arguments, bool and float. + * QAC_TAKE2 | QAC_A1_BOOL | QAC_A2_FLOAT + * + * An option takes any number of arguments in any type. + * QAC_TAKEALL + * + * An option takes any number of arguments but 1st one must be bool and + * 2nd one must be integer and rest of them must be float. + * QAC_TAKEALL | QAC_A1_BOOL | QAC_A2_INT | QAC_AA_FLOAT + */ +enum qaconf_take { + // Define string(any) type argument. + QAC_A1_STR = 0, + QAC_A2_STR = 0, + QAC_A3_STR = 0, + QAC_A4_STR = 0, + QAC_A5_STR = 0, + QAC_AA_STR = 0, // All string unless individually specified. + + // Define integer type argument. + QAC_A1_INT = (1 << 8), + QAC_A2_INT = (QAC_A1_INT << 1), + QAC_A3_INT = (QAC_A1_INT << 2), + QAC_A4_INT = (QAC_A1_INT << 3), + QAC_A5_INT = (QAC_A1_INT << 4), + QAC_AA_INT = (QAC_A1_INT << 5), // All integer unless specified. + + // Define floating point type argument. + QAC_A1_FLOAT = (1 << 16), + QAC_A2_FLOAT = (QAC_A1_FLOAT << 1), + QAC_A3_FLOAT = (QAC_A1_FLOAT << 2), + QAC_A4_FLOAT = (QAC_A1_FLOAT << 3), + QAC_A5_FLOAT = (QAC_A1_FLOAT << 4), + QAC_AA_FLOAT = (QAC_A1_FLOAT << 5), // All float unless specified. + + // Define bool(true/false, yes/no, on/off, 1/0) type argument. + QAC_A1_BOOL = (1 << 24), + QAC_A2_BOOL = (QAC_A1_BOOL << 1), + QAC_A3_BOOL = (QAC_A1_BOOL << 2), + QAC_A4_BOOL = (QAC_A1_BOOL << 3), + QAC_A5_BOOL = (QAC_A1_BOOL << 4), + QAC_AA_BOOL = (QAC_A1_BOOL << 5), // All bool unless specified. + + // Number of arguments to take + QAC_TAKENONE = QAC_TAKEn(0), + QAC_TAKE0 = QAC_TAKENONE, + QAC_TAKE1 = QAC_TAKEn(1), + QAC_TAKE2 = QAC_TAKEn(2), + QAC_TAKE3 = QAC_TAKEn(3), + QAC_TAKE4 = QAC_TAKEn(4), + QAC_TAKE5 = QAC_TAKEn(5), + // use QAC_TAKEn(N) macro for 6~254 arguments. + QAC_TAKEALL = 0xFF, // Take any number of elements. (0 ~ INT_MAX) + + // Convenient synonyms + QAC_TAKE_STR = (QAC_TAKE1 | QAC_A1_STR), + QAC_TAKE_INT = (QAC_TAKE1 | QAC_A1_INT), + QAC_TAKE_FLOAT = (QAC_TAKE1 | QAC_A1_FLOAT), + QAC_TAKE_BOOL = (QAC_TAKE1 | QAC_A1_BOOL), +}; +#define QAC_TAKEn(n) (n) + +/* pre-defined sections */ +enum qaconf_section { + QAC_SECTION_ALL = (0), /* pre-defined */ + QAC_SECTION_ROOT = (1) /* pre-defined */ +}; + +/* option type */ +enum qaconf_otype { + QAC_OTYPE_OPTION = 0, /* general option */ + QAC_OTYPE_SECTIONOPEN = 1, /* section open */ + QAC_OTYPE_SECTIONCLOSE = 2 /* section close */ +}; + +/** + * qaconf_t object. + */ +struct qaconf_s { + /* capsulated member functions */ + int (*addoptions) (qaconf_t *qaconf, const qaconf_option_t *options); + void (*setdefhandler) (qaconf_t *qaconf, qaconf_cb_t *callback); + void (*setuserdata) (qaconf_t *qaconf, const void *userdata); + int (*parse) (qaconf_t *qaconf, const char *filepath, uint8_t flags); + const char *(*errmsg) (qaconf_t *qaconf); + void (*reseterror) (qaconf_t *qaconf); + void (*free) (qaconf_t *qaconf); + + /* private variables - do not access directly */ + int numoptions; /*!< a number of user defined options */ + qaconf_option_t *options; /*!< option data */ + + qaconf_cb_t *defcb; /*!< default callback for unregistered option */ + void *userdata; /*!< userdata */ + + char *filepath; /*!< current processing file's path */ + int lineno; /*!< current processing line number */ + + char *errstr; /*!< last error string */ +}; + +/** + * structure for user option definition. + */ +struct qaconf_option_s { + char *name; /*!< name of option. */ + uint32_t take; /*!< number of arguments and type checking */ + qaconf_cb_t *cb; /*!< callback function */ + uint64_t sectionid; /*!< sectionid if this is a section */ + uint64_t sections; /*!< ORed sectionid(s) where this option is allowed */ +}; +#define QAC_OPTION_END {NULL, 0, NULL, 0, 0} + +/** + * callback data structure. + */ +struct qaconf_cbdata_s { + enum qaconf_otype otype; /*!< option type */ + uint64_t section; /*!< current section where this option is located */ + uint64_t sections; /*!< ORed all parent's sectionid(s) including current sections */ + uint8_t level; /*!< number of parents(level), root level is 0 */ + qaconf_cbdata_t *parent; /*!< upper parent link */ + + int argc; /*!< number arguments. always equal or greater than 1. */ + char **argv; /*!< argument pointers. argv[0] is option name. */ + + void *data; /*!< where actual data is stored */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QACONF_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qconfig.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qconfig.h new file mode 100755 index 0000000000000000000000000000000000000000..233571f35c165213e795676264b6d231c3b46bb0 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qconfig.h @@ -0,0 +1,57 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * INI-style Configuration File Parser. + * + * This is a qLibc extension implementing INI-style configuration file parser. + * + * @file qconfig.h + */ + +#ifndef QCONFIG_H +#define QCONFIG_H + +#include +#include +#include +#include "../containers/qlisttbl.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* public functions */ +extern qlisttbl_t *qconfig_parse_file(qlisttbl_t *tbl, const char *filepath, char sepchar); +extern qlisttbl_t *qconfig_parse_str(qlisttbl_t *tbl, const char *str, char sepchar); + +#ifdef __cplusplus +} +#endif + +#endif /* QCONFIG_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qdatabase.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qdatabase.h new file mode 100755 index 0000000000000000000000000000000000000000..c3db52dafbbb84498b5cbb3ab51da723ed2e49c7 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qdatabase.h @@ -0,0 +1,140 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * Generic database interface. + * + * This is a qLibc extension implementing generic database interface. + * For now, it supports only MySQL database. + * + * @file qdatabase.h + */ + +#ifndef QDATABASE_H +#define QDATABASE_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* database header files should be included before this header file. */ +#ifdef _mysql_h +#define Q_ENABLE_MYSQL (1) +#endif /* _mysql_h */ + +/* types */ +typedef struct qdbresult_s qdbresult_t; +typedef struct qdb_s qdb_t; + +/* public functions */ +extern qdb_t *qdb(const char *dbtype, + const char *addr, int port, const char *database, + const char *username, const char *password, bool autocommit); + +/** + * qdbresult object structure + */ +struct qdbresult_s { + /* encapsulated member functions */ + const char *(*getstr) (qdbresult_t *result, const char *field); + const char *(*get_str_at) (qdbresult_t *result, int idx); + int (*getint) (qdbresult_t *result, const char *field); + int (*get_int_at) (qdbresult_t *result, int idx); + bool (*getnext) (qdbresult_t *result); + + int (*get_cols) (qdbresult_t *result); + int (*get_rows) (qdbresult_t *result); + int (*get_row) (qdbresult_t *result); + + void (*free) (qdbresult_t *result); + +#ifdef Q_ENABLE_MYSQL + /* private variables for mysql database - do not access directly */ + bool fetchtype; + MYSQL_RES *rs; + MYSQL_FIELD *fields; + MYSQL_ROW row; + int cols; + int cursor; +#endif +}; + +/* qdb object structure */ +struct qdb_s { + /* encapsulated member functions */ + bool (*open) (qdb_t *db); + bool (*close) (qdb_t *db); + + int (*execute_update) (qdb_t *db, const char *query); + int (*execute_updatef) (qdb_t *db, const char *format, ...); + + qdbresult_t *(*execute_query) (qdb_t *db, const char *query); + qdbresult_t *(*execute_queryf) (qdb_t *db, const char *format, ...); + + bool (*begin_tran) (qdb_t *db); + bool (*end_tran) (qdb_t *db, bool commit); + bool (*commit) (qdb_t *db); + bool (*rollback) (qdb_t *db); + + bool (*set_fetchtype) (qdb_t *db, bool fromdb); + bool (*get_conn_status) (qdb_t *db); + bool (*ping) (qdb_t *db); + const char *(*get_error) (qdb_t *db, unsigned int *errorno); + void (*free) (qdb_t *db); + + /* private variables - do not access directly */ + void *qmutex; + + bool connected; /*!< if opened true, if closed false */ + + struct { + char *dbtype; + char *addr; + int port; + char *username; + char *password; + char *database; + bool autocommit; + bool fetchtype; + } info; /*!< database connection information */ + +#ifdef Q_ENABLE_MYSQL + /* private variables for mysql database - do not access directly */ + MYSQL *mysql; +#endif +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QDATABASE_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qhttpclient.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qhttpclient.h new file mode 100755 index 0000000000000000000000000000000000000000..1f7869c0cebf24650d2713a8dd2e49a6a8346c0a --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qhttpclient.h @@ -0,0 +1,127 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * HTTP client. + * + * This is a qLibc extension implementing HTTP client. + * + * @file qhttpclient.h + */ + +#ifndef QHTTPCLIENT_H +#define QHTTPCLIENT_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qhttpclient_s qhttpclient_t; + +/* constants */ +#define QHTTPCLIENT_NAME "qLibc" + +/* public functions */ +extern qhttpclient_t *qhttpclient(const char *hostname, int port); + +/** + * qhttpclient object structure + */ +struct qhttpclient_s { + /* encapsulated member functions */ + bool (*setssl) (qhttpclient_t *client); + void (*settimeout) (qhttpclient_t *client, int timeoutms); + void (*setkeepalive) (qhttpclient_t *client, bool keepalive); + void (*setuseragent) (qhttpclient_t *client, const char *useragent); + + bool (*open) (qhttpclient_t *client); + + bool (*head) (qhttpclient_t *client, const char *uri, int *rescode, + qlisttbl_t *reqheaders, qlisttbl_t *resheaders); + bool (*get) (qhttpclient_t *client, const char *uri, int fd, + off_t *savesize, int *rescode, + qlisttbl_t *reqheaders, qlisttbl_t *resheaders, + bool (*callback) (void *userdata, off_t recvbytes), + void *userdata); + bool (*put) (qhttpclient_t *client, const char *uri, int fd, + off_t length, int *retcode, qlisttbl_t *userheaders, + qlisttbl_t *resheaders, + bool (*callback) (void *userdata, off_t sentbytes), + void *userdata); + void *(*cmd) (qhttpclient_t *client, + const char *method, const char *uri, + void *data, size_t size, int *rescode, + size_t *contentslength, + qlisttbl_t *reqheaders, qlisttbl_t *resheaders); + + char *(*json) (qhttpclient_t *client, + const char *method, const char *uri, + char *data, size_t size, int *rescode, + size_t *contentslength, + qlisttbl_t *reqheaders, qlisttbl_t *resheaders); + + bool (*sendrequest) (qhttpclient_t *client, const char *method, + const char *uri, qlisttbl_t *reqheaders); + int (*readresponse) (qhttpclient_t *client, qlisttbl_t *resheaders, + off_t *contentlength); + + ssize_t (*gets) (qhttpclient_t *client, char *buf, size_t bufsize); + ssize_t (*read) (qhttpclient_t *client, void *buf, size_t nbytes); + ssize_t (*write) (qhttpclient_t *client, const void *buf, + size_t nbytes); + off_t (*recvfile) (qhttpclient_t *client, int fd, off_t nbytes); + off_t (*sendfile) (qhttpclient_t *client, int fd, off_t nbytes); + + bool (*close) (qhttpclient_t *client); + void (*free) (qhttpclient_t *client); + + /* private variables - do not access directly */ + int socket; /*!< socket descriptor */ + void *ssl; /*!< will be used if SSL has been enabled at compile time */ + + struct sockaddr_in addr; + char *hostname; + int port; + + int timeoutms; /*< wait timeout milliseconds*/ + bool keepalive; /*< keep-alive flag */ + char *useragent; /*< user-agent name */ + + bool connclose; /*< response keep-alive flag for a last request */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QHTTPCLIENT_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qlog.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qlog.h new file mode 100755 index 0000000000000000000000000000000000000000..5cc0e9fcedc45d475f9786f8c96bd860d68b01b4 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qlog.h @@ -0,0 +1,91 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * Rotating file logger. + * + * This is a qLibc extension implementing application level auto-rotating file + * logger. + * + * @file qlog.h + */ + +#ifndef QLOG_H +#define QLOG_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qlog_s qlog_t; + +/* constants */ +#define QLOG_OPT_THREADSAFE (0x01) +#define QLOG_OPT_FLUSH (0x01 << 1) + +/* public functions */ +extern qlog_t *qlog(const char *filepathfmt, mode_t mode, int rotateinterval, int options); + +/** + * qlog structure object structure + */ +struct qlog_s { + /* encapsulated member functions */ + bool (*write) (qlog_t *log, const char *str); + bool (*writef) (qlog_t *log, const char *format, ...); + bool (*duplicate) (qlog_t *log, FILE *outfp, bool flush); + bool (*flush) (qlog_t *log); + void (*free) (qlog_t *log); + + /* private variables - do not access directly */ + void *qmutex; /*!< activated if compiled with --enable-threadsafe */ + + char filepathfmt[PATH_MAX]; /*!< file file naming format like + /somepath/daily-%Y%m%d.log */ + char filepath[PATH_MAX]; /*!< generated system path of log file */ + FILE *fp; /*!< file pointer of logpath */ + mode_t mode; /*!< file mode */ + int rotateinterval; /*!< log file will be rotate in this interval seconds */ + int nextrotate; /*!< next rotate universal time, seconds */ + bool logflush; /*!< flag for immediate flushing */ + + FILE *outfp; /*!< stream pointer for duplication */ + bool outflush; /*!< flag for immediate flushing for duplicated stream */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QLOG_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qtokenbucket.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qtokenbucket.h new file mode 100755 index 0000000000000000000000000000000000000000..c3db52dafbbb84498b5cbb3ab51da723ed2e49c7 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/extensions/qtokenbucket.h @@ -0,0 +1,140 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * Generic database interface. + * + * This is a qLibc extension implementing generic database interface. + * For now, it supports only MySQL database. + * + * @file qdatabase.h + */ + +#ifndef QDATABASE_H +#define QDATABASE_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* database header files should be included before this header file. */ +#ifdef _mysql_h +#define Q_ENABLE_MYSQL (1) +#endif /* _mysql_h */ + +/* types */ +typedef struct qdbresult_s qdbresult_t; +typedef struct qdb_s qdb_t; + +/* public functions */ +extern qdb_t *qdb(const char *dbtype, + const char *addr, int port, const char *database, + const char *username, const char *password, bool autocommit); + +/** + * qdbresult object structure + */ +struct qdbresult_s { + /* encapsulated member functions */ + const char *(*getstr) (qdbresult_t *result, const char *field); + const char *(*get_str_at) (qdbresult_t *result, int idx); + int (*getint) (qdbresult_t *result, const char *field); + int (*get_int_at) (qdbresult_t *result, int idx); + bool (*getnext) (qdbresult_t *result); + + int (*get_cols) (qdbresult_t *result); + int (*get_rows) (qdbresult_t *result); + int (*get_row) (qdbresult_t *result); + + void (*free) (qdbresult_t *result); + +#ifdef Q_ENABLE_MYSQL + /* private variables for mysql database - do not access directly */ + bool fetchtype; + MYSQL_RES *rs; + MYSQL_FIELD *fields; + MYSQL_ROW row; + int cols; + int cursor; +#endif +}; + +/* qdb object structure */ +struct qdb_s { + /* encapsulated member functions */ + bool (*open) (qdb_t *db); + bool (*close) (qdb_t *db); + + int (*execute_update) (qdb_t *db, const char *query); + int (*execute_updatef) (qdb_t *db, const char *format, ...); + + qdbresult_t *(*execute_query) (qdb_t *db, const char *query); + qdbresult_t *(*execute_queryf) (qdb_t *db, const char *format, ...); + + bool (*begin_tran) (qdb_t *db); + bool (*end_tran) (qdb_t *db, bool commit); + bool (*commit) (qdb_t *db); + bool (*rollback) (qdb_t *db); + + bool (*set_fetchtype) (qdb_t *db, bool fromdb); + bool (*get_conn_status) (qdb_t *db); + bool (*ping) (qdb_t *db); + const char *(*get_error) (qdb_t *db, unsigned int *errorno); + void (*free) (qdb_t *db); + + /* private variables - do not access directly */ + void *qmutex; + + bool connected; /*!< if opened true, if closed false */ + + struct { + char *dbtype; + char *addr; + int port; + char *username; + char *password; + char *database; + bool autocommit; + bool fetchtype; + } info; /*!< database connection information */ + +#ifdef Q_ENABLE_MYSQL + /* private variables for mysql database - do not access directly */ + MYSQL *mysql; +#endif +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QDATABASE_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/ipc/qsem.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/ipc/qsem.h new file mode 100755 index 0000000000000000000000000000000000000000..400973d775e00eabc87ee5708c8757cc2f1146f1 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/ipc/qsem.h @@ -0,0 +1,56 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qsem header file. + * + * @file qsem.h + */ + +#ifndef QSEM_H +#define QSEM_H + +#ifdef __cplusplus +extern "C" { +#endif + +extern int qsem_init(const char *keyfile, int keyid, int nsems, bool recreate); +extern int qsem_getid(const char *keyfile, int keyid); +extern bool qsem_enter(int semid, int semno); +extern bool qsem_enter_nowait(int semid, int semno); +extern bool qsem_enter_force(int semid, int semno, int maxwaitms, + bool *forceflag); +extern bool qsem_leave(int semid, int semno); +extern bool qsem_check(int semid, int semno); +extern bool qsem_free(int semid); + +#ifdef __cplusplus +} +#endif + +#endif /* QSEM_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/ipc/qshm.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/ipc/qshm.h new file mode 100755 index 0000000000000000000000000000000000000000..269777948e8dde6b533575470a80f84ff059f92f --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/ipc/qshm.h @@ -0,0 +1,52 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qshm header file. + * + * @file qshm.h + */ + +#ifndef QSHM_H +#define QSHM_H + +#ifdef __cplusplus +extern "C" { +#endif + +extern int qshm_init(const char *keyfile, int keyid, size_t size, + bool recreate); +extern int qshm_getid(const char *keyfile, int keyid); +extern void *qshm_get(int shmid); +extern bool qshm_free(int shmid); + +#ifdef __cplusplus +} +#endif + +#endif /* QSHM_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/qlibc.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/qlibc.h new file mode 100755 index 0000000000000000000000000000000000000000..3a82875db902fc9e0853c0830d3eb20ff509a1f5 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/qlibc.h @@ -0,0 +1,65 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qlibc header file. + * + * @file qlibc.h + */ + +#ifndef QLIBC_H +#define QLIBC_H + +/* containers */ +#include "containers/qtreetbl.h" +#include "containers/qhashtbl.h" +#include "containers/qhasharr.h" +#include "containers/qlisttbl.h" +#include "containers/qlist.h" +#include "containers/qvector.h" +#include "containers/qqueue.h" +#include "containers/qstack.h" +#include "containers/qgrow.h" + +/* utilities */ +#include "utilities/qcount.h" +#include "utilities/qencode.h" +#include "utilities/qfile.h" +#include "utilities/qhash.h" +#include "utilities/qio.h" +#include "utilities/qsocket.h" +#include "utilities/qstring.h" +#include "utilities/qsystem.h" +#include "utilities/qtime.h" + +/* ipc */ +#include "ipc/qsem.h" +#include "ipc/qshm.h" + +#endif /* QLIBC_H */ + diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/qlibcext.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/qlibcext.h new file mode 100755 index 0000000000000000000000000000000000000000..a6dd0917c357e50bba4c42c5daaaebdbef35f4f5 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/qlibcext.h @@ -0,0 +1,45 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qlibc extension header file. + * + * @file qlibcext.h + */ + +#ifndef QLIBCEXT_H +#define QLIBCEXT_H + +#include "extensions/qconfig.h" +#include "extensions/qaconf.h" +#include "extensions/qlog.h" +#include "extensions/qhttpclient.h" +#include "extensions/qdatabase.h" +#include "extensions/qtokenbucket.h" + +#endif /* QLIBCEXT_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qcount.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qcount.h new file mode 100755 index 0000000000000000000000000000000000000000..ce634f7a6c1c0fd215c92924a96125fd8fc731b5 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qcount.h @@ -0,0 +1,54 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qcount header file. + * + * @file qcount.h + */ + +#ifndef QCOUNT_H +#define QCOUNT_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern int64_t qcount_read(const char *filepath); +extern bool qcount_save(const char *filepath, int64_t number); +extern int64_t qcount_update(const char *filepath, int64_t number); + +#ifdef __cplusplus +} +#endif + +#endif /* QCOUNT_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qencode.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qencode.h new file mode 100755 index 0000000000000000000000000000000000000000..93c5351c9c4928468470f8ab7b4371ba6085a6e7 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qencode.h @@ -0,0 +1,59 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qencode header file. + * + * @file qencode.h + */ + +#ifndef QENCODE_H +#define QENCODE_H + +#include +#include +#include "../containers/qlisttbl.h" + +#ifdef __cplusplus +extern "C" { +#endif + +extern qlisttbl_t *qparse_queries(qlisttbl_t *tbl, const char *query, + char equalchar, char sepchar, int *count); +extern char *qurl_encode(const void *bin, size_t size); +extern size_t qurl_decode(char *str); +extern char *qbase64_encode(const void *bin, size_t size); +extern size_t qbase64_decode(char *str); +extern char *qhex_encode(const void *bin, size_t size); +extern size_t qhex_decode(char *str); + +#ifdef __cplusplus +} +#endif + +#endif /* QENCODE_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qfile.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qfile.h new file mode 100755 index 0000000000000000000000000000000000000000..76b42614576e3a0ae256fa8d260545c12f643a75 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qfile.h @@ -0,0 +1,69 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qfile header file. + * + * @file qfile.h + */ + +#ifndef QFILE_H +#define QFILE_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern bool qfile_lock(int fd); +extern bool qfile_unlock(int fd); +extern bool qfile_exist(const char *filepath); +extern void *qfile_load(const char *filepath, size_t *nbytes); +extern void *qfile_read(FILE *fp, size_t *nbytes); +extern ssize_t qfile_save(const char *filepath, const void *buf, size_t size, + bool append); +extern bool qfile_mkdir(const char *dirpath, mode_t mode, bool recursive); + +extern char *qfile_get_name(const char *filepath); +extern char *qfile_get_dir(const char *filepath); +extern char *qfile_get_ext(const char *filepath); +extern off_t qfile_get_size(const char *filepath); + +extern bool qfile_check_path(const char *path); +extern char *qfile_correct_path(char *path); +extern char *qfile_abspath(char *buf, size_t bufsize, const char *path); + +#ifdef __cplusplus +} +#endif + +#endif /* QFILE_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qhash.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qhash.h new file mode 100755 index 0000000000000000000000000000000000000000..d26a9f0b63c57f169795f657f121de7a7c6bf962 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qhash.h @@ -0,0 +1,61 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qhash header file. + * + * @file qhash.h + */ + +#ifndef QHASH_H +#define QHASH_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern bool qhashmd5(const void *data, size_t nbytes, void *retbuf); +extern bool qhashmd5_file(const char *filepath, off_t offset, ssize_t nbytes, + void *retbuf); + +extern uint32_t qhashfnv1_32(const void *data, size_t nbytes); +extern uint64_t qhashfnv1_64(const void *data, size_t nbytes); + +extern uint32_t qhashmurmur3_32(const void *data, size_t nbytes); +extern bool qhashmurmur3_128(const void *data, size_t nbytes, void *retbuf); + +#ifdef __cplusplus +} +#endif + +#endif /* QHASH_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qio.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qio.h new file mode 100755 index 0000000000000000000000000000000000000000..e8c9e6e32e09f75ea552a90c779529cd945016e9 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qio.h @@ -0,0 +1,60 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qio header file. + * + * @file qio.h + */ + +#ifndef QIO_H +#define QIO_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern int qio_wait_readable(int fd, int timeoutms); +extern int qio_wait_writable(int fd, int timeoutms); +extern ssize_t qio_read(int fd, void *buf, size_t nbytes, int timeoutms); +extern ssize_t qio_write(int fd, const void *data, size_t nbytes, + int timeoutms); +extern off_t qio_send(int outfd, int infd, off_t nbytes, int timeoutms); +extern ssize_t qio_gets(int fd, char *buf, size_t bufsize, int timeoutms); +extern ssize_t qio_puts(int fd, const char *str, int timeoutms); +extern ssize_t qio_printf(int fd, int timeoutms, const char *format, ...); + +#ifdef __cplusplus +} +#endif + +#endif /* QIO_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qsocket.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qsocket.h new file mode 100755 index 0000000000000000000000000000000000000000..1caca9fecc0e7927c360b4020d77b7a52f32d5ce --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qsocket.h @@ -0,0 +1,56 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qsocket header file. + * + * @file qsocket.h + */ + +#ifndef QSOCKET_H +#define QSOCKET_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern int qsocket_open(const char *hostname, int port, int timeoutms); +extern bool qsocket_close(int sockfd, int timeoutms); +extern bool qsocket_get_addr(struct sockaddr_in *addr, const char *hostname, + int port); +extern char *qsocket_get_localaddr(char *buf, size_t bufsize); + +#ifdef __cplusplus +} +#endif + +#endif /* QSOCKET_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qstring.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qstring.h new file mode 100755 index 0000000000000000000000000000000000000000..75c61632345173f8052b83707fc60d4113da031f --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qstring.h @@ -0,0 +1,78 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qstring header file. + * + * @file qstring.h + */ + +#ifndef QSTRING_H +#define QSTRING_H + +#include +#include +#include "../containers/qlist.h" + +#ifdef __cplusplus +extern "C" { +#endif + +extern char *qstrtrim(char *str); +extern char *qstrtrim_head(char *str); +extern char *qstrtrim_tail(char *str); +extern char *qstrunchar(char *str, char head, char tail); +extern char *qstrreplace(const char *mode, char *srcstr, const char *tokstr, + const char *word); +extern char *qstrcpy(char *dst, size_t size, const char *src); +extern char *qstrncpy(char *dst, size_t size, const char *src, size_t nbytes); +extern char *qstrdupf(const char *format, ...); +extern char *qstrdup_between(const char *str, const char *start, + const char *end); +extern void *qmemdup(const void *data, size_t size); +extern char *qstrcatf(char *str, const char *format, ...); +extern char *qstrgets(char *buf, size_t size, char **offset); +extern char *qstrrev(char *str); +extern char *qstrupper(char *str); +extern char *qstrlower(char *str); +extern char *qstrtok(char *str, const char *delimiters, char *retstop, + int *offset); +extern qlist_t *qstrtokenizer(const char *str, const char *delimiters); +extern char *qstrunique(const char *seed); +extern char *qstr_comma_number(int number); +extern bool qstrtest(int (*testfunc)(int), const char *str); +extern bool qstr_is_email(const char *email); +extern bool qstr_is_ip4addr(const char *str); +extern char *qstr_conv_encoding(const char *fromstr, const char *fromcode, + const char *tocode, float mag); + +#ifdef __cplusplus +} +#endif + +#endif /* QSTRING_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qsystem.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qsystem.h new file mode 100755 index 0000000000000000000000000000000000000000..885bfb354fcc9a6c80e62f572287807b5b4b9d85 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qsystem.h @@ -0,0 +1,49 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qsystem header file. + * + * @file qsystem.h + */ + +#ifndef QSYSTEM_H +#define QSYSTEM_H + +#ifdef __cplusplus +extern "C" { +#endif + +extern const char *qgetenv(const char *envname, const char *nullstr); +extern char *qsyscmd(const char *cmd); + +#ifdef __cplusplus +} +#endif + +#endif /* QSYSTEM_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qtime.h b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qtime.h new file mode 100755 index 0000000000000000000000000000000000000000..c752f2ec83bd6ab1bc70d0c97c7beab34b877dd6 --- /dev/null +++ b/qlibc/0.0.0/AIX-00FB437F4C00/include/qlibc/utilities/qtime.h @@ -0,0 +1,67 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qtime header file. + * + * @file qtime.h + */ + +#ifndef QTIME_H +#define QTIME_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern void qtime_timespec_diff(struct timespec t1, struct timespec t2, + struct timespec *diff); +extern void qtime_timeval_diff(struct timeval t1, struct timeval t2, + struct timeval *diff); + +extern long qtime_current_milli(void); + +extern char *qtime_localtime_strf(char *buf, int size, time_t utctime, + const char *format); +extern char *qtime_localtime_str(time_t utctime); +extern const char *qtime_localtime_staticstr(time_t utctime); +extern char *qtime_gmt_strf(char *buf, int size, time_t utctime, + const char *format); +extern char *qtime_gmt_str(time_t utctime); +extern const char *qtime_gmt_staticstr(time_t utctime); +extern time_t qtime_parse_gmtstr(const char *gmtstr); + +#ifdef __cplusplus +} +#endif + +#endif /* QTIME_H */ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/libqlibc.a.1 b/qlibc/0.0.0/AIX-00FB437F4C00/libqlibc.a.1 new file mode 100755 index 0000000000000000000000000000000000000000..ee29d08ad05d17b6f8fb5de248e36b0d8682d08d Binary files /dev/null and b/qlibc/0.0.0/AIX-00FB437F4C00/libqlibc.a.1 differ diff --git a/qlibc/0.0.0/AIX-00FB437F4C00/libqlibcext.a.1 b/qlibc/0.0.0/AIX-00FB437F4C00/libqlibcext.a.1 new file mode 100755 index 0000000000000000000000000000000000000000..813d0fb38b8bd5022999a0d091820d1d3e228ce9 Binary files /dev/null and b/qlibc/0.0.0/AIX-00FB437F4C00/libqlibcext.a.1 differ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qgrow.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qgrow.h new file mode 100755 index 0000000000000000000000000000000000000000..b34d9b1ae4d70666a65eb2043fa89d5fb06589cb --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qgrow.h @@ -0,0 +1,99 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Grow container that handles growable objects. + * + * @file qgrow.h + */ + +#ifndef QGROW_H +#define QGROW_H + +#include +#include +#include +#include "qlist.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qgrow_s qgrow_t; + +/* public functions */ +enum { + QGROW_THREADSAFE = (QLIST_THREADSAFE) /*!< make it thread-safe */ +}; + +extern qgrow_t *qgrow(int options); + +extern bool qgrow_add(qgrow_t *grow, const void *object, size_t size); +extern bool qgrow_addstr(qgrow_t *grow, const char *str); +extern bool qgrow_addstrf(qgrow_t *grow, const char *format, ...); + +extern size_t qgrow_size(qgrow_t *grow); +extern size_t qgrow_datasize(qgrow_t *grow); + +extern void *qgrow_toarray(qgrow_t *grow, size_t *size); +extern char *qgrow_tostring(qgrow_t *grow); + +extern void qgrow_clear(qgrow_t *grow); +extern bool qgrow_debug(qgrow_t *grow, FILE *out); +extern void qgrow_free(qgrow_t *grow); + +/** + * qgrow container object + */ +struct qgrow_s { + /* capsulated member functions */ + bool (*add) (qgrow_t *grow, const void *data, size_t size); + bool (*addstr) (qgrow_t *grow, const char *str); + bool (*addstrf) (qgrow_t *grow, const char *format, ...); + + size_t (*size) (qgrow_t *grow); + size_t (*datasize) (qgrow_t *grow); + + void *(*toarray) (qgrow_t *grow, size_t *size); + char *(*tostring) (qgrow_t *grow); + + void (*clear) (qgrow_t *grow); + bool (*debug) (qgrow_t *grow, FILE *out); + + void (*free) (qgrow_t *grow); + + /* private variables - do not access directly */ + qlist_t *list; /*!< data container */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QGROW_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qhasharr.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qhasharr.h new file mode 100755 index 0000000000000000000000000000000000000000..23f2e089386d5cc6557154de9e5a932e0c54a7e1 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qhasharr.h @@ -0,0 +1,174 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Static Hash Table container that works in preallocated fixed size memory. + * + * @file qhasharr.h + */ + +#ifndef QHASHARR_H +#define QHASHARR_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* tunable knobs */ +#define Q_HASHARR_NAMESIZE (16) /*!< knob for maximum key size. */ +#define Q_HASHARR_DATASIZE (32) /*!< knob for maximum data size in a slot. */ + +/* types */ +typedef struct qhasharr_s qhasharr_t; +typedef struct qhasharr_slot_s qhasharr_slot_t; +typedef struct qhasharr_data_s qhasharr_data_t; +typedef struct qhasharr_obj_s qhasharr_obj_t; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->put(tbl, ...); // easier to switch the container type to other kinds. + * - qhasharr_put(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qhasharr_t *qhasharr(void *memory, size_t memsize); +extern size_t qhasharr_calculate_memsize(int max); + +extern bool qhasharr_put(qhasharr_t *tbl, const char *key, const void *value, + size_t size); +extern bool qhasharr_putstr(qhasharr_t *tbl, const char *key, const char *str); +extern bool qhasharr_putstrf(qhasharr_t *tbl, const char *key, const char *format, ...); +extern bool qhasharr_put_by_obj(qhasharr_t *tbl, const void *name, size_t namesize, + const void *data, size_t datasize); + +extern void *qhasharr_get(qhasharr_t *tbl, const char *key, size_t *size); +extern char *qhasharr_getstr(qhasharr_t *tbl, const char *key); +extern void *qhasharr_get_by_obj(qhasharr_t *tbl, const void *name, size_t namesize, + size_t *datasize); + +extern bool qhasharr_remove(qhasharr_t *tbl, const char *key); +extern bool qhasharr_remove_by_obj(qhasharr_t *tbl, const char *name, size_t namesize); +extern bool qhasharr_remove_by_idx(qhasharr_t *tbl, int idx); + +extern bool qhasharr_getnext(qhasharr_t *tbl, qhasharr_obj_t *obj, int *idx); + +extern int qhasharr_size(qhasharr_t *tbl, int *maxslots, int *usedslots); +extern void qhasharr_clear(qhasharr_t *tbl); +extern bool qhasharr_debug(qhasharr_t *tbl, FILE *out); + +extern void qhasharr_free(qhasharr_t *tbl); + + +/** + * qhasharr container object + */ +struct qhasharr_s { + /* encapsulated member functions */ + bool (*put) (qhasharr_t *tbl, const char *key, const void *value, + size_t size); + bool (*putstr) (qhasharr_t *tbl, const char *key, const char *str); + bool (*putstrf) (qhasharr_t *tbl, const char *key, const char *format, ...); + bool (*put_by_obj) (qhasharr_t *tbl, const void *name, size_t namesize, + const void *data, size_t datasize); + + void *(*get) (qhasharr_t *tbl, const char *key, size_t *size); + char *(*getstr) (qhasharr_t *tbl, const char *key); + void *(*get_by_obj) (qhasharr_t *tbl, const void *name, size_t namesize, + size_t *datasize); + + bool (*remove) (qhasharr_t *tbl, const char *key); + bool (*remove_by_obj) (qhasharr_t *tbl, const char *name, size_t namesize); + bool (*remove_by_idx) (qhasharr_t *tbl, int idx); + + bool (*getnext) (qhasharr_t *tbl, qhasharr_obj_t *obj, int *idx); + + int (*size) (qhasharr_t *tbl, int *maxslots, int *usedslots); + void (*clear) (qhasharr_t *tbl); + bool (*debug) (qhasharr_t *tbl, FILE *out); + + void (*free) (qhasharr_t *tbl); + + /* private variables */ + qhasharr_data_t *data; +}; + +/** + * qhasharr internal data slot structure + */ +struct qhasharr_slot_s { + short count; /*!< hash collision counter. 0 indicates empty slot, + -1 is used for collision resolution, -2 is used for + indicating linked block */ + uint32_t hash; /*!< key hash */ + uint8_t datasize; /*!< value size in this slot*/ + int link; /*!< next link */ + + union { + /*!< key/value data */ + struct Q_HASHARR_SLOT_KEYVAL { + uint8_t data[Q_HASHARR_DATASIZE]; /*!< value */ + uint8_t name[Q_HASHARR_NAMESIZE]; /*!< key string, can be cut */ + uint16_t namesize; /*!< original key length */ + uint8_t namemd5[16]; /*!< md5 hash of the key */ + } pair; + + /*!< extended data block, used only when the count value is -2 */ + struct Q_HASHARR_SLOT_EXT { + uint8_t data[sizeof(struct Q_HASHARR_SLOT_KEYVAL)]; + } ext; + } data; +}; + +/** + * qhasharr memory structure + */ +struct qhasharr_data_s { + int maxslots; /*!< number of maximum slots */ + int usedslots; /*!< number of used slots */ + int num; /*!< number of stored keys */ +}; + +/** + * qhasharr named-object data structure for user return + */ +struct qhasharr_obj_s { + void *name; /*!< name */ + size_t namesize; /*!< name size */ + void *data; /*!< data */ + size_t datasize; /*!< data size */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QHASHARR_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qhashtbl.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qhashtbl.h new file mode 100755 index 0000000000000000000000000000000000000000..1e16f977c0507cb465e37063467207884d7957cc --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qhashtbl.h @@ -0,0 +1,135 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Hash Table container. + * + * @file qhashtbl.h + */ + +#ifndef QHASHTBL_H +#define QHASHTBL_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qhashtbl_s qhashtbl_t; +typedef struct qhashtbl_obj_s qhashtbl_obj_t; + +enum { + QHASHTBL_THREADSAFE = (0x01) /*!< make it thread-safe */ +}; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->put(tbl, ...); // easier to switch the container type to other kinds. + * - qhashtbl_put(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qhashtbl_t *qhashtbl(size_t range, int options); /*!< qhashtbl constructor */ + +extern bool qhashtbl_put(qhashtbl_t *tbl, const char *name, const void *data, size_t size); +extern bool qhashtbl_putstr(qhashtbl_t *tbl, const char *name, const char *str); +extern bool qhashtbl_putstrf(qhashtbl_t *tbl, const char *name, const char *format, ...); +extern bool qhashtbl_putint(qhashtbl_t *tbl, const char *name, int64_t num); + +extern void *qhashtbl_get(qhashtbl_t *tbl, const char *name, size_t *size, bool newmem); +extern char *qhashtbl_getstr(qhashtbl_t *tbl, const char *name, bool newmem); +extern int64_t qhashtbl_getint(qhashtbl_t *tbl, const char *name); + +extern bool qhashtbl_remove(qhashtbl_t *tbl, const char *name); + +extern bool qhashtbl_getnext(qhashtbl_t *tbl, qhashtbl_obj_t *obj, bool newmem); + +extern size_t qhashtbl_size(qhashtbl_t *tbl); +extern void qhashtbl_clear(qhashtbl_t *tbl); +extern bool qhashtbl_debug(qhashtbl_t *tbl, FILE *out); + +extern void qhashtbl_lock(qhashtbl_t *tbl); +extern void qhashtbl_unlock(qhashtbl_t *tbl); + +extern void qhashtbl_free(qhashtbl_t *tbl); + +/** + * qhashtbl container object structure + */ +struct qhashtbl_s { + /* encapsulated member functions */ + bool (*put) (qhashtbl_t *tbl, const char *name, const void *data, size_t size); + bool (*putstr) (qhashtbl_t *tbl, const char *name, const char *str); + bool (*putstrf) (qhashtbl_t *tbl, const char *name, const char *format, ...); + bool (*putint) (qhashtbl_t *tbl, const char *name, const int64_t num); + + void *(*get) (qhashtbl_t *tbl, const char *name, size_t *size, bool newmem); + char *(*getstr) (qhashtbl_t *tbl, const char *name, bool newmem); + int64_t (*getint) (qhashtbl_t *tbl, const char *name); + + bool (*remove) (qhashtbl_t *tbl, const char *name); + + bool (*getnext) (qhashtbl_t *tbl, qhashtbl_obj_t *obj, bool newmem); + + size_t (*size) (qhashtbl_t *tbl); + void (*clear) (qhashtbl_t *tbl); + bool (*debug) (qhashtbl_t *tbl, FILE *out); + + void (*lock) (qhashtbl_t *tbl); + void (*unlock) (qhashtbl_t *tbl); + + void (*free) (qhashtbl_t *tbl); + + /* private variables - do not access directly */ + void *qmutex; /*!< initialized when QHASHTBL_THREADSAFE is given */ + size_t num; /*!< number of objects in this table */ + size_t range; /*!< hash range, vertical number of slots */ + qhashtbl_obj_t **slots; /*!< slot pointer container */ +}; + +/** + * qhashtbl object data structure + */ +struct qhashtbl_obj_s { + uint32_t hash; /*!< 32bit-hash value of object name */ + char *name; /*!< object name */ + void *data; /*!< data */ + size_t size; /*!< data size */ + + qhashtbl_obj_t *next; /*!< for chaining next collision object */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QHASHTBL_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qlist.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qlist.h new file mode 100755 index 0000000000000000000000000000000000000000..f96cde1b2fe619291d91e81bea7c86ea8ca7549f --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qlist.h @@ -0,0 +1,161 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Doubly Linked-list container. + * + * @file qlist.h + */ + +#ifndef QLIST_H +#define QLIST_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +enum { + QLIST_THREADSAFE = (0x01) /*!< make it thread-safe */ +}; + +/* types */ +typedef struct qlist_s qlist_t; +typedef struct qlist_obj_s qlist_obj_t; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->addlast(tbl, ...); // easier to switch the container type to other kinds. + * - qlist_addlast(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qlist_t *qlist(int options); /*!< qlist constructor */ +extern size_t qlist_setsize(qlist_t *list, size_t max); + +extern bool qlist_addfirst(qlist_t *list, const void *data, size_t size); +extern bool qlist_addlast(qlist_t *list, const void *data, size_t size); +extern bool qlist_addat(qlist_t *list, int index, const void *data, size_t size); + +extern void *qlist_getfirst(qlist_t *list, size_t *size, bool newmem); +extern void *qlist_getlast(qlist_t *list, size_t *size, bool newmem); +extern void *qlist_getat(qlist_t *list, int index, size_t *size, bool newmem); + +extern void *qlist_popfirst(qlist_t *list, size_t *size); +extern void *qlist_poplast(qlist_t *list, size_t *size); +extern void *qlist_popat(qlist_t *list, int index, size_t *size); + +extern bool qlist_removefirst(qlist_t *list); +extern bool qlist_removelast(qlist_t *list); +extern bool qlist_removeat(qlist_t *list, int index); + +extern bool qlist_getnext(qlist_t *list, qlist_obj_t *obj, bool newmem); + +extern size_t qlist_size(qlist_t *list); +extern size_t qlist_datasize(qlist_t *list); +extern void qlist_reverse(qlist_t *list); +extern void qlist_clear(qlist_t *list); + +extern void *qlist_toarray(qlist_t *list, size_t *size); +extern char *qlist_tostring(qlist_t *list); +extern bool qlist_debug(qlist_t *list, FILE *out); + +extern void qlist_lock(qlist_t *list); +extern void qlist_unlock(qlist_t *list); + +extern void qlist_free(qlist_t *list); + +/** + * qlist container object + */ +struct qlist_s { + /* encapsulated member functions */ + size_t (*setsize)(qlist_t *list, size_t max); + + bool (*addfirst)(qlist_t *list, const void *data, size_t size); + bool (*addlast)(qlist_t *list, const void *data, size_t size); + bool (*addat)(qlist_t *list, int index, const void *data, size_t size); + + void *(*getfirst)(qlist_t *list, size_t *size, bool newmem); + void *(*getlast)(qlist_t *list, size_t *size, bool newmem); + void *(*getat)(qlist_t *list, int index, size_t *size, bool newmem); + + void *(*popfirst)(qlist_t *list, size_t *size); + void *(*poplast)(qlist_t *list, size_t *size); + void *(*popat)(qlist_t *list, int index, size_t *size); + + bool (*removefirst)(qlist_t *list); + bool (*removelast)(qlist_t *list); + bool (*removeat)(qlist_t *list, int index); + + bool (*getnext)(qlist_t *list, qlist_obj_t *obj, bool newmem); + + void (*reverse)(qlist_t *list); + void (*clear)(qlist_t *list); + + size_t (*size)(qlist_t *list); + size_t (*datasize)(qlist_t *list); + + void *(*toarray)(qlist_t *list, size_t *size); + char *(*tostring)(qlist_t *list); + bool (*debug)(qlist_t *list, FILE *out); + + void (*lock)(qlist_t *list); + void (*unlock)(qlist_t *list); + + void (*free)(qlist_t *list); + + /* private variables - do not access directly */ + void *qmutex; /*!< initialized when QLIST_OPT_THREADSAFE is given */ + size_t num; /*!< number of elements */ + size_t max; /*!< maximum number of elements. 0 means no limit */ + size_t datasum; /*!< total sum of data size, does not include name size */ + + qlist_obj_t *first; /*!< first object pointer */ + qlist_obj_t *last; /*!< last object pointer */ +}; + +/** + * qlist node data structure. + */ +struct qlist_obj_s { + void *data; /*!< data */ + size_t size; /*!< data size */ + + qlist_obj_t *prev; /*!< previous link */ + qlist_obj_t *next; /*!< next link */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QLIST_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qlisttbl.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qlisttbl.h new file mode 100755 index 0000000000000000000000000000000000000000..24fa25bc59d64d806fb5c5e594a521fb2e7b7eb6 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qlisttbl.h @@ -0,0 +1,180 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * List container with key/value pair in doubly linked data structure. + * + * @file qlisttbl.h + */ + +#ifndef QLISTTBL_H +#define QLISTTBL_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qlisttbl_s qlisttbl_t; +typedef struct qlisttbl_obj_s qlisttbl_obj_t; +typedef struct qlisttbl_data_s qlisttbl_data_t; + +enum { + QLISTTBL_THREADSAFE = (0x01), /*!< make it thread-safe */ + QLISTTBL_UNIQUE = (0x01 << 1), /*!< keys are unique */ + QLISTTBL_CASEINSENSITIVE = (0x01 << 2), /*!< keys are case insensitive */ + QLISTTBL_INSERTTOP = (0x01 << 3), /*!< insert new key at the top */ + QLISTTBL_LOOKUPFORWARD = (0x01 << 4), /*!< find key from the top (default: backward) */ +}; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->put(tbl, ...); // easier to switch the container type to other kinds. + * - qlisttbl_put(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qlisttbl_t *qlisttbl(int options); /*!< qlisttbl constructor */ + +extern bool qlisttbl_put(qlisttbl_t *tbl, const char *name, const void *data, size_t size); +extern bool qlisttbl_putstr(qlisttbl_t *tbl, const char *name, const char *str); +extern bool qlisttbl_putstrf(qlisttbl_t *tbl, const char *name, const char *format, ...); +extern bool qlisttbl_putint(qlisttbl_t *tbl, const char *name, int64_t num); + +extern void *qlisttbl_get(qlisttbl_t *tbl, const char *name, size_t *size, bool newmem); +extern char *qlisttbl_getstr(qlisttbl_t *tbl, const char *name, bool newmem); +extern int64_t qlisttbl_getint(qlisttbl_t *tbl, const char *name); + +extern qlisttbl_data_t *qlisttbl_getmulti(qlisttbl_t *tbl, const char *name, bool newmem, size_t *numobjs); +extern void qlisttbl_freemulti(qlisttbl_data_t *objs); + +extern size_t qlisttbl_remove(qlisttbl_t *tbl, const char *name); +extern bool qlisttbl_removeobj(qlisttbl_t *tbl, const qlisttbl_obj_t *obj); + +extern bool qlisttbl_getnext(qlisttbl_t *tbl, qlisttbl_obj_t *obj, const char *name, bool newmem); + +extern size_t qlisttbl_size(qlisttbl_t *tbl); +extern void qlisttbl_sort(qlisttbl_t *tbl, const bool reverse); +extern void qlisttbl_clear(qlisttbl_t *tbl); +extern bool qlisttbl_save(qlisttbl_t *tbl, const char *filepath, char sepchar, bool encode); +extern ssize_t qlisttbl_load(qlisttbl_t *tbl, const char *filepath, char sepchar, bool decode); + +extern bool qlisttbl_debug(qlisttbl_t *tbl, FILE *out); + +extern void qlisttbl_lock(qlisttbl_t *tbl); +extern void qlisttbl_unlock(qlisttbl_t *tbl); + +extern void qlisttbl_free(qlisttbl_t *tbl); + + + +/** + * qlisttbl container structure + */ +struct qlisttbl_s { + /* capsulated member functions */ + bool (*put) (qlisttbl_t *tbl, const char *name, const void *data, size_t size); + bool (*putstr) (qlisttbl_t *tbl, const char *name, const char *str); + bool (*putstrf) (qlisttbl_t *tbl, const char *name, const char *format, ...); + bool (*putint) (qlisttbl_t *tbl, const char *name, int64_t num); + + void *(*get) (qlisttbl_t *tbl, const char *name, size_t *size, bool newmem); + char *(*getstr) (qlisttbl_t *tbl, const char *name, bool newmem); + int64_t (*getint) (qlisttbl_t *tbl, const char *name); + + qlisttbl_data_t *(*getmulti) (qlisttbl_t *tbl, const char *name, bool newmem, size_t *numobjs); + void (*freemulti) (qlisttbl_data_t *objs); + + size_t (*remove) (qlisttbl_t *tbl, const char *name); + bool (*removeobj) (qlisttbl_t *tbl, const qlisttbl_obj_t *obj); + + bool (*getnext) (qlisttbl_t *tbl, qlisttbl_obj_t *obj, const char *name, bool newmem); + + size_t (*size) (qlisttbl_t *tbl); + void (*sort) (qlisttbl_t *tbl, const bool reverse); + void (*clear) (qlisttbl_t *tbl); + + bool (*save) (qlisttbl_t *tbl, const char *filepath, char sepchar, + bool encode); + ssize_t (*load) (qlisttbl_t *tbl, const char *filepath, char sepchar, + bool decode); + bool (*debug) (qlisttbl_t *tbl, FILE *out); + + void (*lock) (qlisttbl_t *tbl); + void (*unlock) (qlisttbl_t *tbl); + + void (*free) (qlisttbl_t *tbl); + + /* private methods */ + bool (*namematch) (qlisttbl_obj_t *obj, const char *name, uint32_t hash); + int (*namecmp) (const char *s1, const char *s2); + + /* private variables - do not access directly */ + bool unique; /*!< keys are unique */ + bool caseinsensitive; /*!< case insensitive key comparison */ + bool keepsorted; /*!< keep table in sorted (default: insertion order) */ + bool inserttop; /*!< add new key at the top. (default: bottom) */ + bool lookupforward; /*!< find keys from the top. (default: backward) */ + + void *qmutex; /*!< initialized when QLISTTBL_OPT_THREADSAFE is given */ + size_t num; /*!< number of elements */ + qlisttbl_obj_t *first; /*!< first object pointer */ + qlisttbl_obj_t *last; /*!< last object pointer */ +}; + +/** + * qlisttbl node object data structure + */ +struct qlisttbl_obj_s { + uint32_t hash; /*!< 32bit-hash value of object name */ + char *name; /*!< object name */ + void *data; /*!< data */ + size_t size; /*!< data size */ + + qlisttbl_obj_t *prev; /*!< previous link */ + qlisttbl_obj_t *next; /*!< next link */ +}; + +/** + * qlisttbl value data structure for user return + */ +struct qlisttbl_data_s { + void *data; /*!< data */ + size_t size; /*!< data size */ + uint8_t type; /*!< data type, internal use */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QLISTTBL_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qqueue.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qqueue.h new file mode 100755 index 0000000000000000000000000000000000000000..b087b58e3a6706b810d4f6ccbfb912402cb2365c --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qqueue.h @@ -0,0 +1,116 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Queue container. + * + * @file qqueue.h + */ + +#ifndef QQUEUE_H +#define QQUEUE_H + +#include +#include +#include +#include "qlist.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qqueue_s qqueue_t; + +enum { + QQUEUE_THREADSAFE = (QLIST_THREADSAFE) /*!< make it thread-safe */ +}; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->push(tbl, ...); // easier to switch the container type to other kinds. + * - qqueue_push(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qqueue_t *qqueue(int options); +extern size_t qqueue_setsize(qqueue_t *queue, size_t max); + +extern bool qqueue_push(qqueue_t *queue, const void *data, size_t size); +extern bool qqueue_pushstr(qqueue_t *queue, const char *str); +extern bool qqueue_pushint(qqueue_t *queue, int64_t num); + +extern void *qqueue_pop(qqueue_t *queue, size_t *size); +extern char *qqueue_popstr(qqueue_t *queue); +extern int64_t qqueue_popint(qqueue_t *queue); +extern void *qqueue_popat(qqueue_t *queue, int index, size_t *size); + +extern void *qqueue_get(qqueue_t *queue, size_t *size, bool newmem); +extern char *qqueue_getstr(qqueue_t *queue); +extern int64_t qqueue_getint(qqueue_t *queue); +extern void *qqueue_getat(qqueue_t *queue, int index, size_t *size, bool newmem); + +extern size_t qqueue_size(qqueue_t *queue); +extern void qqueue_clear(qqueue_t *queue); +extern bool qqueue_debug(qqueue_t *queue, FILE *out); +extern void qqueue_free(qqueue_t *queue); + +/** + * qqueue container object structure + */ +struct qqueue_s { + /* encapsulated member functions */ + size_t (*setsize) (qqueue_t *stack, size_t max); + + bool (*push) (qqueue_t *stack, const void *data, size_t size); + bool (*pushstr) (qqueue_t *stack, const char *str); + bool (*pushint) (qqueue_t *stack, int64_t num); + + void *(*pop) (qqueue_t *stack, size_t *size); + char *(*popstr) (qqueue_t *stack); + int64_t (*popint) (qqueue_t *stack); + void *(*popat) (qqueue_t *stack, int index, size_t *size); + + void *(*get) (qqueue_t *stack, size_t *size, bool newmem); + char *(*getstr) (qqueue_t *stack); + int64_t (*getint) (qqueue_t *stack); + void *(*getat) (qqueue_t *stack, int index, size_t *size, bool newmem); + + size_t (*size) (qqueue_t *stack); + void (*clear) (qqueue_t *stack); + bool (*debug) (qqueue_t *stack, FILE *out); + void (*free) (qqueue_t *stack); + + /* private variables - do not access directly */ + qlist_t *list; /*!< data container */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QQUEUE_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qstack.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qstack.h new file mode 100755 index 0000000000000000000000000000000000000000..8afb711960008b9e028767b7a2e09c5de5332243 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qstack.h @@ -0,0 +1,116 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * LIFO Stack container. + * + * @file qstack.h + */ + +#ifndef QSTACK_H +#define QSTACK_H + +#include +#include +#include +#include "qlist.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qstack_s qstack_t; + +enum { + QSTACK_THREADSAFE = (QLIST_THREADSAFE) /*!< make it thread-safe */ +}; + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->push(tbl, ...); // easier to switch the container type to other kinds. + * - qstack_push(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern qstack_t *qstack(int options); +extern size_t qstack_setsize(qstack_t *stack, size_t max); + +extern bool qstack_push(qstack_t *stack, const void *data, size_t size); +extern bool qstack_pushstr(qstack_t *stack, const char *str); +extern bool qstack_pushint(qstack_t *stack, int64_t num); + +extern void *qstack_pop(qstack_t *stack, size_t *size); +extern char *qstack_popstr(qstack_t *stack); +extern int64_t qstack_popint(qstack_t *stack); +extern void *qstack_popat(qstack_t *stack, int index, size_t *size); + +extern void *qstack_get(qstack_t *stack, size_t *size, bool newmem); +extern char *qstack_getstr(qstack_t *stack); +extern int64_t qstack_getint(qstack_t *stack); +extern void *qstack_getat(qstack_t *stack, int index, size_t *size, bool newmem); + +extern size_t qstack_size(qstack_t *stack); +extern void qstack_clear(qstack_t *stack); +extern bool qstack_debug(qstack_t *stack, FILE *out); +extern void qstack_free(qstack_t *stack); + +/** + * qstack container object structure + */ +struct qstack_s { + /* encapsulated member functions */ + size_t (*setsize) (qstack_t *stack, size_t max); + + bool (*push) (qstack_t *stack, const void *data, size_t size); + bool (*pushstr) (qstack_t *stack, const char *str); + bool (*pushint) (qstack_t *stack, int64_t num); + + void *(*pop) (qstack_t *stack, size_t *size); + char *(*popstr) (qstack_t *stack); + int64_t (*popint) (qstack_t *stack); + void *(*popat) (qstack_t *stack, int index, size_t *size); + + void *(*get) (qstack_t *stack, size_t *size, bool newmem); + char *(*getstr) (qstack_t *stack); + int64_t (*getint) (qstack_t *stack); + void *(*getat) (qstack_t *stack, int index, size_t *size, bool newmem); + + size_t (*size) (qstack_t *stack); + void (*clear) (qstack_t *stack); + bool (*debug) (qstack_t *stack, FILE *out); + void (*free) (qstack_t *stack); + + /* private variables - do not access directly */ + qlist_t *list; /*!< data container */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QSTACK_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qtreetbl.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qtreetbl.h new file mode 100755 index 0000000000000000000000000000000000000000..b7463a73a08135672205152a54af7fff9541c805 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qtreetbl.h @@ -0,0 +1,182 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * Tree Table container that implements "Left-Leaning Red-Black" Binary Search Tree algorithm. + * + * @file qtreetbl.h + */ + +#ifndef QTREETBL_H +#define QTREETBL_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qtreetbl_s qtreetbl_t; +typedef struct qtreetbl_obj_s qtreetbl_obj_t; + +/* public functions */ +enum { + QTREETBL_THREADSAFE = (0x01) /*!< make it thread-safe */ +}; + +extern qtreetbl_t *qtreetbl(int options); /*!< qtreetbl constructor */ + +/* member functions + * + * All the member functions can be accessed in both ways: + * - tbl->put(tbl, ...); // easier to switch the container type to other kinds. + * - qtreetbl_put(tbl, ...); // where avoiding pointer overhead is preferred. + */ +extern void qtreetbl_set_compare( + qtreetbl_t *tbl, + int (*cmp)(const void *name1, size_t namesize1, const void *name2, + size_t namesize2)); + +extern bool qtreetbl_put(qtreetbl_t *tbl, const char *name, const void *data, + size_t datasize); +extern bool qtreetbl_putstr(qtreetbl_t *tbl, const char *name, const char *str); +extern bool qtreetbl_putstrf(qtreetbl_t *tbl, const char *name, + const char *format, ...); +extern bool qtreetbl_put_by_obj(qtreetbl_t *tbl, const void *name, + size_t namesize, const void *data, + size_t datasize); + +extern void *qtreetbl_get(qtreetbl_t *tbl, const char *name, size_t *datasize, +bool newmem); +extern char *qtreetbl_getstr(qtreetbl_t *tbl, const char *name, + const bool newmem); +extern void *qtreetbl_get_by_obj(qtreetbl_t *tbl, const char *name, + size_t namesize, size_t *datasize, bool newmem); + +extern bool qtreetbl_remove(qtreetbl_t *tbl, const char *name); +extern bool qtreetbl_remove_by_obj(qtreetbl_t *tbl, const void *name, + size_t namesize); + +extern bool qtreetbl_getnext(qtreetbl_t *tbl, qtreetbl_obj_t *obj, + const bool newmem); + +extern void *qtreetbl_find_min(qtreetbl_t *tbl, size_t *namesize); +extern void *qtreetbl_find_max(qtreetbl_t *tbl, size_t *namesize); +extern qtreetbl_obj_t qtreetbl_find_nearest(qtreetbl_t *tbl, const void *name, + size_t namesize, bool newmem); + +extern size_t qtreetbl_size(qtreetbl_t *tbl); +extern void qtreetbl_clear(qtreetbl_t *tbl); + +extern void qtreetbl_lock(qtreetbl_t *tbl); +extern void qtreetbl_unlock(qtreetbl_t *tbl); + +extern void qtreetbl_free(qtreetbl_t *tbl); + +extern int qtreetbl_byte_cmp(const void *name1, size_t namesize1, + const void *name2, size_t namesize2); +extern bool qtreetbl_debug(qtreetbl_t *tbl, FILE *out); + +/** + * qtreetbl container object + */ +struct qtreetbl_s { + /* encapsulated member functions */ + void (*set_compare)( + qtreetbl_t *tbl, + int (*cmp)(const void *name1, size_t namesize1, const void *name2, + size_t namesize2)); + bool (*put)(qtreetbl_t *tbl, const char *name, const void *data, + size_t size); + bool (*putstr)(qtreetbl_t *tbl, const char *name, const char *str); + bool (*putstrf)(qtreetbl_t *tbl, const char *name, const char *format, ...); + bool (*put_by_obj)(qtreetbl_t *tbl, const void *name, size_t namesize, + const void *data, size_t datasize); + + void *(*get)(qtreetbl_t *tbl, const char *name, size_t *datasize, + bool newmem); + char *(*getstr)(qtreetbl_t *tbl, const char *name, bool newmem); + void *(*get_by_obj)(qtreetbl_t *tbl, const char *name, size_t namesize, + size_t *datasize, bool newmem); + + bool (*remove)(qtreetbl_t *tbl, const char *name); + bool (*remove_by_obj)(qtreetbl_t *tbl, const void *name, size_t namesize); + + bool (*getnext)(qtreetbl_t *tbl, qtreetbl_obj_t *obj, const bool newmem); + + void *(*find_min)(qtreetbl_t *tbl, size_t *namesize); + void *(*find_max)(qtreetbl_t *tbl, size_t *namesize); + qtreetbl_obj_t (*find_nearest)(qtreetbl_t *tbl, const void *name, + size_t namesize, bool newmem); + + size_t (*size)(qtreetbl_t *tbl); + void (*clear)(qtreetbl_t *tbl); + bool (*debug)(qtreetbl_t *tbl, FILE *out); + + void (*lock)(qtreetbl_t *tbl); + void (*unlock)(qtreetbl_t *tbl); + + void (*free)(qtreetbl_t *tbl); + + /* private member functions */ + int (*compare)(const void *name1, size_t namesize1, const void *name2, + size_t namesize2); + + /* private variables - do not access directly */ + void *qmutex; /*!< initialized when QTREETBL_THREADSAFE is given */ + qtreetbl_obj_t *root; /*!< root node */ + size_t num; /*!< number of objects */ + uint8_t tid; /*!< travel id sequencer */ +}; + +/** + * qtreetbl object data structure + */ +struct qtreetbl_obj_s { + void *name; /*!< name of key */ + size_t namesize; /*!< name size */ + void *data; /*!< data */ + size_t datasize; /*!< data size */ + + bool red; /*!< true if upper link is red */ + qtreetbl_obj_t *left; /*!< left node */ + qtreetbl_obj_t *right; /*!< right node */ + + qtreetbl_obj_t *next; /*!< temporary use for tree traversal */ + uint8_t tid; /*!< temporary use for tree traversal */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QTREETBL_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qvector.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qvector.h new file mode 100755 index 0000000000000000000000000000000000000000..65faa0145efd665ec0f872ba23775515b33fc8b2 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/containers/qvector.h @@ -0,0 +1,160 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ +/* This code is written and updated by following people and released under + * the same license as above qLibc license. + * Copyright (c) 2015 Zhenjiang Xie - https://github.com/Charles0429 + *****************************************************************************/ + +/** + * Vector container. + * + * @file qvector.h + */ + +#ifndef QVECTOR_H +#define QVECTOR_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qvector_s qvector_t; +typedef struct qvector_obj_s qvector_obj_t; + +/* public functions */ +enum { + QVECTOR_THREADSAFE = (0x01), /*!< make it thread-safe */ + QVECTOR_RESIZE_DOUBLE = (0x02), /*!< double the size when vector is full*/ + QVECTOR_RESIZE_LINEAR = (0x04), /*!< add the size with initial num when vector is full*/ + QVECTOR_RESIZE_EXACT = (0x08) /*!< add up as much as needed*/ +}; + +extern qvector_t *qvector(size_t max, size_t objsize, int options); + +extern bool qvector_addfirst(qvector_t *vector, const void *data); +extern bool qvector_addlast(qvector_t *vector, const void *data); +extern bool qvector_addat(qvector_t *vector, int index, const void *data); + +extern void *qvector_getfirst(qvector_t *vector, bool newmem); +extern void *qvector_getlast(qvector_t *vector, bool newmem); +extern void *qvector_getat(qvector_t *vector, int index, bool newmem); + +extern bool qvector_setfirst(qvector_t *vector, const void *data); +extern bool qvector_setlast(qvector_t *vector, const void *data); +extern bool qvector_setat(qvector_t *vector, int index, const void *data); + +extern void *qvector_popfirst(qvector_t *vector); +extern void *qvector_poplast(qvector_t *vector); +extern void *qvector_popat(qvector_t *vector, int index); + +extern bool qvector_removefirst(qvector_t *vector); +extern bool qvector_removelast(qvector_t *vector); +extern bool qvector_removeat(qvector_t *vector, int index); + +extern size_t qvector_size(qvector_t *vector); +extern bool qvector_resize(qvector_t *vector, size_t newmax); + +extern void *qvector_toarray(qvector_t *vector, size_t *size); + +extern void qvector_lock(qvector_t *vector); +extern void qvector_unlock(qvector_t *vector); + +extern void qvector_clear(qvector_t *vector); +extern bool qvector_debug(qvector_t *vector, FILE *out); +extern void qvector_free(qvector_t *vector); + +extern void qvector_reverse(qvector_t *vector); +extern bool qvector_getnext(qvector_t *vector, qvector_obj_t *obj, bool newmem); + +/** + * qvector container object + */ +struct qvector_s { + /* capsulated member functions */ + + bool (*addfirst)(qvector_t *vector, const void *object); + bool (*addlast)(qvector_t *vector, const void *data); + bool (*addat)(qvector_t *vector, int index, const void *data); + + void *(*getfirst)(qvector_t *vector, bool newmem); + void *(*getlast)(qvector_t *vector, bool newmem); + void *(*getat)(qvector_t *vector, int index, bool newmem); + + bool (*setfirst)(qvector_t *vector, const void *data); + bool (*setlast)(qvector_t *vector, const void *data); + bool (*setat)(qvector_t *vector, int index, const void *data); + + void *(*popfirst)(qvector_t *vector); + void *(*poplast)(qvector_t *vector); + void *(*popat)(qvector_t *vector, int index); + + bool (*removefirst)(qvector_t *vector); + bool (*removelast)(qvector_t *vector); + bool (*removeat)(qvector_t *vector, int index); + + size_t (*size)(qvector_t *vector); + bool (*resize)(qvector_t *vector, size_t newmax); + + void *(*toarray)(qvector_t *vector, size_t *size); + + void (*lock)(qvector_t *vector); + void (*unlock)(qvector_t *vector); + + void (*clear)(qvector_t *vector); + bool (*debug)(qvector_t *vector, FILE *out); + void (*free)(qvector_t *vector); + + void (*reverse)(qvector_t *vector); + bool (*getnext)(qvector_t *vector, qvector_obj_t *obj, bool newmem); + + /* private variables - do not access directly */ + void *qmutex; + void *data; + size_t num; /*number of elements*/ + size_t objsize; /*the size of each element*/ + size_t max; /*allocated number of elements*/ + int options; + size_t initnum; +}; + +struct qvector_obj_s { + void *data; + int index; +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QVECTOR_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qaconf.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qaconf.h new file mode 100755 index 0000000000000000000000000000000000000000..53e6a58ceeaabdecd9a4bd06d2a598a547678de3 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qaconf.h @@ -0,0 +1,229 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * Apache-style Configuration File Parser. + * + * This is a qLibc extension implementing Apache-style configuration file + * parser. + * + * @file qaconf.h + */ + +#ifndef QACONF_H +#define QACONF_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qaconf_s qaconf_t; +typedef struct qaconf_option_s qaconf_option_t; +typedef struct qaconf_cbdata_s qaconf_cbdata_t; +typedef char *(qaconf_cb_t) (qaconf_cbdata_t *data, void *userdata); + +/* public functions */ +extern qaconf_t *qaconf(void); + +/* user's callback function prototype */ +#define QAC_CB(func) char *func(qaconf_cbdata_t *data, void *userdata) +#define QAC_TAKEn(n) (n) + +/* parser option flags */ +enum { + QAC_CASEINSENSITIVE = (1), + QAC_IGNOREUNKNOWN = (2), // Ignore unknown option directives. +}; + +/** + * Argument type check + * + * uint32_t type 32bit variable is used for passing argument types. + * notused bool float int #arg + * ---- ---====== ---- --== ==== ---- ---- + * rrrr rrBb bbbb Ffff ffIi iiii aaaa aaaa (32bit mask) + * (6bit) (6bit) (6bit) (6bit) (8bit) + * + * r : Not Used + * B : Consider all arguments as BOOL type unless individually specified. + * b : Flaged argument(1~5) must be bool type. + * F : Consider all arguments as FLOAT type unless individually specified. + * f : Flaged argument(1~5) must be float type. + * I : Consider all arguments as INTEGER type unless individually specified. + * i : Flaged argument(1~5) must be integer type. + * a : Number of arguments (0~254). + * Value 255 means take any number of arguments. + * + * An option takes 1 argument. + * QAC_TAKE_STR <= String(any) type + * QAC_TAKE_INT <= Integer type + * QAC_TAKE_FLOAT <= Float type + * QAC_TAKE_BOOL <= Bool type + * + * QAC_TAKE1 <= equivalent to QAC_TAKE_STR + * QAC_TAKE1 | QAC_A1_BOOL <= equivalent to QAC_TAKE_BOOL + * + * An option takes 2 arguments, bool and float. + * QAC_TAKE2 | QAC_A1_BOOL | QAC_A2_FLOAT + * + * An option takes any number of arguments in any type. + * QAC_TAKEALL + * + * An option takes any number of arguments but 1st one must be bool and + * 2nd one must be integer and rest of them must be float. + * QAC_TAKEALL | QAC_A1_BOOL | QAC_A2_INT | QAC_AA_FLOAT + */ +enum qaconf_take { + // Define string(any) type argument. + QAC_A1_STR = 0, + QAC_A2_STR = 0, + QAC_A3_STR = 0, + QAC_A4_STR = 0, + QAC_A5_STR = 0, + QAC_AA_STR = 0, // All string unless individually specified. + + // Define integer type argument. + QAC_A1_INT = (1 << 8), + QAC_A2_INT = (QAC_A1_INT << 1), + QAC_A3_INT = (QAC_A1_INT << 2), + QAC_A4_INT = (QAC_A1_INT << 3), + QAC_A5_INT = (QAC_A1_INT << 4), + QAC_AA_INT = (QAC_A1_INT << 5), // All integer unless specified. + + // Define floating point type argument. + QAC_A1_FLOAT = (1 << 16), + QAC_A2_FLOAT = (QAC_A1_FLOAT << 1), + QAC_A3_FLOAT = (QAC_A1_FLOAT << 2), + QAC_A4_FLOAT = (QAC_A1_FLOAT << 3), + QAC_A5_FLOAT = (QAC_A1_FLOAT << 4), + QAC_AA_FLOAT = (QAC_A1_FLOAT << 5), // All float unless specified. + + // Define bool(true/false, yes/no, on/off, 1/0) type argument. + QAC_A1_BOOL = (1 << 24), + QAC_A2_BOOL = (QAC_A1_BOOL << 1), + QAC_A3_BOOL = (QAC_A1_BOOL << 2), + QAC_A4_BOOL = (QAC_A1_BOOL << 3), + QAC_A5_BOOL = (QAC_A1_BOOL << 4), + QAC_AA_BOOL = (QAC_A1_BOOL << 5), // All bool unless specified. + + // Number of arguments to take + QAC_TAKENONE = QAC_TAKEn(0), + QAC_TAKE0 = QAC_TAKENONE, + QAC_TAKE1 = QAC_TAKEn(1), + QAC_TAKE2 = QAC_TAKEn(2), + QAC_TAKE3 = QAC_TAKEn(3), + QAC_TAKE4 = QAC_TAKEn(4), + QAC_TAKE5 = QAC_TAKEn(5), + // use QAC_TAKEn(N) macro for 6~254 arguments. + QAC_TAKEALL = 0xFF, // Take any number of elements. (0 ~ INT_MAX) + + // Convenient synonyms + QAC_TAKE_STR = (QAC_TAKE1 | QAC_A1_STR), + QAC_TAKE_INT = (QAC_TAKE1 | QAC_A1_INT), + QAC_TAKE_FLOAT = (QAC_TAKE1 | QAC_A1_FLOAT), + QAC_TAKE_BOOL = (QAC_TAKE1 | QAC_A1_BOOL), +}; +#define QAC_TAKEn(n) (n) + +/* pre-defined sections */ +enum qaconf_section { + QAC_SECTION_ALL = (0), /* pre-defined */ + QAC_SECTION_ROOT = (1) /* pre-defined */ +}; + +/* option type */ +enum qaconf_otype { + QAC_OTYPE_OPTION = 0, /* general option */ + QAC_OTYPE_SECTIONOPEN = 1, /* section open */ + QAC_OTYPE_SECTIONCLOSE = 2 /* section close */ +}; + +/** + * qaconf_t object. + */ +struct qaconf_s { + /* capsulated member functions */ + int (*addoptions) (qaconf_t *qaconf, const qaconf_option_t *options); + void (*setdefhandler) (qaconf_t *qaconf, qaconf_cb_t *callback); + void (*setuserdata) (qaconf_t *qaconf, const void *userdata); + int (*parse) (qaconf_t *qaconf, const char *filepath, uint8_t flags); + const char *(*errmsg) (qaconf_t *qaconf); + void (*reseterror) (qaconf_t *qaconf); + void (*free) (qaconf_t *qaconf); + + /* private variables - do not access directly */ + int numoptions; /*!< a number of user defined options */ + qaconf_option_t *options; /*!< option data */ + + qaconf_cb_t *defcb; /*!< default callback for unregistered option */ + void *userdata; /*!< userdata */ + + char *filepath; /*!< current processing file's path */ + int lineno; /*!< current processing line number */ + + char *errstr; /*!< last error string */ +}; + +/** + * structure for user option definition. + */ +struct qaconf_option_s { + char *name; /*!< name of option. */ + uint32_t take; /*!< number of arguments and type checking */ + qaconf_cb_t *cb; /*!< callback function */ + uint64_t sectionid; /*!< sectionid if this is a section */ + uint64_t sections; /*!< ORed sectionid(s) where this option is allowed */ +}; +#define QAC_OPTION_END {NULL, 0, NULL, 0, 0} + +/** + * callback data structure. + */ +struct qaconf_cbdata_s { + enum qaconf_otype otype; /*!< option type */ + uint64_t section; /*!< current section where this option is located */ + uint64_t sections; /*!< ORed all parent's sectionid(s) including current sections */ + uint8_t level; /*!< number of parents(level), root level is 0 */ + qaconf_cbdata_t *parent; /*!< upper parent link */ + + int argc; /*!< number arguments. always equal or greater than 1. */ + char **argv; /*!< argument pointers. argv[0] is option name. */ + + void *data; /*!< where actual data is stored */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QACONF_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qconfig.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qconfig.h new file mode 100755 index 0000000000000000000000000000000000000000..feea277987655034e2023fdd7f31af16dee6003c --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qconfig.h @@ -0,0 +1,57 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * INI-style Configuration File Parser. + * + * This is a qLibc extension implementing INI-style configuration file parser. + * + * @file qconfig.h + */ + +#ifndef QCONFIG_H +#define QCONFIG_H + +#include +#include +#include +#include "../containers/qlisttbl.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* public functions */ +extern qlisttbl_t *qconfig_parse_file(qlisttbl_t *tbl, const char *filepath, char sepchar); +extern qlisttbl_t *qconfig_parse_str(qlisttbl_t *tbl, const char *str, char sepchar); + +#ifdef __cplusplus +} +#endif + +#endif /* QCONFIG_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qdatabase.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qdatabase.h new file mode 100755 index 0000000000000000000000000000000000000000..1101731dcac72376b82ac0f07aada1cd59952b4b --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qdatabase.h @@ -0,0 +1,140 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * Generic database interface. + * + * This is a qLibc extension implementing generic database interface. + * For now, it supports only MySQL database. + * + * @file qdatabase.h + */ + +#ifndef QDATABASE_H +#define QDATABASE_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* database header files should be included before this header file. */ +#ifdef _mysql_h +#define Q_ENABLE_MYSQL (1) +#endif /* _mysql_h */ + +/* types */ +typedef struct qdbresult_s qdbresult_t; +typedef struct qdb_s qdb_t; + +/* public functions */ +extern qdb_t *qdb(const char *dbtype, + const char *addr, int port, const char *database, + const char *username, const char *password, bool autocommit); + +/** + * qdbresult object structure + */ +struct qdbresult_s { + /* encapsulated member functions */ + const char *(*getstr) (qdbresult_t *result, const char *field); + const char *(*get_str_at) (qdbresult_t *result, int idx); + int (*getint) (qdbresult_t *result, const char *field); + int (*get_int_at) (qdbresult_t *result, int idx); + bool (*getnext) (qdbresult_t *result); + + int (*get_cols) (qdbresult_t *result); + int (*get_rows) (qdbresult_t *result); + int (*get_row) (qdbresult_t *result); + + void (*free) (qdbresult_t *result); + +#ifdef Q_ENABLE_MYSQL + /* private variables for mysql database - do not access directly */ + bool fetchtype; + MYSQL_RES *rs; + MYSQL_FIELD *fields; + MYSQL_ROW row; + int cols; + int cursor; +#endif +}; + +/* qdb object structure */ +struct qdb_s { + /* encapsulated member functions */ + bool (*open) (qdb_t *db); + bool (*close) (qdb_t *db); + + int (*execute_update) (qdb_t *db, const char *query); + int (*execute_updatef) (qdb_t *db, const char *format, ...); + + qdbresult_t *(*execute_query) (qdb_t *db, const char *query); + qdbresult_t *(*execute_queryf) (qdb_t *db, const char *format, ...); + + bool (*begin_tran) (qdb_t *db); + bool (*end_tran) (qdb_t *db, bool commit); + bool (*commit) (qdb_t *db); + bool (*rollback) (qdb_t *db); + + bool (*set_fetchtype) (qdb_t *db, bool fromdb); + bool (*get_conn_status) (qdb_t *db); + bool (*ping) (qdb_t *db); + const char *(*get_error) (qdb_t *db, unsigned int *errorno); + void (*free) (qdb_t *db); + + /* private variables - do not access directly */ + void *qmutex; + + bool connected; /*!< if opened true, if closed false */ + + struct { + char *dbtype; + char *addr; + int port; + char *username; + char *password; + char *database; + bool autocommit; + bool fetchtype; + } info; /*!< database connection information */ + +#ifdef Q_ENABLE_MYSQL + /* private variables for mysql database - do not access directly */ + MYSQL *mysql; +#endif +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QDATABASE_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qhttpclient.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qhttpclient.h new file mode 100755 index 0000000000000000000000000000000000000000..ba9f5c705873ce079143a793ea051416a02266ae --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qhttpclient.h @@ -0,0 +1,127 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * HTTP client. + * + * This is a qLibc extension implementing HTTP client. + * + * @file qhttpclient.h + */ + +#ifndef QHTTPCLIENT_H +#define QHTTPCLIENT_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qhttpclient_s qhttpclient_t; + +/* constants */ +#define QHTTPCLIENT_NAME "qLibc" + +/* public functions */ +extern qhttpclient_t *qhttpclient(const char *hostname, int port); + +/** + * qhttpclient object structure + */ +struct qhttpclient_s { + /* encapsulated member functions */ + bool (*setssl) (qhttpclient_t *client); + void (*settimeout) (qhttpclient_t *client, int timeoutms); + void (*setkeepalive) (qhttpclient_t *client, bool keepalive); + void (*setuseragent) (qhttpclient_t *client, const char *useragent); + + bool (*open) (qhttpclient_t *client); + + bool (*head) (qhttpclient_t *client, const char *uri, int *rescode, + qlisttbl_t *reqheaders, qlisttbl_t *resheaders); + bool (*get) (qhttpclient_t *client, const char *uri, int fd, + off_t *savesize, int *rescode, + qlisttbl_t *reqheaders, qlisttbl_t *resheaders, + bool (*callback) (void *userdata, off_t recvbytes), + void *userdata); + bool (*put) (qhttpclient_t *client, const char *uri, int fd, + off_t length, int *retcode, qlisttbl_t *userheaders, + qlisttbl_t *resheaders, + bool (*callback) (void *userdata, off_t sentbytes), + void *userdata); + void *(*cmd) (qhttpclient_t *client, + const char *method, const char *uri, + void *data, size_t size, int *rescode, + size_t *contentslength, + qlisttbl_t *reqheaders, qlisttbl_t *resheaders); + + char *(*json) (qhttpclient_t *client, + const char *method, const char *uri, + char *data, size_t size, int *rescode, + size_t *contentslength, + qlisttbl_t *reqheaders, qlisttbl_t *resheaders); + + bool (*sendrequest) (qhttpclient_t *client, const char *method, + const char *uri, qlisttbl_t *reqheaders); + int (*readresponse) (qhttpclient_t *client, qlisttbl_t *resheaders, + off_t *contentlength); + + ssize_t (*gets) (qhttpclient_t *client, char *buf, size_t bufsize); + ssize_t (*read) (qhttpclient_t *client, void *buf, size_t nbytes); + ssize_t (*write) (qhttpclient_t *client, const void *buf, + size_t nbytes); + off_t (*recvfile) (qhttpclient_t *client, int fd, off_t nbytes); + off_t (*sendfile) (qhttpclient_t *client, int fd, off_t nbytes); + + bool (*close) (qhttpclient_t *client); + void (*free) (qhttpclient_t *client); + + /* private variables - do not access directly */ + int socket; /*!< socket descriptor */ + void *ssl; /*!< will be used if SSL has been enabled at compile time */ + + struct sockaddr_in addr; + char *hostname; + int port; + + int timeoutms; /*< wait timeout milliseconds*/ + bool keepalive; /*< keep-alive flag */ + char *useragent; /*< user-agent name */ + + bool connclose; /*< response keep-alive flag for a last request */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QHTTPCLIENT_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qlog.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qlog.h new file mode 100755 index 0000000000000000000000000000000000000000..89f0b96f2a59831f72b30b30bc85c679a7f88f52 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qlog.h @@ -0,0 +1,91 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * Rotating file logger. + * + * This is a qLibc extension implementing application level auto-rotating file + * logger. + * + * @file qlog.h + */ + +#ifndef QLOG_H +#define QLOG_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* types */ +typedef struct qlog_s qlog_t; + +/* constants */ +#define QLOG_OPT_THREADSAFE (0x01) +#define QLOG_OPT_FLUSH (0x01 << 1) + +/* public functions */ +extern qlog_t *qlog(const char *filepathfmt, mode_t mode, int rotateinterval, int options); + +/** + * qlog structure object structure + */ +struct qlog_s { + /* encapsulated member functions */ + bool (*write) (qlog_t *log, const char *str); + bool (*writef) (qlog_t *log, const char *format, ...); + bool (*duplicate) (qlog_t *log, FILE *outfp, bool flush); + bool (*flush) (qlog_t *log); + void (*free) (qlog_t *log); + + /* private variables - do not access directly */ + void *qmutex; /*!< activated if compiled with --enable-threadsafe */ + + char filepathfmt[PATH_MAX]; /*!< file file naming format like + /somepath/daily-%Y%m%d.log */ + char filepath[PATH_MAX]; /*!< generated system path of log file */ + FILE *fp; /*!< file pointer of logpath */ + mode_t mode; /*!< file mode */ + int rotateinterval; /*!< log file will be rotate in this interval seconds */ + int nextrotate; /*!< next rotate universal time, seconds */ + bool logflush; /*!< flag for immediate flushing */ + + FILE *outfp; /*!< stream pointer for duplication */ + bool outflush; /*!< flag for immediate flushing for duplicated stream */ +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QLOG_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qtokenbucket.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qtokenbucket.h new file mode 100755 index 0000000000000000000000000000000000000000..1101731dcac72376b82ac0f07aada1cd59952b4b --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/extensions/qtokenbucket.h @@ -0,0 +1,140 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + ******************************************************************************/ + +/** + * Generic database interface. + * + * This is a qLibc extension implementing generic database interface. + * For now, it supports only MySQL database. + * + * @file qdatabase.h + */ + +#ifndef QDATABASE_H +#define QDATABASE_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* database header files should be included before this header file. */ +#ifdef _mysql_h +#define Q_ENABLE_MYSQL (1) +#endif /* _mysql_h */ + +/* types */ +typedef struct qdbresult_s qdbresult_t; +typedef struct qdb_s qdb_t; + +/* public functions */ +extern qdb_t *qdb(const char *dbtype, + const char *addr, int port, const char *database, + const char *username, const char *password, bool autocommit); + +/** + * qdbresult object structure + */ +struct qdbresult_s { + /* encapsulated member functions */ + const char *(*getstr) (qdbresult_t *result, const char *field); + const char *(*get_str_at) (qdbresult_t *result, int idx); + int (*getint) (qdbresult_t *result, const char *field); + int (*get_int_at) (qdbresult_t *result, int idx); + bool (*getnext) (qdbresult_t *result); + + int (*get_cols) (qdbresult_t *result); + int (*get_rows) (qdbresult_t *result); + int (*get_row) (qdbresult_t *result); + + void (*free) (qdbresult_t *result); + +#ifdef Q_ENABLE_MYSQL + /* private variables for mysql database - do not access directly */ + bool fetchtype; + MYSQL_RES *rs; + MYSQL_FIELD *fields; + MYSQL_ROW row; + int cols; + int cursor; +#endif +}; + +/* qdb object structure */ +struct qdb_s { + /* encapsulated member functions */ + bool (*open) (qdb_t *db); + bool (*close) (qdb_t *db); + + int (*execute_update) (qdb_t *db, const char *query); + int (*execute_updatef) (qdb_t *db, const char *format, ...); + + qdbresult_t *(*execute_query) (qdb_t *db, const char *query); + qdbresult_t *(*execute_queryf) (qdb_t *db, const char *format, ...); + + bool (*begin_tran) (qdb_t *db); + bool (*end_tran) (qdb_t *db, bool commit); + bool (*commit) (qdb_t *db); + bool (*rollback) (qdb_t *db); + + bool (*set_fetchtype) (qdb_t *db, bool fromdb); + bool (*get_conn_status) (qdb_t *db); + bool (*ping) (qdb_t *db); + const char *(*get_error) (qdb_t *db, unsigned int *errorno); + void (*free) (qdb_t *db); + + /* private variables - do not access directly */ + void *qmutex; + + bool connected; /*!< if opened true, if closed false */ + + struct { + char *dbtype; + char *addr; + int port; + char *username; + char *password; + char *database; + bool autocommit; + bool fetchtype; + } info; /*!< database connection information */ + +#ifdef Q_ENABLE_MYSQL + /* private variables for mysql database - do not access directly */ + MYSQL *mysql; +#endif +}; + +#ifdef __cplusplus +} +#endif + +#endif /* QDATABASE_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/ipc/qsem.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/ipc/qsem.h new file mode 100755 index 0000000000000000000000000000000000000000..892b68d1dbed0b4439c4355f5ddd13a50dd4563d --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/ipc/qsem.h @@ -0,0 +1,56 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qsem header file. + * + * @file qsem.h + */ + +#ifndef QSEM_H +#define QSEM_H + +#ifdef __cplusplus +extern "C" { +#endif + +extern int qsem_init(const char *keyfile, int keyid, int nsems, bool recreate); +extern int qsem_getid(const char *keyfile, int keyid); +extern bool qsem_enter(int semid, int semno); +extern bool qsem_enter_nowait(int semid, int semno); +extern bool qsem_enter_force(int semid, int semno, int maxwaitms, + bool *forceflag); +extern bool qsem_leave(int semid, int semno); +extern bool qsem_check(int semid, int semno); +extern bool qsem_free(int semid); + +#ifdef __cplusplus +} +#endif + +#endif /* QSEM_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/ipc/qshm.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/ipc/qshm.h new file mode 100755 index 0000000000000000000000000000000000000000..4ae39ad6bb7a0fc0b8433ba0aae3811c73da70fb --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/ipc/qshm.h @@ -0,0 +1,52 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qshm header file. + * + * @file qshm.h + */ + +#ifndef QSHM_H +#define QSHM_H + +#ifdef __cplusplus +extern "C" { +#endif + +extern int qshm_init(const char *keyfile, int keyid, size_t size, + bool recreate); +extern int qshm_getid(const char *keyfile, int keyid); +extern void *qshm_get(int shmid); +extern bool qshm_free(int shmid); + +#ifdef __cplusplus +} +#endif + +#endif /* QSHM_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/qlibc.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/qlibc.h new file mode 100755 index 0000000000000000000000000000000000000000..d8d18876e8b16a982dbad311cf13d02c8c514307 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/qlibc.h @@ -0,0 +1,65 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qlibc header file. + * + * @file qlibc.h + */ + +#ifndef QLIBC_H +#define QLIBC_H + +/* containers */ +#include "containers/qtreetbl.h" +#include "containers/qhashtbl.h" +#include "containers/qhasharr.h" +#include "containers/qlisttbl.h" +#include "containers/qlist.h" +#include "containers/qvector.h" +#include "containers/qqueue.h" +#include "containers/qstack.h" +#include "containers/qgrow.h" + +/* utilities */ +#include "utilities/qcount.h" +#include "utilities/qencode.h" +#include "utilities/qfile.h" +#include "utilities/qhash.h" +#include "utilities/qio.h" +#include "utilities/qsocket.h" +#include "utilities/qstring.h" +#include "utilities/qsystem.h" +#include "utilities/qtime.h" + +/* ipc */ +#include "ipc/qsem.h" +#include "ipc/qshm.h" + +#endif /* QLIBC_H */ + diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/qlibcext.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/qlibcext.h new file mode 100755 index 0000000000000000000000000000000000000000..42c922a270eae5ce8ff7a4c4388f7d5dc7933d1b --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/qlibcext.h @@ -0,0 +1,45 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qlibc extension header file. + * + * @file qlibcext.h + */ + +#ifndef QLIBCEXT_H +#define QLIBCEXT_H + +#include "extensions/qconfig.h" +#include "extensions/qaconf.h" +#include "extensions/qlog.h" +#include "extensions/qhttpclient.h" +#include "extensions/qdatabase.h" +#include "extensions/qtokenbucket.h" + +#endif /* QLIBCEXT_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qcount.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qcount.h new file mode 100755 index 0000000000000000000000000000000000000000..f110cb4d1edc8d1243dc86354ca08c14d474831d --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qcount.h @@ -0,0 +1,54 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qcount header file. + * + * @file qcount.h + */ + +#ifndef QCOUNT_H +#define QCOUNT_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern int64_t qcount_read(const char *filepath); +extern bool qcount_save(const char *filepath, int64_t number); +extern int64_t qcount_update(const char *filepath, int64_t number); + +#ifdef __cplusplus +} +#endif + +#endif /* QCOUNT_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qencode.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qencode.h new file mode 100755 index 0000000000000000000000000000000000000000..4c8305e76fee45f51231effe134495cb2d75b8ae --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qencode.h @@ -0,0 +1,59 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qencode header file. + * + * @file qencode.h + */ + +#ifndef QENCODE_H +#define QENCODE_H + +#include +#include +#include "../containers/qlisttbl.h" + +#ifdef __cplusplus +extern "C" { +#endif + +extern qlisttbl_t *qparse_queries(qlisttbl_t *tbl, const char *query, + char equalchar, char sepchar, int *count); +extern char *qurl_encode(const void *bin, size_t size); +extern size_t qurl_decode(char *str); +extern char *qbase64_encode(const void *bin, size_t size); +extern size_t qbase64_decode(char *str); +extern char *qhex_encode(const void *bin, size_t size); +extern size_t qhex_decode(char *str); + +#ifdef __cplusplus +} +#endif + +#endif /* QENCODE_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qfile.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qfile.h new file mode 100755 index 0000000000000000000000000000000000000000..fcb8ebd59d88da3d98b9430b9175cc9edfb3643d --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qfile.h @@ -0,0 +1,69 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qfile header file. + * + * @file qfile.h + */ + +#ifndef QFILE_H +#define QFILE_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern bool qfile_lock(int fd); +extern bool qfile_unlock(int fd); +extern bool qfile_exist(const char *filepath); +extern void *qfile_load(const char *filepath, size_t *nbytes); +extern void *qfile_read(FILE *fp, size_t *nbytes); +extern ssize_t qfile_save(const char *filepath, const void *buf, size_t size, + bool append); +extern bool qfile_mkdir(const char *dirpath, mode_t mode, bool recursive); + +extern char *qfile_get_name(const char *filepath); +extern char *qfile_get_dir(const char *filepath); +extern char *qfile_get_ext(const char *filepath); +extern off_t qfile_get_size(const char *filepath); + +extern bool qfile_check_path(const char *path); +extern char *qfile_correct_path(char *path); +extern char *qfile_abspath(char *buf, size_t bufsize, const char *path); + +#ifdef __cplusplus +} +#endif + +#endif /* QFILE_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qhash.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qhash.h new file mode 100755 index 0000000000000000000000000000000000000000..251759ce3657ad7a890d612270c1c67df094027f --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qhash.h @@ -0,0 +1,61 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qhash header file. + * + * @file qhash.h + */ + +#ifndef QHASH_H +#define QHASH_H + +#include +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern bool qhashmd5(const void *data, size_t nbytes, void *retbuf); +extern bool qhashmd5_file(const char *filepath, off_t offset, ssize_t nbytes, + void *retbuf); + +extern uint32_t qhashfnv1_32(const void *data, size_t nbytes); +extern uint64_t qhashfnv1_64(const void *data, size_t nbytes); + +extern uint32_t qhashmurmur3_32(const void *data, size_t nbytes); +extern bool qhashmurmur3_128(const void *data, size_t nbytes, void *retbuf); + +#ifdef __cplusplus +} +#endif + +#endif /* QHASH_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qio.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qio.h new file mode 100755 index 0000000000000000000000000000000000000000..f26e734e4aa924f8f86cca0e3538afae44dbb112 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qio.h @@ -0,0 +1,60 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qio header file. + * + * @file qio.h + */ + +#ifndef QIO_H +#define QIO_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern int qio_wait_readable(int fd, int timeoutms); +extern int qio_wait_writable(int fd, int timeoutms); +extern ssize_t qio_read(int fd, void *buf, size_t nbytes, int timeoutms); +extern ssize_t qio_write(int fd, const void *data, size_t nbytes, + int timeoutms); +extern off_t qio_send(int outfd, int infd, off_t nbytes, int timeoutms); +extern ssize_t qio_gets(int fd, char *buf, size_t bufsize, int timeoutms); +extern ssize_t qio_puts(int fd, const char *str, int timeoutms); +extern ssize_t qio_printf(int fd, int timeoutms, const char *format, ...); + +#ifdef __cplusplus +} +#endif + +#endif /* QIO_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qsocket.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qsocket.h new file mode 100755 index 0000000000000000000000000000000000000000..700e3ddea4f492154d1feca81a5f50b51d539da7 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qsocket.h @@ -0,0 +1,56 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qsocket header file. + * + * @file qsocket.h + */ + +#ifndef QSOCKET_H +#define QSOCKET_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern int qsocket_open(const char *hostname, int port, int timeoutms); +extern bool qsocket_close(int sockfd, int timeoutms); +extern bool qsocket_get_addr(struct sockaddr_in *addr, const char *hostname, + int port); +extern char *qsocket_get_localaddr(char *buf, size_t bufsize); + +#ifdef __cplusplus +} +#endif + +#endif /* QSOCKET_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qstring.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qstring.h new file mode 100755 index 0000000000000000000000000000000000000000..3d4c16d840e2c8825f7e38f3d6f4a1a583e5e3a4 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qstring.h @@ -0,0 +1,78 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qstring header file. + * + * @file qstring.h + */ + +#ifndef QSTRING_H +#define QSTRING_H + +#include +#include +#include "../containers/qlist.h" + +#ifdef __cplusplus +extern "C" { +#endif + +extern char *qstrtrim(char *str); +extern char *qstrtrim_head(char *str); +extern char *qstrtrim_tail(char *str); +extern char *qstrunchar(char *str, char head, char tail); +extern char *qstrreplace(const char *mode, char *srcstr, const char *tokstr, + const char *word); +extern char *qstrcpy(char *dst, size_t size, const char *src); +extern char *qstrncpy(char *dst, size_t size, const char *src, size_t nbytes); +extern char *qstrdupf(const char *format, ...); +extern char *qstrdup_between(const char *str, const char *start, + const char *end); +extern void *qmemdup(const void *data, size_t size); +extern char *qstrcatf(char *str, const char *format, ...); +extern char *qstrgets(char *buf, size_t size, char **offset); +extern char *qstrrev(char *str); +extern char *qstrupper(char *str); +extern char *qstrlower(char *str); +extern char *qstrtok(char *str, const char *delimiters, char *retstop, + int *offset); +extern qlist_t *qstrtokenizer(const char *str, const char *delimiters); +extern char *qstrunique(const char *seed); +extern char *qstr_comma_number(int number); +extern bool qstrtest(int (*testfunc)(int), const char *str); +extern bool qstr_is_email(const char *email); +extern bool qstr_is_ip4addr(const char *str); +extern char *qstr_conv_encoding(const char *fromstr, const char *fromcode, + const char *tocode, float mag); + +#ifdef __cplusplus +} +#endif + +#endif /* QSTRING_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qsystem.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qsystem.h new file mode 100755 index 0000000000000000000000000000000000000000..129eb626d8cb85bd90a14a18731eca5211055991 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qsystem.h @@ -0,0 +1,49 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qsystem header file. + * + * @file qsystem.h + */ + +#ifndef QSYSTEM_H +#define QSYSTEM_H + +#ifdef __cplusplus +extern "C" { +#endif + +extern const char *qgetenv(const char *envname, const char *nullstr); +extern char *qsyscmd(const char *cmd); + +#ifdef __cplusplus +} +#endif + +#endif /* QSYSTEM_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qtime.h b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qtime.h new file mode 100755 index 0000000000000000000000000000000000000000..ecd2d588d2944f6ec989c9ccb920ca50e06b7ef3 --- /dev/null +++ b/qlibc/0.0.0/Linux-x86_64/include/qlibc/utilities/qtime.h @@ -0,0 +1,67 @@ +/****************************************************************************** + * qLibc + * + * Copyright (c) 2010-2015 Seungyoung Kim. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + *****************************************************************************/ + +/** + * qtime header file. + * + * @file qtime.h + */ + +#ifndef QTIME_H +#define QTIME_H + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +extern void qtime_timespec_diff(struct timespec t1, struct timespec t2, + struct timespec *diff); +extern void qtime_timeval_diff(struct timeval t1, struct timeval t2, + struct timeval *diff); + +extern long qtime_current_milli(void); + +extern char *qtime_localtime_strf(char *buf, int size, time_t utctime, + const char *format); +extern char *qtime_localtime_str(time_t utctime); +extern const char *qtime_localtime_staticstr(time_t utctime); +extern char *qtime_gmt_strf(char *buf, int size, time_t utctime, + const char *format); +extern char *qtime_gmt_str(time_t utctime); +extern const char *qtime_gmt_staticstr(time_t utctime); +extern time_t qtime_parse_gmtstr(const char *gmtstr); + +#ifdef __cplusplus +} +#endif + +#endif /* QTIME_H */ diff --git a/qlibc/0.0.0/Linux-x86_64/libqlibc.so.1 b/qlibc/0.0.0/Linux-x86_64/libqlibc.so.1 new file mode 100755 index 0000000000000000000000000000000000000000..edccc197530cfff4c408ebc939c20ca02654eda8 Binary files /dev/null and b/qlibc/0.0.0/Linux-x86_64/libqlibc.so.1 differ diff --git a/qlibc/0.0.0/Linux-x86_64/libqlibcext.so.1 b/qlibc/0.0.0/Linux-x86_64/libqlibcext.so.1 new file mode 100755 index 0000000000000000000000000000000000000000..436c2143237a6de192a0de754e063f45ffeffba9 Binary files /dev/null and b/qlibc/0.0.0/Linux-x86_64/libqlibcext.so.1 differ diff --git a/zmq/3.2.5/Linux-x86_64/include/zmq.h b/zmq/3.2.5/Linux-x86_64/include/zmq.h new file mode 100755 index 0000000000000000000000000000000000000000..56d28f80d5d99042e02c9bc5b0f6a785a39029e4 --- /dev/null +++ b/zmq/3.2.5/Linux-x86_64/include/zmq.h @@ -0,0 +1,402 @@ +/* + Copyright (c) 2007-2012 iMatix Corporation + Copyright (c) 2009-2011 250bpm s.r.o. + Copyright (c) 2011 VMware, Inc. + Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file + + This file is part of 0MQ. + + 0MQ is free software; you can redistribute it and/or modify it under + the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + 0MQ is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with this program. If not, see . +*/ + +#ifndef __ZMQ_H_INCLUDED__ +#define __ZMQ_H_INCLUDED__ + +#ifdef __cplusplus +extern "C" { +#endif + +#if !defined WINCE +#include +#endif +#include +#include +#if defined _WIN32 +#include +#endif + +/* Handle DSO symbol visibility */ +#if defined _WIN32 +# if defined DLL_EXPORT +# define ZMQ_EXPORT __declspec(dllexport) +# else +# define ZMQ_EXPORT __declspec(dllimport) +# endif +#else +# if defined __SUNPRO_C || defined __SUNPRO_CC +# define ZMQ_EXPORT __global +# elif (defined __GNUC__ && __GNUC__ >= 4) || defined __INTEL_COMPILER +# define ZMQ_EXPORT __attribute__ ((visibility("default"))) +# else +# define ZMQ_EXPORT +# endif +#endif + +/******************************************************************************/ +/* 0MQ versioning support. */ +/******************************************************************************/ + +/* Version macros for compile-time API version detection */ +#define ZMQ_VERSION_MAJOR 3 +#define ZMQ_VERSION_MINOR 2 +#define ZMQ_VERSION_PATCH 5 + +#define ZMQ_MAKE_VERSION(major, minor, patch) \ + ((major) * 10000 + (minor) * 100 + (patch)) +#define ZMQ_VERSION \ + ZMQ_MAKE_VERSION(ZMQ_VERSION_MAJOR, ZMQ_VERSION_MINOR, ZMQ_VERSION_PATCH) + +/* Run-time API version detection */ +ZMQ_EXPORT void zmq_version (int *major, int *minor, int *patch); + +/******************************************************************************/ +/* 0MQ errors. */ +/******************************************************************************/ + +/* A number random enough not to collide with different errno ranges on */ +/* different OSes. The assumption is that error_t is at least 32-bit type. */ +#define ZMQ_HAUSNUMERO 156384712 + +/* On Windows platform some of the standard POSIX errnos are not defined. */ +#ifndef ENOTSUP +#define ENOTSUP (ZMQ_HAUSNUMERO + 1) +#endif +#ifndef EPROTONOSUPPORT +#define EPROTONOSUPPORT (ZMQ_HAUSNUMERO + 2) +#endif +#ifndef ENOBUFS +#define ENOBUFS (ZMQ_HAUSNUMERO + 3) +#endif +#ifndef ENETDOWN +#define ENETDOWN (ZMQ_HAUSNUMERO + 4) +#endif +#ifndef EADDRINUSE +#define EADDRINUSE (ZMQ_HAUSNUMERO + 5) +#endif +#ifndef EADDRNOTAVAIL +#define EADDRNOTAVAIL (ZMQ_HAUSNUMERO + 6) +#endif +#ifndef ECONNREFUSED +#define ECONNREFUSED (ZMQ_HAUSNUMERO + 7) +#endif +#ifndef EINPROGRESS +#define EINPROGRESS (ZMQ_HAUSNUMERO + 8) +#endif +#ifndef ENOTSOCK +#define ENOTSOCK (ZMQ_HAUSNUMERO + 9) +#endif +#ifndef EMSGSIZE +#define EMSGSIZE (ZMQ_HAUSNUMERO + 10) +#endif +#ifndef EAFNOSUPPORT +#define EAFNOSUPPORT (ZMQ_HAUSNUMERO + 11) +#endif +#ifndef ENETUNREACH +#define ENETUNREACH (ZMQ_HAUSNUMERO + 12) +#endif +#ifndef ECONNABORTED +#define ECONNABORTED (ZMQ_HAUSNUMERO + 13) +#endif +#ifndef ECONNRESET +#define ECONNRESET (ZMQ_HAUSNUMERO + 14) +#endif +#ifndef ENOTCONN +#define ENOTCONN (ZMQ_HAUSNUMERO + 15) +#endif +#ifndef ETIMEDOUT +#define ETIMEDOUT (ZMQ_HAUSNUMERO + 16) +#endif +#ifndef EHOSTUNREACH +#define EHOSTUNREACH (ZMQ_HAUSNUMERO + 17) +#endif +#ifndef ENETRESET +#define ENETRESET (ZMQ_HAUSNUMERO + 18) +#endif + +/* Native 0MQ error codes. */ +#define EFSM (ZMQ_HAUSNUMERO + 51) +#define ENOCOMPATPROTO (ZMQ_HAUSNUMERO + 52) +#define ETERM (ZMQ_HAUSNUMERO + 53) +#define EMTHREAD (ZMQ_HAUSNUMERO + 54) + +/* This function retrieves the errno as it is known to 0MQ library. The goal */ +/* of this function is to make the code 100% portable, including where 0MQ */ +/* compiled with certain CRT library (on Windows) is linked to an */ +/* application that uses different CRT library. */ +ZMQ_EXPORT int zmq_errno (void); + +/* Resolves system errors and 0MQ errors to human-readable string. */ +ZMQ_EXPORT const char *zmq_strerror (int errnum); + +/******************************************************************************/ +/* 0MQ infrastructure (a.k.a. context) initialisation & termination. */ +/******************************************************************************/ + +/* New API */ +/* Context options */ +#define ZMQ_IO_THREADS 1 +#define ZMQ_MAX_SOCKETS 2 + +/* Default for new contexts */ +#define ZMQ_IO_THREADS_DFLT 1 +#define ZMQ_MAX_SOCKETS_DFLT 1024 + +ZMQ_EXPORT void *zmq_ctx_new (void); +ZMQ_EXPORT int zmq_ctx_destroy (void *context); +ZMQ_EXPORT int zmq_ctx_set (void *context, int option, int optval); +ZMQ_EXPORT int zmq_ctx_get (void *context, int option); + +/* Old (legacy) API */ +ZMQ_EXPORT void *zmq_init (int io_threads); +ZMQ_EXPORT int zmq_term (void *context); + + +/******************************************************************************/ +/* 0MQ message definition. */ +/******************************************************************************/ + +typedef struct zmq_msg_t {unsigned char _ [32];} zmq_msg_t; + +typedef void (zmq_free_fn) (void *data, void *hint); + +ZMQ_EXPORT int zmq_msg_init (zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_init_size (zmq_msg_t *msg, size_t size); +ZMQ_EXPORT int zmq_msg_init_data (zmq_msg_t *msg, void *data, + size_t size, zmq_free_fn *ffn, void *hint); +ZMQ_EXPORT int zmq_msg_send (zmq_msg_t *msg, void *s, int flags); +ZMQ_EXPORT int zmq_msg_recv (zmq_msg_t *msg, void *s, int flags); +ZMQ_EXPORT int zmq_msg_close (zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src); +ZMQ_EXPORT int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src); +ZMQ_EXPORT void *zmq_msg_data (zmq_msg_t *msg); +ZMQ_EXPORT size_t zmq_msg_size (zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_more (zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_get (zmq_msg_t *msg, int option); +ZMQ_EXPORT int zmq_msg_set (zmq_msg_t *msg, int option, int optval); + + +/******************************************************************************/ +/* 0MQ socket definition. */ +/******************************************************************************/ + +/* Socket types. */ +#define ZMQ_PAIR 0 +#define ZMQ_PUB 1 +#define ZMQ_SUB 2 +#define ZMQ_REQ 3 +#define ZMQ_REP 4 +#define ZMQ_DEALER 5 +#define ZMQ_ROUTER 6 +#define ZMQ_PULL 7 +#define ZMQ_PUSH 8 +#define ZMQ_XPUB 9 +#define ZMQ_XSUB 10 + +/* Deprecated aliases */ +#define ZMQ_XREQ ZMQ_DEALER +#define ZMQ_XREP ZMQ_ROUTER + +/* Socket options. */ +#define ZMQ_AFFINITY 4 +#define ZMQ_IDENTITY 5 +#define ZMQ_SUBSCRIBE 6 +#define ZMQ_UNSUBSCRIBE 7 +#define ZMQ_RATE 8 +#define ZMQ_RECOVERY_IVL 9 +#define ZMQ_SNDBUF 11 +#define ZMQ_RCVBUF 12 +#define ZMQ_RCVMORE 13 +#define ZMQ_FD 14 +#define ZMQ_EVENTS 15 +#define ZMQ_TYPE 16 +#define ZMQ_LINGER 17 +#define ZMQ_RECONNECT_IVL 18 +#define ZMQ_BACKLOG 19 +#define ZMQ_RECONNECT_IVL_MAX 21 +#define ZMQ_MAXMSGSIZE 22 +#define ZMQ_SNDHWM 23 +#define ZMQ_RCVHWM 24 +#define ZMQ_MULTICAST_HOPS 25 +#define ZMQ_RCVTIMEO 27 +#define ZMQ_SNDTIMEO 28 +#define ZMQ_IPV4ONLY 31 +#define ZMQ_LAST_ENDPOINT 32 +#define ZMQ_ROUTER_MANDATORY 33 +#define ZMQ_TCP_KEEPALIVE 34 +#define ZMQ_TCP_KEEPALIVE_CNT 35 +#define ZMQ_TCP_KEEPALIVE_IDLE 36 +#define ZMQ_TCP_KEEPALIVE_INTVL 37 +#define ZMQ_TCP_ACCEPT_FILTER 38 +#define ZMQ_DELAY_ATTACH_ON_CONNECT 39 +#define ZMQ_XPUB_VERBOSE 40 + + +/* Message options */ +#define ZMQ_MORE 1 + +/* Send/recv options. */ +#define ZMQ_DONTWAIT 1 +#define ZMQ_SNDMORE 2 + +/* Deprecated aliases */ +#define ZMQ_NOBLOCK ZMQ_DONTWAIT +#define ZMQ_FAIL_UNROUTABLE ZMQ_ROUTER_MANDATORY +#define ZMQ_ROUTER_BEHAVIOR ZMQ_ROUTER_MANDATORY + +/******************************************************************************/ +/* 0MQ socket events and monitoring */ +/******************************************************************************/ + +/* Socket transport events (tcp and ipc only) */ +#define ZMQ_EVENT_CONNECTED 1 +#define ZMQ_EVENT_CONNECT_DELAYED 2 +#define ZMQ_EVENT_CONNECT_RETRIED 4 + +#define ZMQ_EVENT_LISTENING 8 +#define ZMQ_EVENT_BIND_FAILED 16 + +#define ZMQ_EVENT_ACCEPTED 32 +#define ZMQ_EVENT_ACCEPT_FAILED 64 + +#define ZMQ_EVENT_CLOSED 128 +#define ZMQ_EVENT_CLOSE_FAILED 256 +#define ZMQ_EVENT_DISCONNECTED 512 + +#define ZMQ_EVENT_ALL ( ZMQ_EVENT_CONNECTED | ZMQ_EVENT_CONNECT_DELAYED | \ + ZMQ_EVENT_CONNECT_RETRIED | ZMQ_EVENT_LISTENING | \ + ZMQ_EVENT_BIND_FAILED | ZMQ_EVENT_ACCEPTED | \ + ZMQ_EVENT_ACCEPT_FAILED | ZMQ_EVENT_CLOSED | \ + ZMQ_EVENT_CLOSE_FAILED | ZMQ_EVENT_DISCONNECTED ) + +/* Socket event data (union member per event) */ +typedef struct { + int event; + union { + struct { + char *addr; + int fd; + } connected; + struct { + char *addr; + int err; + } connect_delayed; + struct { + char *addr; + int interval; + } connect_retried; + struct { + char *addr; + int fd; + } listening; + struct { + char *addr; + int err; + } bind_failed; + struct { + char *addr; + int fd; + } accepted; + struct { + char *addr; + int err; + } accept_failed; + struct { + char *addr; + int fd; + } closed; + struct { + char *addr; + int err; + } close_failed; + struct { + char *addr; + int fd; + } disconnected; + } data; +} zmq_event_t; + +ZMQ_EXPORT void *zmq_socket (void *, int type); +ZMQ_EXPORT int zmq_close (void *s); +ZMQ_EXPORT int zmq_setsockopt (void *s, int option, const void *optval, + size_t optvallen); +ZMQ_EXPORT int zmq_getsockopt (void *s, int option, void *optval, + size_t *optvallen); +ZMQ_EXPORT int zmq_bind (void *s, const char *addr); +ZMQ_EXPORT int zmq_connect (void *s, const char *addr); +ZMQ_EXPORT int zmq_unbind (void *s, const char *addr); +ZMQ_EXPORT int zmq_disconnect (void *s, const char *addr); +ZMQ_EXPORT int zmq_send (void *s, const void *buf, size_t len, int flags); +ZMQ_EXPORT int zmq_recv (void *s, void *buf, size_t len, int flags); +ZMQ_EXPORT int zmq_socket_monitor (void *s, const char *addr, int events); + +ZMQ_EXPORT int zmq_sendmsg (void *s, zmq_msg_t *msg, int flags); +ZMQ_EXPORT int zmq_recvmsg (void *s, zmq_msg_t *msg, int flags); + +/* Experimental */ +struct iovec; + +ZMQ_EXPORT int zmq_sendiov (void *s, struct iovec *iov, size_t count, int flags); +ZMQ_EXPORT int zmq_recviov (void *s, struct iovec *iov, size_t *count, int flags); + +/******************************************************************************/ +/* I/O multiplexing. */ +/******************************************************************************/ + +#define ZMQ_POLLIN 1 +#define ZMQ_POLLOUT 2 +#define ZMQ_POLLERR 4 + +typedef struct +{ + void *socket; +#if defined _WIN32 + SOCKET fd; +#else + int fd; +#endif + short events; + short revents; +} zmq_pollitem_t; + +ZMQ_EXPORT int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout); + +/* Built-in message proxy (3-way) */ + +ZMQ_EXPORT int zmq_proxy (void *frontend, void *backend, void *capture); + +/* Deprecated aliases */ +#define ZMQ_STREAMER 1 +#define ZMQ_FORWARDER 2 +#define ZMQ_QUEUE 3 +/* Deprecated method */ +ZMQ_EXPORT int zmq_device (int type, void *frontend, void *backend); + +#undef ZMQ_EXPORT + +#ifdef __cplusplus +} +#endif + +#endif + diff --git a/zmq/3.2.5/Linux-x86_64/include/zmq_utils.h b/zmq/3.2.5/Linux-x86_64/include/zmq_utils.h new file mode 100755 index 0000000000000000000000000000000000000000..341d6399829e7255a6c1c0aa4707e9dbdb4953ed --- /dev/null +++ b/zmq/3.2.5/Linux-x86_64/include/zmq_utils.h @@ -0,0 +1,64 @@ +/* + Copyright (c) 2009-2011 250bpm s.r.o. + Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file + + This file is part of 0MQ. + + 0MQ is free software; you can redistribute it and/or modify it under + the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + 0MQ is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with this program. If not, see . +*/ + +#ifndef __ZMQ_UTILS_H_INCLUDED__ +#define __ZMQ_UTILS_H_INCLUDED__ + +#ifdef __cplusplus +extern "C" { +#endif + +/* Handle DSO symbol visibility */ +#if defined _WIN32 +# if defined DLL_EXPORT +# define ZMQ_EXPORT __declspec(dllexport) +# else +# define ZMQ_EXPORT __declspec(dllimport) +# endif +#else +# if defined __SUNPRO_C || defined __SUNPRO_CC +# define ZMQ_EXPORT __global +# elif (defined __GNUC__ && __GNUC__ >= 4) || defined __INTEL_COMPILER +# define ZMQ_EXPORT __attribute__ ((visibility("default"))) +# else +# define ZMQ_EXPORT +# endif +#endif + +/* Helper functions are used by perf tests so that they don't have to care */ +/* about minutiae of time-related functions on different OS platforms. */ + +/* Starts the stopwatch. Returns the handle to the watch. */ +ZMQ_EXPORT void *zmq_stopwatch_start (void); + +/* Stops the stopwatch. Returns the number of microseconds elapsed since */ +/* the stopwatch was started. */ +ZMQ_EXPORT unsigned long zmq_stopwatch_stop (void *watch_); + +/* Sleeps for specified number of seconds. */ +ZMQ_EXPORT void zmq_sleep (int seconds_); + +#undef ZMQ_EXPORT + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/zmq/3.2.5/Linux-x86_64/libzmq.so.3.0.0 b/zmq/3.2.5/Linux-x86_64/libzmq.so.3.0.0 new file mode 100755 index 0000000000000000000000000000000000000000..733b5ea357ccb01898fee174e11ceb7a632e6415 Binary files /dev/null and b/zmq/3.2.5/Linux-x86_64/libzmq.so.3.0.0 differ diff --git a/zmq/4.3.5/AIX-00FB437F4C00/include/zmq.h b/zmq/4.3.5/AIX-00FB437F4C00/include/zmq.h new file mode 100755 index 0000000000000000000000000000000000000000..b13edfd870a71e62eb344c7e6d892aa65dd52d49 --- /dev/null +++ b/zmq/4.3.5/AIX-00FB437F4C00/include/zmq.h @@ -0,0 +1,708 @@ +/* + Copyright (c) 2007-2016 Contributors as noted in the AUTHORS file + + This file is part of libzmq, the ZeroMQ core engine in C++. + + libzmq is free software; you can redistribute it and/or modify it under + the terms of the GNU Lesser General Public License (LGPL) as published + by the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + As a special exception, the Contributors give you permission to link + this library with independent modules to produce an executable, + regardless of the license terms of these independent modules, and to + copy and distribute the resulting executable under terms of your choice, + provided that you also meet, for each linked independent module, the + terms and conditions of the license of that module. An independent + module is a module which is not derived from or based on this library. + If you modify this library, you must extend this exception to your + version of the library. + + libzmq is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public + License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with this program. If not, see . + + ************************************************************************* + NOTE to contributors. This file comprises the principal public contract + for ZeroMQ API users. Any change to this file supplied in a stable + release SHOULD not break existing applications. + In practice this means that the value of constants must not change, and + that old values may not be reused for new constants. + ************************************************************************* +*/ + +#ifndef __ZMQ_H_INCLUDED__ +#define __ZMQ_H_INCLUDED__ + +/* Version macros for compile-time API version detection */ +#define ZMQ_VERSION_MAJOR 4 +#define ZMQ_VERSION_MINOR 2 +#define ZMQ_VERSION_PATCH 3 + +#define ZMQ_MAKE_VERSION(major, minor, patch) \ + ((major) * 10000 + (minor) * 100 + (patch)) +#define ZMQ_VERSION \ + ZMQ_MAKE_VERSION(ZMQ_VERSION_MAJOR, ZMQ_VERSION_MINOR, ZMQ_VERSION_PATCH) + +#ifdef __cplusplus +extern "C" { +#endif + +#if !defined _WIN32_WCE +#include +#endif +#include +#include +#if defined _WIN32 +// Set target version to Windows Server 2008, Windows Vista or higher. +// Windows XP (0x0501) is supported but without client & server socket types. +#ifndef _WIN32_WINNT +#define _WIN32_WINNT 0x0600 +#endif + +#ifdef __MINGW32__ +// Require Windows XP or higher with MinGW for getaddrinfo(). +#if(_WIN32_WINNT >= 0x0501) +#else +#error You need at least Windows XP target +#endif +#endif +#include +#endif + +/* Handle DSO symbol visibility */ +#if defined _WIN32 +# if defined ZMQ_STATIC +# define ZMQ_EXPORT +# elif defined DLL_EXPORT +# define ZMQ_EXPORT __declspec(dllexport) +# else +# define ZMQ_EXPORT __declspec(dllimport) +# endif +#else +# if defined __SUNPRO_C || defined __SUNPRO_CC +# define ZMQ_EXPORT __global +# elif (defined __GNUC__ && __GNUC__ >= 4) || defined __INTEL_COMPILER +# define ZMQ_EXPORT __attribute__ ((visibility("default"))) +# else +# define ZMQ_EXPORT +# endif +#endif + +/* Define integer types needed for event interface */ +#define ZMQ_DEFINED_STDINT 1 +#if defined ZMQ_HAVE_SOLARIS || defined ZMQ_HAVE_OPENVMS +# include +#elif defined _MSC_VER && _MSC_VER < 1600 +# ifndef int32_t + typedef __int32 int32_t; +# endif +# ifndef uint32_t + typedef unsigned __int32 uint32_t; +# endif +# ifndef uint16_t + typedef unsigned __int16 uint16_t; +# endif +# ifndef uint8_t + typedef unsigned __int8 uint8_t; +# endif +#else +# include +#endif + +// 32-bit AIX's pollfd struct members are called reqevents and rtnevents so it +// defines compatibility macros for them. Need to include that header first to +// stop build failures since zmq_pollset_t defines them as events and revents. +#ifdef ZMQ_HAVE_AIX + #include +#endif + + +/******************************************************************************/ +/* 0MQ errors. */ +/******************************************************************************/ + +/* A number random enough not to collide with different errno ranges on */ +/* different OSes. The assumption is that error_t is at least 32-bit type. */ +#define ZMQ_HAUSNUMERO 156384712 + +/* On Windows platform some of the standard POSIX errnos are not defined. */ +#ifndef ENOTSUP +#define ENOTSUP (ZMQ_HAUSNUMERO + 1) +#endif +#ifndef EPROTONOSUPPORT +#define EPROTONOSUPPORT (ZMQ_HAUSNUMERO + 2) +#endif +#ifndef ENOBUFS +#define ENOBUFS (ZMQ_HAUSNUMERO + 3) +#endif +#ifndef ENETDOWN +#define ENETDOWN (ZMQ_HAUSNUMERO + 4) +#endif +#ifndef EADDRINUSE +#define EADDRINUSE (ZMQ_HAUSNUMERO + 5) +#endif +#ifndef EADDRNOTAVAIL +#define EADDRNOTAVAIL (ZMQ_HAUSNUMERO + 6) +#endif +#ifndef ECONNREFUSED +#define ECONNREFUSED (ZMQ_HAUSNUMERO + 7) +#endif +#ifndef EINPROGRESS +#define EINPROGRESS (ZMQ_HAUSNUMERO + 8) +#endif +#ifndef ENOTSOCK +#define ENOTSOCK (ZMQ_HAUSNUMERO + 9) +#endif +#ifndef EMSGSIZE +#define EMSGSIZE (ZMQ_HAUSNUMERO + 10) +#endif +#ifndef EAFNOSUPPORT +#define EAFNOSUPPORT (ZMQ_HAUSNUMERO + 11) +#endif +#ifndef ENETUNREACH +#define ENETUNREACH (ZMQ_HAUSNUMERO + 12) +#endif +#ifndef ECONNABORTED +#define ECONNABORTED (ZMQ_HAUSNUMERO + 13) +#endif +#ifndef ECONNRESET +#define ECONNRESET (ZMQ_HAUSNUMERO + 14) +#endif +#ifndef ENOTCONN +#define ENOTCONN (ZMQ_HAUSNUMERO + 15) +#endif +#ifndef ETIMEDOUT +#define ETIMEDOUT (ZMQ_HAUSNUMERO + 16) +#endif +#ifndef EHOSTUNREACH +#define EHOSTUNREACH (ZMQ_HAUSNUMERO + 17) +#endif +#ifndef ENETRESET +#define ENETRESET (ZMQ_HAUSNUMERO + 18) +#endif + +/* Native 0MQ error codes. */ +#define EFSM (ZMQ_HAUSNUMERO + 51) +#define ENOCOMPATPROTO (ZMQ_HAUSNUMERO + 52) +#define ETERM (ZMQ_HAUSNUMERO + 53) +#define EMTHREAD (ZMQ_HAUSNUMERO + 54) + +/* This function retrieves the errno as it is known to 0MQ library. The goal */ +/* of this function is to make the code 100% portable, including where 0MQ */ +/* compiled with certain CRT library (on Windows) is linked to an */ +/* application that uses different CRT library. */ +ZMQ_EXPORT int zmq_errno (void); + +/* Resolves system errors and 0MQ errors to human-readable string. */ +ZMQ_EXPORT const char *zmq_strerror (int errnum); + +/* Run-time API version detection */ +ZMQ_EXPORT void zmq_version (int *major, int *minor, int *patch); + +/******************************************************************************/ +/* 0MQ infrastructure (a.k.a. context) initialisation & termination. */ +/******************************************************************************/ + +/* Context options */ +#define ZMQ_IO_THREADS 1 +#define ZMQ_MAX_SOCKETS 2 +#define ZMQ_SOCKET_LIMIT 3 +#define ZMQ_THREAD_PRIORITY 3 +#define ZMQ_THREAD_SCHED_POLICY 4 +#define ZMQ_MAX_MSGSZ 5 + +/* Default for new contexts */ +#define ZMQ_IO_THREADS_DFLT 1 +#define ZMQ_MAX_SOCKETS_DFLT 1023 +#define ZMQ_THREAD_PRIORITY_DFLT -1 +#define ZMQ_THREAD_SCHED_POLICY_DFLT -1 + +ZMQ_EXPORT void *zmq_ctx_new (void); +ZMQ_EXPORT int zmq_ctx_term (void *context); +ZMQ_EXPORT int zmq_ctx_shutdown (void *context); +ZMQ_EXPORT int zmq_ctx_set (void *context, int option, int optval); +ZMQ_EXPORT int zmq_ctx_get (void *context, int option); + +/* Old (legacy) API */ +ZMQ_EXPORT void *zmq_init (int io_threads); +ZMQ_EXPORT int zmq_term (void *context); +ZMQ_EXPORT int zmq_ctx_destroy (void *context); + + +/******************************************************************************/ +/* 0MQ message definition. */ +/******************************************************************************/ + +/* Some architectures, like sparc64 and some variants of aarch64, enforce pointer + * alignment and raise sigbus on violations. Make sure applications allocate + * zmq_msg_t on addresses aligned on a pointer-size boundary to avoid this issue. + */ +typedef struct zmq_msg_t { +#if defined (__GNUC__) || defined ( __INTEL_COMPILER) || \ + (defined (__SUNPRO_C) && __SUNPRO_C >= 0x590) || \ + (defined (__SUNPRO_CC) && __SUNPRO_CC >= 0x590) + unsigned char _ [64] __attribute__ ((aligned (sizeof (void *)))); +#elif defined (_MSC_VER) && (defined (_M_X64) || defined (_M_ARM64)) + __declspec (align (8)) unsigned char _ [64]; +#elif defined (_MSC_VER) && (defined (_M_IX86) || defined (_M_ARM_ARMV7VE)) + __declspec (align (4)) unsigned char _ [64]; +#else + unsigned char _ [64]; +#endif +} zmq_msg_t; + +typedef void (zmq_free_fn) (void *data, void *hint); + +ZMQ_EXPORT int zmq_msg_init (zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_init_size (zmq_msg_t *msg, size_t size); +ZMQ_EXPORT int zmq_msg_init_data (zmq_msg_t *msg, void *data, + size_t size, zmq_free_fn *ffn, void *hint); +ZMQ_EXPORT int zmq_msg_send (zmq_msg_t *msg, void *s, int flags); +ZMQ_EXPORT int zmq_msg_recv (zmq_msg_t *msg, void *s, int flags); +ZMQ_EXPORT int zmq_msg_close (zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_move (zmq_msg_t *dest, zmq_msg_t *src); +ZMQ_EXPORT int zmq_msg_copy (zmq_msg_t *dest, zmq_msg_t *src); +ZMQ_EXPORT void *zmq_msg_data (zmq_msg_t *msg); +ZMQ_EXPORT size_t zmq_msg_size (const zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_more (const zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_get (const zmq_msg_t *msg, int property); +ZMQ_EXPORT int zmq_msg_set (zmq_msg_t *msg, int property, int optval); +ZMQ_EXPORT const char *zmq_msg_gets (const zmq_msg_t *msg, const char *property); + +/******************************************************************************/ +/* 0MQ socket definition. */ +/******************************************************************************/ + +/* Socket types. */ +#define ZMQ_PAIR 0 +#define ZMQ_PUB 1 +#define ZMQ_SUB 2 +#define ZMQ_REQ 3 +#define ZMQ_REP 4 +#define ZMQ_DEALER 5 +#define ZMQ_ROUTER 6 +#define ZMQ_PULL 7 +#define ZMQ_PUSH 8 +#define ZMQ_XPUB 9 +#define ZMQ_XSUB 10 +#define ZMQ_STREAM 11 + +/* Deprecated aliases */ +#define ZMQ_XREQ ZMQ_DEALER +#define ZMQ_XREP ZMQ_ROUTER + +/* Socket options. */ +#define ZMQ_AFFINITY 4 +#define ZMQ_ROUTING_ID 5 +#define ZMQ_SUBSCRIBE 6 +#define ZMQ_UNSUBSCRIBE 7 +#define ZMQ_RATE 8 +#define ZMQ_RECOVERY_IVL 9 +#define ZMQ_SNDBUF 11 +#define ZMQ_RCVBUF 12 +#define ZMQ_RCVMORE 13 +#define ZMQ_FD 14 +#define ZMQ_EVENTS 15 +#define ZMQ_TYPE 16 +#define ZMQ_LINGER 17 +#define ZMQ_RECONNECT_IVL 18 +#define ZMQ_BACKLOG 19 +#define ZMQ_RECONNECT_IVL_MAX 21 +#define ZMQ_MAXMSGSIZE 22 +#define ZMQ_SNDHWM 23 +#define ZMQ_RCVHWM 24 +#define ZMQ_MULTICAST_HOPS 25 +#define ZMQ_RCVTIMEO 27 +#define ZMQ_SNDTIMEO 28 +#define ZMQ_LAST_ENDPOINT 32 +#define ZMQ_ROUTER_MANDATORY 33 +#define ZMQ_TCP_KEEPALIVE 34 +#define ZMQ_TCP_KEEPALIVE_CNT 35 +#define ZMQ_TCP_KEEPALIVE_IDLE 36 +#define ZMQ_TCP_KEEPALIVE_INTVL 37 +#define ZMQ_IMMEDIATE 39 +#define ZMQ_XPUB_VERBOSE 40 +#define ZMQ_ROUTER_RAW 41 +#define ZMQ_IPV6 42 +#define ZMQ_MECHANISM 43 +#define ZMQ_PLAIN_SERVER 44 +#define ZMQ_PLAIN_USERNAME 45 +#define ZMQ_PLAIN_PASSWORD 46 +#define ZMQ_CURVE_SERVER 47 +#define ZMQ_CURVE_PUBLICKEY 48 +#define ZMQ_CURVE_SECRETKEY 49 +#define ZMQ_CURVE_SERVERKEY 50 +#define ZMQ_PROBE_ROUTER 51 +#define ZMQ_REQ_CORRELATE 52 +#define ZMQ_REQ_RELAXED 53 +#define ZMQ_CONFLATE 54 +#define ZMQ_ZAP_DOMAIN 55 +#define ZMQ_ROUTER_HANDOVER 56 +#define ZMQ_TOS 57 +#define ZMQ_CONNECT_ROUTING_ID 61 +#define ZMQ_GSSAPI_SERVER 62 +#define ZMQ_GSSAPI_PRINCIPAL 63 +#define ZMQ_GSSAPI_SERVICE_PRINCIPAL 64 +#define ZMQ_GSSAPI_PLAINTEXT 65 +#define ZMQ_HANDSHAKE_IVL 66 +#define ZMQ_SOCKS_PROXY 68 +#define ZMQ_XPUB_NODROP 69 +#define ZMQ_BLOCKY 70 +#define ZMQ_XPUB_MANUAL 71 +#define ZMQ_XPUB_WELCOME_MSG 72 +#define ZMQ_STREAM_NOTIFY 73 +#define ZMQ_INVERT_MATCHING 74 +#define ZMQ_HEARTBEAT_IVL 75 +#define ZMQ_HEARTBEAT_TTL 76 +#define ZMQ_HEARTBEAT_TIMEOUT 77 +#define ZMQ_XPUB_VERBOSER 78 +#define ZMQ_CONNECT_TIMEOUT 79 +#define ZMQ_TCP_MAXRT 80 +#define ZMQ_THREAD_SAFE 81 +#define ZMQ_MULTICAST_MAXTPDU 84 +#define ZMQ_VMCI_BUFFER_SIZE 85 +#define ZMQ_VMCI_BUFFER_MIN_SIZE 86 +#define ZMQ_VMCI_BUFFER_MAX_SIZE 87 +#define ZMQ_VMCI_CONNECT_TIMEOUT 88 +#define ZMQ_USE_FD 89 + +/* Message options */ +#define ZMQ_MORE 1 +#define ZMQ_SHARED 3 + +/* Send/recv options. */ +#define ZMQ_DONTWAIT 1 +#define ZMQ_SNDMORE 2 + +/* Security mechanisms */ +#define ZMQ_NULL 0 +#define ZMQ_PLAIN 1 +#define ZMQ_CURVE 2 +#define ZMQ_GSSAPI 3 + +/* RADIO-DISH protocol */ +#define ZMQ_GROUP_MAX_LENGTH 15 + +/* Deprecated options and aliases */ +#define ZMQ_IDENTITY ZMQ_ROUTING_ID +#define ZMQ_CONNECT_RID ZMQ_CONNECT_ROUTING_ID +#define ZMQ_TCP_ACCEPT_FILTER 38 +#define ZMQ_IPC_FILTER_PID 58 +#define ZMQ_IPC_FILTER_UID 59 +#define ZMQ_IPC_FILTER_GID 60 +#define ZMQ_IPV4ONLY 31 +#define ZMQ_DELAY_ATTACH_ON_CONNECT ZMQ_IMMEDIATE +#define ZMQ_NOBLOCK ZMQ_DONTWAIT +#define ZMQ_FAIL_UNROUTABLE ZMQ_ROUTER_MANDATORY +#define ZMQ_ROUTER_BEHAVIOR ZMQ_ROUTER_MANDATORY + +/* Deprecated Message options */ +#define ZMQ_SRCFD 2 + +/******************************************************************************/ +/* 0MQ socket events and monitoring */ +/******************************************************************************/ + +/* Socket transport events (TCP, IPC and TIPC only) */ + +#define ZMQ_EVENT_CONNECTED 0x0001 +#define ZMQ_EVENT_CONNECT_DELAYED 0x0002 +#define ZMQ_EVENT_CONNECT_RETRIED 0x0004 +#define ZMQ_EVENT_LISTENING 0x0008 +#define ZMQ_EVENT_BIND_FAILED 0x0010 +#define ZMQ_EVENT_ACCEPTED 0x0020 +#define ZMQ_EVENT_ACCEPT_FAILED 0x0040 +#define ZMQ_EVENT_CLOSED 0x0080 +#define ZMQ_EVENT_CLOSE_FAILED 0x0100 +#define ZMQ_EVENT_DISCONNECTED 0x0200 +#define ZMQ_EVENT_MONITOR_STOPPED 0x0400 +#define ZMQ_EVENT_ALL 0xFFFF + +ZMQ_EXPORT void *zmq_socket (void *, int type); +ZMQ_EXPORT int zmq_close (void *s); +ZMQ_EXPORT int zmq_setsockopt (void *s, int option, const void *optval, + size_t optvallen); +ZMQ_EXPORT int zmq_getsockopt (void *s, int option, void *optval, + size_t *optvallen); +ZMQ_EXPORT int zmq_bind (void *s, const char *addr); +ZMQ_EXPORT int zmq_connect (void *s, const char *addr); +ZMQ_EXPORT int zmq_unbind (void *s, const char *addr); +ZMQ_EXPORT int zmq_disconnect (void *s, const char *addr); +ZMQ_EXPORT int zmq_send (void *s, const void *buf, size_t len, int flags); +ZMQ_EXPORT int zmq_send_const (void *s, const void *buf, size_t len, int flags); +ZMQ_EXPORT int zmq_recv (void *s, void *buf, size_t len, int flags); +ZMQ_EXPORT int zmq_socket_monitor (void *s, const char *addr, int events); + + +/******************************************************************************/ +/* Deprecated I/O multiplexing. Prefer using zmq_poller API */ +/******************************************************************************/ + +#define ZMQ_POLLIN 1 +#define ZMQ_POLLOUT 2 +#define ZMQ_POLLERR 4 +#define ZMQ_POLLPRI 8 + +typedef struct zmq_pollitem_t +{ + void *socket; +#if defined _WIN32 + SOCKET fd; +#else + int fd; +#endif + short events; + short revents; +} zmq_pollitem_t; + +#define ZMQ_POLLITEMS_DFLT 16 + +ZMQ_EXPORT int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout); + +/******************************************************************************/ +/* Message proxying */ +/******************************************************************************/ + +ZMQ_EXPORT int zmq_proxy (void *frontend, void *backend, void *capture); +ZMQ_EXPORT int zmq_proxy_steerable (void *frontend, void *backend, void *capture, void *control); + +/******************************************************************************/ +/* Probe library capabilities */ +/******************************************************************************/ + +#define ZMQ_HAS_CAPABILITIES 1 +ZMQ_EXPORT int zmq_has (const char *capability); + +/* Deprecated aliases */ +#define ZMQ_STREAMER 1 +#define ZMQ_FORWARDER 2 +#define ZMQ_QUEUE 3 + +/* Deprecated methods */ +ZMQ_EXPORT int zmq_device (int type, void *frontend, void *backend); +ZMQ_EXPORT int zmq_sendmsg (void *s, zmq_msg_t *msg, int flags); +ZMQ_EXPORT int zmq_recvmsg (void *s, zmq_msg_t *msg, int flags); +struct iovec; +ZMQ_EXPORT int zmq_sendiov (void *s, struct iovec *iov, size_t count, int flags); +ZMQ_EXPORT int zmq_recviov (void *s, struct iovec *iov, size_t *count, int flags); + +/******************************************************************************/ +/* Encryption functions */ +/******************************************************************************/ + +/* Encode data with Z85 encoding. Returns encoded data */ +ZMQ_EXPORT char *zmq_z85_encode (char *dest, const uint8_t *data, size_t size); + +/* Decode data with Z85 encoding. Returns decoded data */ +ZMQ_EXPORT uint8_t *zmq_z85_decode (uint8_t *dest, const char *string); + +/* Generate z85-encoded public and private keypair with tweetnacl/libsodium. */ +/* Returns 0 on success. */ +ZMQ_EXPORT int zmq_curve_keypair (char *z85_public_key, char *z85_secret_key); + +/* Derive the z85-encoded public key from the z85-encoded secret key. */ +/* Returns 0 on success. */ +ZMQ_EXPORT int zmq_curve_public (char *z85_public_key, const char *z85_secret_key); + +/******************************************************************************/ +/* Atomic utility methods */ +/******************************************************************************/ + +ZMQ_EXPORT void *zmq_atomic_counter_new (void); +ZMQ_EXPORT void zmq_atomic_counter_set (void *counter, int value); +ZMQ_EXPORT int zmq_atomic_counter_inc (void *counter); +ZMQ_EXPORT int zmq_atomic_counter_dec (void *counter); +ZMQ_EXPORT int zmq_atomic_counter_value (void *counter); +ZMQ_EXPORT void zmq_atomic_counter_destroy (void **counter_p); + + +/******************************************************************************/ +/* These functions are not documented by man pages -- use at your own risk. */ +/* If you need these to be part of the formal ZMQ API, then (a) write a man */ +/* page, and (b) write a test case in tests. */ +/******************************************************************************/ + +/* Helper functions are used by perf tests so that they don't have to care */ +/* about minutiae of time-related functions on different OS platforms. */ + +/* Starts the stopwatch. Returns the handle to the watch. */ +ZMQ_EXPORT void *zmq_stopwatch_start (void); + +/* Stops the stopwatch. Returns the number of microseconds elapsed since */ +/* the stopwatch was started. */ +ZMQ_EXPORT unsigned long zmq_stopwatch_stop (void *watch_); + +/* Sleeps for specified number of seconds. */ +ZMQ_EXPORT void zmq_sleep (int seconds_); + +typedef void (zmq_thread_fn) (void*); + +/* Start a thread. Returns a handle to the thread. */ +ZMQ_EXPORT void *zmq_threadstart (zmq_thread_fn* func, void* arg); + +/* Wait for thread to complete then free up resources. */ +ZMQ_EXPORT void zmq_threadclose (void* thread); + + +/******************************************************************************/ +/* These functions are DRAFT and disabled in stable releases, and subject to */ +/* change at ANY time until declared stable. */ +/******************************************************************************/ + +#ifdef ZMQ_BUILD_DRAFT_API + +/* DRAFT Socket types. */ +#define ZMQ_SERVER 12 +#define ZMQ_CLIENT 13 +#define ZMQ_RADIO 14 +#define ZMQ_DISH 15 +#define ZMQ_GATHER 16 +#define ZMQ_SCATTER 17 +#define ZMQ_DGRAM 18 + +/* DRAFT Socket options. */ +#define ZMQ_GSSAPI_PRINCIPAL_NAMETYPE 90 +#define ZMQ_GSSAPI_SERVICE_PRINCIPAL_NAMETYPE 91 +#define ZMQ_BINDTODEVICE 92 +#define ZMQ_ZAP_ENFORCE_DOMAIN 93 + +/* DRAFT 0MQ socket events and monitoring */ +/* Unspecified system errors during handshake. Event value is an errno. */ +#define ZMQ_EVENT_HANDSHAKE_FAILED_NO_DETAIL 0x0800 +/* Handshake complete successfully with successful authentication (if * + * enabled). Event value is unused. */ +#define ZMQ_EVENT_HANDSHAKE_SUCCEEDED 0x1000 +/* Protocol errors between ZMTP peers or between server and ZAP handler. * + * Event value is one of ZMQ_PROTOCOL_ERROR_* */ +#define ZMQ_EVENT_HANDSHAKE_FAILED_PROTOCOL 0x2000 +/* Failed authentication requests. Event value is the numeric ZAP status * + * code, i.e. 300, 400 or 500. */ +#define ZMQ_EVENT_HANDSHAKE_FAILED_AUTH 0x4000 + +#define ZMQ_PROTOCOL_ERROR_ZMTP_UNSPECIFIED 0x10000000 +#define ZMQ_PROTOCOL_ERROR_ZMTP_UNEXPECTED_COMMAND 0x10000001 +#define ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_SEQUENCE 0x10000002 +#define ZMQ_PROTOCOL_ERROR_ZMTP_KEY_EXCHANGE 0x10000003 +#define ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_UNSPECIFIED 0x10000011 +#define ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_MESSAGE 0x10000012 +#define ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_HELLO 0x10000013 +#define ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_INITIATE 0x10000014 +#define ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_ERROR 0x10000015 +#define ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_READY 0x10000016 +#define ZMQ_PROTOCOL_ERROR_ZMTP_MALFORMED_COMMAND_WELCOME 0x10000017 +#define ZMQ_PROTOCOL_ERROR_ZMTP_INVALID_METADATA 0x10000018 + +// the following two may be due to erroneous configuration of a peer +#define ZMQ_PROTOCOL_ERROR_ZMTP_CRYPTOGRAPHIC 0x11000001 +#define ZMQ_PROTOCOL_ERROR_ZMTP_MECHANISM_MISMATCH 0x11000002 + +#define ZMQ_PROTOCOL_ERROR_ZAP_UNSPECIFIED 0x20000000 +#define ZMQ_PROTOCOL_ERROR_ZAP_MALFORMED_REPLY 0x20000001 +#define ZMQ_PROTOCOL_ERROR_ZAP_BAD_REQUEST_ID 0x20000002 +#define ZMQ_PROTOCOL_ERROR_ZAP_BAD_VERSION 0x20000003 +#define ZMQ_PROTOCOL_ERROR_ZAP_INVALID_STATUS_CODE 0x20000004 +#define ZMQ_PROTOCOL_ERROR_ZAP_INVALID_METADATA 0x20000005 + +/* DRAFT Context options */ +#define ZMQ_MSG_T_SIZE 6 +#define ZMQ_THREAD_AFFINITY_CPU_ADD 7 +#define ZMQ_THREAD_AFFINITY_CPU_REMOVE 8 +#define ZMQ_THREAD_NAME_PREFIX 9 + +/* DRAFT Socket methods. */ +ZMQ_EXPORT int zmq_join (void *s, const char *group); +ZMQ_EXPORT int zmq_leave (void *s, const char *group); + +/* DRAFT Msg methods. */ +ZMQ_EXPORT int zmq_msg_set_routing_id(zmq_msg_t *msg, uint32_t routing_id); +ZMQ_EXPORT uint32_t zmq_msg_routing_id(zmq_msg_t *msg); +ZMQ_EXPORT int zmq_msg_set_group(zmq_msg_t *msg, const char *group); +ZMQ_EXPORT const char *zmq_msg_group(zmq_msg_t *msg); + +/* DRAFT Msg property names. */ +#define ZMQ_MSG_PROPERTY_ROUTING_ID "Routing-Id" +#define ZMQ_MSG_PROPERTY_SOCKET_TYPE "Socket-Type" +#define ZMQ_MSG_PROPERTY_USER_ID "User-Id" +#define ZMQ_MSG_PROPERTY_PEER_ADDRESS "Peer-Address" + +/******************************************************************************/ +/* Poller polling on sockets,fd and thread-safe sockets */ +/******************************************************************************/ + +#define ZMQ_HAVE_POLLER + +typedef struct zmq_poller_event_t +{ + void *socket; +#if defined _WIN32 + SOCKET fd; +#else + int fd; +#endif + void *user_data; + short events; +} zmq_poller_event_t; + +ZMQ_EXPORT void *zmq_poller_new (void); +ZMQ_EXPORT int zmq_poller_destroy (void **poller_p); +ZMQ_EXPORT int zmq_poller_add (void *poller, void *socket, void *user_data, short events); +ZMQ_EXPORT int zmq_poller_modify (void *poller, void *socket, short events); +ZMQ_EXPORT int zmq_poller_remove (void *poller, void *socket); +ZMQ_EXPORT int zmq_poller_wait (void *poller, zmq_poller_event_t *event, long timeout); +ZMQ_EXPORT int zmq_poller_wait_all (void *poller, zmq_poller_event_t *events, int n_events, long timeout); + +#if defined _WIN32 +ZMQ_EXPORT int zmq_poller_add_fd (void *poller, SOCKET fd, void *user_data, short events); +ZMQ_EXPORT int zmq_poller_modify_fd (void *poller, SOCKET fd, short events); +ZMQ_EXPORT int zmq_poller_remove_fd (void *poller, SOCKET fd); +#else +ZMQ_EXPORT int zmq_poller_add_fd (void *poller, int fd, void *user_data, short events); +ZMQ_EXPORT int zmq_poller_modify_fd (void *poller, int fd, short events); +ZMQ_EXPORT int zmq_poller_remove_fd (void *poller, int fd); +#endif + +ZMQ_EXPORT int zmq_socket_get_peer_state (void *socket, + const void *routing_id, + size_t routing_id_size); + +/******************************************************************************/ +/* Scheduling timers */ +/******************************************************************************/ + +#define ZMQ_HAVE_TIMERS + +typedef void (zmq_timer_fn)(int timer_id, void *arg); + +ZMQ_EXPORT void *zmq_timers_new (void); +ZMQ_EXPORT int zmq_timers_destroy (void **timers_p); +ZMQ_EXPORT int zmq_timers_add (void *timers, size_t interval, zmq_timer_fn handler, void *arg); +ZMQ_EXPORT int zmq_timers_cancel (void *timers, int timer_id); +ZMQ_EXPORT int zmq_timers_set_interval (void *timers, int timer_id, size_t interval); +ZMQ_EXPORT int zmq_timers_reset (void *timers, int timer_id); +ZMQ_EXPORT long zmq_timers_timeout (void *timers); +ZMQ_EXPORT int zmq_timers_execute (void *timers); + +/******************************************************************************/ +/* GSSAPI definitions */ +/******************************************************************************/ + +/* GSSAPI principal name types */ +#define ZMQ_GSSAPI_NT_HOSTBASED 0 +#define ZMQ_GSSAPI_NT_USER_NAME 1 +#define ZMQ_GSSAPI_NT_KRB5_PRINCIPAL 2 + +#endif // ZMQ_BUILD_DRAFT_API + + +#undef ZMQ_EXPORT + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/zmq/4.3.5/AIX-00FB437F4C00/include/zmq_utils.h b/zmq/4.3.5/AIX-00FB437F4C00/include/zmq_utils.h new file mode 100755 index 0000000000000000000000000000000000000000..75f8b32cf00916242525a0a7973b07225ed49af4 --- /dev/null +++ b/zmq/4.3.5/AIX-00FB437F4C00/include/zmq_utils.h @@ -0,0 +1,48 @@ +/* + Copyright (c) 2007-2016 Contributors as noted in the AUTHORS file + + This file is part of libzmq, the ZeroMQ core engine in C++. + + libzmq is free software; you can redistribute it and/or modify it under + the terms of the GNU Lesser General Public License (LGPL) as published + by the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + As a special exception, the Contributors give you permission to link + this library with independent modules to produce an executable, + regardless of the license terms of these independent modules, and to + copy and distribute the resulting executable under terms of your choice, + provided that you also meet, for each linked independent module, the + terms and conditions of the license of that module. An independent + module is a module which is not derived from or based on this library. + If you modify this library, you must extend this exception to your + version of the library. + + libzmq is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public + License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with this program. If not, see . +*/ + +/* This file is deprecated, and all its functionality provided by zmq.h */ +/* Note that -Wpedantic compilation requires GCC to avoid using its custom + extensions such as #warning, hence the trick below. Also, pragmas for + warnings or other messages are not standard, not portable, and not all + compilers even have an equivalent concept. + So in the worst case, this include file is treated as silently empty. */ + +#if defined(__clang__) || defined(__GNUC__) || defined(__GNUG__) || defined(_MSC_VER) +#if defined(__GNUC__) || defined(__GNUG__) +#pragma GCC diagnostic push +#pragma GCC diagnostic warning "-Wcpp" +#pragma GCC diagnostic ignored "-Werror" +#pragma GCC diagnostic ignored "-Wall" +#endif +#pragma message("Warning: zmq_utils.h is deprecated. All its functionality is provided by zmq.h.") +#if defined(__GNUC__) || defined(__GNUG__) +#pragma GCC diagnostic pop +#endif +#endif diff --git a/zmq/4.3.5/AIX-00FB437F4C00/libzmq.a b/zmq/4.3.5/AIX-00FB437F4C00/libzmq.a new file mode 100755 index 0000000000000000000000000000000000000000..52dc88f20c6b49db4d776923f2462832889870b4 Binary files /dev/null and b/zmq/4.3.5/AIX-00FB437F4C00/libzmq.a differ