Man page of tw_init(3)

tw_init - initialize a Textweiser object

 #include <tw.h>

 tw_errno_t tw_init(tw_t *tw, const tw_config_t *cfg);

tw_init() establishes a connection to a database and initializes a new Textweiser object.

tw (tw_t *)

Pointer to an uninitialized Textweiser object. If tw_init() succeeds, tw will be initialized and ready for use.

cfg (const tw_config_t *)

Pointer to a Textweiser configuration data structure containing all settings required to connect to the database.

Have a look at CONFIGURATION DATA STRUCTURE below for details.

tw_init() returns an error indicator (tw_errno_t). A return value of TW_OK indicates success, any other value discriminates the occurred error.

The function tw_strerror(3) can be used to obtain a natural language error message.

The configuration data structure tw_config_t comprises all settings that may be required to connect to a database. It has to be initialized using the TW_CONFIG_INITIALIZER macro and can be used afterwards. In order to suite the data structure to your needs, assign your configuration settings to the appropriate fields of the data structure:

host (char *)

Hostname of the database server to connect to. (Ignored if the SQLite version of Textweiser is used.)

user (char *)

Username that should be used to log in on the database server. (Ignored if the SQLite version of Textweiser is used.)

passwd (char *)

Password of the user to log in on the database server. (Ignored if the SQLite version of Textweiser is used.)

db_name (char *)

Name of the database that should be used by Textweiser (UTF-8 encoded).

NOTE: If the SQLite version of Textweiser is used, db_name has to be the path to a database file, not necessarily encoded in UTF-8.

port (unsigned int)

Port of the database server to use. (Ignored if the SQLite version of Textweiser is used.)

NOTE: If port is set to 0, Textweiser will assign the default port of the database.

instance (char *)

Name of the Microsoft SQL Server instance to use. (Ignored unless the Microsoft SQL Server version of Textweiser is used.)

encrypt (unsigned char)

Sets whether to request the database driver to use encryption and whether to trust presented server certificates. (Ignored if the SQLite version of Textweiser is used.)

The set of valid values comprises:

TW_ENCRYPT_OFF

Disable encryption.

TW_ENCRYPT_ON

Enable encryption.

In order to trust any certificate presented by the database server, which is i.e. required to use self-signed certificates, combine TW_ENCRYPT_ON with TW_ENCRYPT_TRUST_CERT using addition or bitwise OR. See EXAMPLE below.

EXAMPLE:

C/C++ #include <tw.h>

 int main(int argc, char **argv)
 {
     tw_config_t cfg = TW_CONFIG_INITIALIZER;

     cfg.db_name = "Example";
     cfg.user    = "Test";
     cfg.encrypt = TW_ENCRYPT_ON | TW_ENCRYPT_TRUST_CERT;

     /* ... */

     return 0;
 }

Besides manual initialization, tw_parse_config(3) may be used to automatically generate a configuration data structure from a configuration file.

o

You should assign TW_INITIALIZER to any tw_t variable on declaration in order to set its members to their default values.

o

If the Textweiser object is not needed anymore, tw_free(3) should be used to free any resources allocated by Textweiser and close the database connection.

o

Communication encryption is the task of the database driver. Textweiser merely instructs the driver to enable or disable encryption according to the passed options and checks whether the operation did succeed.

o

If encryption has been requested by setting cfg.encrypt to TW_ENCRYPT_ON (maybe combined with TW_ENCRYPT_TRUST_CERT), tw_init() will return an appropriate error unless the database driver is able to establish an encrypted connection to the database server.

C/C++ #include <stdio.h>
 #include <stdlib.h>

 #include <tw.h>

 int main(int argc, char *argv[])
 {
     tw_errno_t  rv  = TW_OK;
     tw_config_t cfg = TW_CONFIG_INITIALIZER;
     tw_t        tw  = TW_INITIALIZER;

     /* Initialize a Textweiser object using the SQLite
      * database backend. */
     cfg.db_name = "example.sqlt";

     rv = tw_init(&tw, &cfg);

     printf("tw_init() returned error code %d (%s)\n", rv,
            tw_strerror(rv));

     if (rv == TW_OK)
     {
         tw_free(&tw);
         return(EXIT_SUCCESS);
     }

     return(EXIT_FAILURE);
 }

tw_create_db(3), tw_free(3), tw_parse_config, tw_strerror(3)

Textweiser User Manual

http://www.lingua-systems.com/text-classifier/textweiser-library/

Copyright (c) 2010-2011 Lingua-Systems Software GmbH