Structs
=======

.. c:type:: ms3_st

   An internal struct which contains authentication information

.. c:type:: ms3_list_st

   A linked-list struct which contains a list of files/keys and information about them

   .. c:member:: char *key

      The key/filename for the object

   .. c:member:: size_t length

      The data size for the object

   .. c:member:: time_t created

      The created / updated timestamp for the object

   .. c:member:: struct ms3_list_st *next

      A pointer to the next struct in the list

.. c:type:: ms3_status_st

   An struct which contains the status of an object

   .. c:member:: size_t length

      The data size for the object

   .. c:member:: time_t created

      The created / updated timestamp for the object

Constants
=========

.. c:type:: ms3_set_option_t

   Options to use for :c:func:`ms3_set_option`. Possible values:

   * ``MS3_OPT_USE_HTTP`` - Use ``http://`` instead of ``https://``. The ``value`` parameter of :c:func:`ms3_set_option` is unused and each call to this toggles the flag (HTTPS is used by default)
   * ``MS3_OPT_DISABLE_SSL_VERIFY`` - Disable SSL verification. The ``value`` parameter of :c:func:`ms3_set_option` is unused and each call to this toggles the flag (SSL verification is on by default)
   * ``MS3_OPT_BUFFER_CHUNK_SIZE`` - Set the chunk size in bytes for the receive buffer. Default is 1MB. If you are receiving a large file a realloc will have to happen every time the buffer is full. For performance reasons you may want to increase the size of this buffer to reduce the reallocs and associated memory copies. The ``value`` parameter of :c:func:`ms3_set_option` should be a pointer to a :c:type:`size_t` greater than 1.
   * ``MS3_OPT_FORCE_LIST_VERSION`` - An internal option for the regression suite only. The ``value`` parameter of :c:func:`ms3_set_option` should be a pointer to a :c:type:`uint8_t` of value ``1`` or ``2``
   * ``MS3_OPT_FORCE_PROTOCOL_VERSION`` - Set to 1 to force talking to the S3 server using version 1 of the List Bucket API, this is for S3 compatible servers. Set to 2 to force talking to the S3 server version 2 of the List Bucket API. This is for use when the autodetect bsaed on providing a base_domain does the wrong thing. The ``value`` parameter of :c:func:`ms3_set_option` should be a pointer to a :c:type:`uint8_t` of value ``1`` or ``2``
   * ``MS3_OPT_READ_CB`` - Custom read callback for :c:func:`ms3_get`. The ``value`` parameter of :c:func:`ms3_set_option` should be a :c:type:`ms3_read_callback` function.
   * ``MS3_OPT_USER_DATA`` - User data for the custom read callback. The ``value`` parameter of :c:func:`ms3_set_option` is the pointer that will be passed as the ``userdata`` argument of the callback.
   * ``MS3_OPT_CONNECT_TIMEOUT`` - Sets the maximum time in seconds for the connection phase to take. This timeout only limits the connection phase, it has no impact once the connection is established. The ``value`` parameter of :c:func:`ms3_set_option` should be a pointer to a ``float`` of value between ``0`` and ``4294966``. ``0`` is the default value indicating that the default libcurl timeout will be used.
   * ``MS3_OPT_TIMEOUT`` - Sets the maximum time in seconds for the entire transfer operation to take. The ``value`` parameter of :c:func:`ms3_set_option` should be a pointer to a ``float`` of value between ``0`` and ``4294966``. ``0`` is the default value indicating that there is no timeout at all.

Callbacks
=========

.. c:type:: ms3_read_callback

   The callback function for ``MS3_OPT_READ_CB``. The function and the user data
   set with ``MS3_OPT_USER_DATA`` are passed to Curl. For more information, refer
   to `CURLOPT_WRITE_FUNCTION <https://curl.se/libcurl/c/CURLOPT_WRITEFUNCTION.html>`_.

Built-In Types
==============

.. c:type:: NULL

   A null pointer as defined in the standard header ``string.h``.

.. c:type:: uint8_t

   An unsigned single byte character as defined in the standard header ``stdint.h``

.. c:type:: size_t

   The unsigned integer type of the result of ``sizeof``.

.. c:type:: time_t

   Real arithmetic type capable of representing times as deinfined in the standard header ``time.h``