jni/libzrtp/sources/zrtp/libzrtpcpp/zrtpCacheDbBackend.h

/*
  Copyright (C) 2006-2013 Werner Dittmann

  This program 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.

  This program 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 General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef _ZRTP_CACHE_DB_BACKEND_H_
#define _ZRTP_CACHE_DB_BACKEND_H_

#include <libzrtpcpp/ZIDRecordDb.h>

#if defined(__cplusplus)
extern "C"
{
#endif

#define DB_CACHE_ERR_BUFF_SIZE  1000

/**
 * Set of accessible operations of database ZRTP cache implementaion.
 *
 * The only public method of the database ZRTP implementation is
 * getDbCacheOps(...)  that fills in this call structure. This mechanism
 * decouples the database implementations from libzrtp and possible other
 * clients.
 *
 * Some implementation notes:
 * <ul>
 * <li> All data storage methods return 0 (zero) if the call was successful.
 * </li>

 * <li> The @c errString parameter points to a buffer of at least @c
 *      DB_CACHE_ERR_BUFF_SIZE character. In case of an error methods shall
 *      store detailed, human readable information in this buffer. Use @c
 *      snprintf or similar functions to format the data.  If this parameter
 *      is @c NULL then methods must not return an error string.
 *</li>
 * <li> The methods cast the @c void to the type they need. Be aware that the
 *      open functions requires a pointer to a pointer.
 * </li>
 * </ul>
 *
 *
 * 
 */
typedef struct {
    /**
     * @brief Open the cache.
     *
     * @param name String that identifies the database or data storage.
     *
     * @param pdb Pointer to an internal structure that the database
     *            implementation requires.
     *
     * @param errString Pointer to a character buffer, see implementation
     *                  notes above.
     */
    int (*openCache)(const char* name, void **pdb, char *errString);

    /**
     * Close the cache.
     *
     * @param db Pointer to an internal structure that the database
     *           implementation requires.
     */
    int (*closeCache)(void *db);

    /**
     * @brief Read a local ZID from the database.
     *
     * The cache database may implement methods to generate and store local
     * ZRTP identifiers (ZID) and optionally link them with account
     * information. The account information data is the key to the request
     * local ZID. If the application does not provide account information data
     * the method implmentation shall use a standard predfined string that
     * does not collide with usual account information.
     *
     * The SQLite backend uses the string @c "_STANDARD_" in this case and
     * sets a specific type field.
     * 
     * The first call to this method with a specific account information
     * generates a ZID, stores it in the database usind the account
     * information as key, and returns the ZID to the application. Any
     * subsequent call with the same account information return the same local
     * ZID.
     *
     * @param db Pointer to an internal structure that the database
     *           implementation requires.
     *
     * @param localZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                 uint8_t bytes. The method stores the local ZID in this
     *                 buffer.
     *
     * @param accountInfo Pointer to an account information string or @c NULL
     *                    if explicit account information is not required.
     *
     * @param errString Pointer to a character buffer, see implementation
     *                  notes above.
     */
    int (*readLocalZid)(void *db, uint8_t *localZid, const char *accountInfo, char *errString);

    /**
     * @brief Read a remote ZID data structure.
     *
     * The method uses @c remoteZid and @c localZid as keys to read the remote
     * ZID record.  If a record does not exist in the database the method
     * clears the @c flags field in the @c remoteZidRecord_t structure and
     * returns without error. The application must check the flags if the
     * method found a valid record.
     *
     * @param db Pointer to an internal structure that the database
     *           implementation requires.
     *
     * @param localZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                 uint8_t bytes. The buffer must contain the local ZID.
     *
     * @param remoteZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                  uint8_t bytes. The buffer must contain the remote ZID.
     *
     * @param remZid Pointer to the @c remoteZidRecord_t structure. The method
     *               fills this structure with data it read from the database.
     *
     * @param errString Pointer to a character buffer, see implementation
     *                  notes above.
     */
    int (*readRemoteZidRecord)(void *db, const uint8_t *remoteZid, const uint8_t *localZid, 
                               remoteZidRecord_t *remZid, char* errString);
    /**
     * @brief Update an existing remote ZID data structure.
     *
     * The method uses @c remoteZid and @c localZid as keys to update an
     * existing remote ZID record.
     *
     * @b NOTE: application must use this methods only if
     *          @c readRemoteZidRecord (see above) returned a @b valid record. If
     *          @c readRemoteZidRecord returned an invalid record then no such
     *          record exists in the database and the application must use the
     *          @c insertRemoteZidRecord (see below).
     *
     * @param db Pointer to an internal structure that the database
     *           implementation requires.
     *
     * @param localZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                 uint8_t bytes. The buffer must contain the local ZID.
     *
     * @param remoteZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                  uint8_t bytes. The buffer must contain the remote ZID.
     *
     * @param remZid Pointer to the @c remoteZidRecord_t structure. The method
     *               gets data from this structure and stores it in the
     *               database.
     *
     * @param errString Pointer to a character buffer, see implementation
     *                  notes above.
     */
    int (*updateRemoteZidRecord)(void *db, const uint8_t *remoteZid, const uint8_t *localZid, 
                                 const remoteZidRecord_t *remZid, char* errString);
    /**
     * @brief Insert a new remote ZID data structure.
     *
     * The method uses @c remoteZid and @c localZid as keys to insert a new
     * remote ZID record.
     *
     * @b NOTE: application must use this methods only if @c
     *          readRemoteZidRecord (see above) returned an @b invalid
     *          record. Refer to note.
     *
     * @param db Pointer to an internal structure that the database
     *           implementation requires.
     *
     * @param localZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                 uint8_t bytes. The buffer must contain the local ZID.
     *
     * @param remoteZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                  uint8_t bytes. The buffer must contain the remote ZID.
     *
     * @param remZid Pointer to the @c remoteZidRecord_t structure. The method
     *               gets data from this structure and stores it in the
     *               database.
     *
     * @param errString Pointer to a character buffer, see implementation
     *                  notes above.
     */
    int (*insertRemoteZidRecord)(void *db, const uint8_t *remoteZid, const uint8_t *localZid, 
                                 const remoteZidRecord_t *remZid, char* errString);

    /**
     * @brief Read a remote ZID name.
     *
     * The method uses @c remoteZid, @c localZid, and @c accountInfo as keys
     * to read the remote ZID name.  If a record does not exist in the database
     * the method clears the @c flags field in the @c zidNameRecord_t structure and
     * returns without error. The application must check the flags if the
     * method found a valid record.
     * 
     * @param db Pointer to an internal structure that the database
     *           implementation requires.
     *
     * @param localZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                 uint8_t bytes. The buffer must contain the local ZID.
     *
     * @param remoteZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                  uint8_t bytes. The buffer must contain the remote ZID.
     *
     * @param accountInfo Pointer to an account information string or @c NULL
     *                    if explicit account information is not required.
     *
     * @param zidName Pointer to the @c zidNameRecord_t structure. The method
     *                returns the data in this structure.
     *
     * @param errString Pointer to a character buffer, see implementation
     *                  notes above.
     */
    int (*readZidNameRecord)(void *vdb, const uint8_t *remoteZid, const uint8_t *localZid,
                             const char *accountInfo, zidNameRecord_t *zidName, char* errString);

    /**
     * @brief Update an existing remote ZID data structure.
     *
     * The method uses @c remoteZid and @c localZid as keys to update an
     * existing remote ZID record.
     *
     * @b NOTE: application must use this methods only if
     *          @c readZidName (see above) returned a @b valid record. If
     *          @c readZidName returned an invalid record then no such
     *          record exists in the database and the application must use the
     *          @c insertZidNameRecord (see below).
     *
     * @param db Pointer to an internal structure that the database
     *           implementation requires.
     *
     * @param localZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                 uint8_t bytes. The buffer must contain the local ZID.
     *
     * @param remoteZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                  uint8_t bytes. The buffer must contain the remote ZID.
     *
     * @param accountInfo Pointer to an account information string or @c NULL
     *                    if explicit account information is not required.
     *
     * @param zidName Pointer to the @c zidNameRecord_t structure. The method
     *               gets data from this structure and stores it in the
     *               database.
     *
     * @param errString Pointer to a character buffer, see implementation
     *                  notes above.
     */
    int (*updateZidNameRecord)(void *vdb, const uint8_t *remoteZid, const uint8_t *localZid,
                               const char *accountInfo, zidNameRecord_t *zidName, char* errString);

    /**
     * @brief Insert a new ZID name record.
     *
     * The method uses @c remoteZid, @c localZid, and @c accountInfo as keys to
     * insert a new ZID name record.
     *
     * @b NOTE: application must use this methods only if @c readZidName
     *         (see above) returned an @b invalid record.
     *
     * @param db Pointer to an internal structure that the database
     *           implementation requires.
     *
     * @param localZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                 uint8_t bytes. The buffer must contain the local ZID.
     *
     * @param remoteZid Pointer to a buffer of at least @c IDENTIFIER_LEN @c
     *                  uint8_t bytes. The buffer must contain the remote ZID.
     *
     * @param accountInfo Pointer to an account information string or @c NULL
     *                    if explicit account information is not required.
     *
     * @param zidName Pointer to the @c zidNameRecord_t structure. The method
     *               gets data from this structure and stores it in the
     *               database.
     *
     * @param errString Pointer to a character buffer, see implementation
     *                  notes above.
     */
    int (*insertZidNameRecord)(void *vdb, const uint8_t *remoteZid, const uint8_t *localZid,
                               const char *accountInfo, zidNameRecord_t *zidName, char* errString);


    /**
     * @brief Clean the cache.
     * 
     * The function drops and re-creates all tables in the database. This removes all stored
     * data. The application must not call this while a ZRTP call is active. Also the application
     * <b>must</b> get the local ZID again.
     *
     * @param db Pointer to an internal structure that the database
     *           implementation requires.
     *
     * @param errString Pointer to a character buffer, see implementation
     *                  notes above.
     */
    int (*cleanCache)(void *db, char* errString);
} dbCacheOps_t;

void getDbCacheOps(dbCacheOps_t *ops);


#if defined(__cplusplus)
}
#endif

#endif /* _ZRTP_CACHE_DB_BACKEND_H_*/