クライアントライブラリ
3
milter managerライブラリ

# クライアントライブラリ

milterを実装するためのクライアントライブラリ。

## 概要

    #define             MILTER_CLIENT_ERROR
    enum                MilterClientError;
                        MilterClient;
    GQuark              milter_client_error_quark           (void);
    MilterClient *      milter_client_new                   (void);
    gchar *             milter_client_get_default_connection_spec
                                                            (MilterClient *client);
    gboolean            milter_client_set_connection_spec   (MilterClient *client,
                                                             const gchar *spec,
                                                             GError **error);
    GIOChannel *        milter_client_get_listen_channel    (MilterClient *client);
    void                milter_client_set_listen_channel    (MilterClient *client,
                                                             GIOChannel *channel);
    void                milter_client_set_listen_backlog    (MilterClient *client,
                                                             gint backlog);
    gboolean            milter_client_is_remove_unix_socket_on_create
                                                            (MilterClient *client);
    void                milter_client_set_remove_unix_socket_on_create
                                                            (MilterClient *client,
                                                             gboolean remove);
    void                milter_client_set_timeout           (MilterClient *client,
                                                             guint timeout);
    guint               milter_client_get_unix_socket_mode  (MilterClient *client);
    guint               milter_client_get_default_unix_socket_mode
                                                            (MilterClient *client);
    void                milter_client_set_default_unix_socket_mode
                                                            (MilterClient *client,
                                                             guint mode);
    const gchar *       milter_client_get_unix_socket_group (MilterClient *client);
    const gchar *       milter_client_get_default_unix_socket_group
                                                            (MilterClient *client);
    void                milter_client_set_default_unix_socket_group
                                                            (MilterClient *client,
                                                             const gchar *group);
    gboolean            milter_client_is_remove_unix_socket_on_close
                                                            (MilterClient *client);
    gboolean            milter_client_get_default_remove_unix_socket_on_close
                                                            (MilterClient *client);
    void                milter_client_set_default_remove_unix_socket_on_close
                                                            (MilterClient *client,
                                                             gboolean remove);
    gboolean            milter_client_main                  (MilterClient *client);
    void                milter_client_shutdown              (MilterClient *client);

## オブジェクト階層

      GObject
       +----MilterClient

## 実装されたインターフェイス

MilterClientはMilterErrorEmittableを実装しています。

## プロパティ

      "connection-spec"          gchar*                : Read
      "custom-fork"              gpointer              : Read / Write
      "default-packet-buffer-size" guint                 : Read / Write
      "event-loop"               MilterEventLoop*      : Read
      "event-loop-backend"       MilterClientEventLoopBackend  : Read / Write
      "maintenance-interval"     guint                 : Read / Write
      "max-pending-finished-sessions" guint                 : Read / Write
      "n-workers"                guint                 : Read / Write
      "pid-file"                 gchar*                : Read / Write
      "remove-pid-file-on-exit"  gboolean              : Read / Write
      "run-as-daemon"            gchar*                : Read / Write
      "start-syslog"             gboolean              : Write
      "syslog-facility"          gchar*                : Read / Write
      "syslog-identify"          gchar*                : Read / Write
      "worker-id"                guint                 : Read

## シグナル

      "connection-established"                         : Run Last
      "event-loop-created"                             : Run Last
      "listen-started"                                 : Run Last
      "maintain"                                       : Run Last
      "sessions-finished"                              : Run Last

## 説明

milter-clientライブラリはクライアント側のすべてのmilterプロトコルを処理する機能を提供します。「クライアント側」というのは「milter側」ということで、「MTA側」ではありません。

milter-clientライブラリでの主要なクラスは`MilterClient`と`MilterClientContext`です。`MilterClient`はMTAからの複数の接続を受け付け、各接続は`MilterClientContext`が処理します。

### 使用法概観

メインループに入る前に、接続指定をし、"connection-established"シグナルに接続します。

接続指定はMTAが`MilterClient`に接続するためのエントリポイントです。接続指定は「プロトコル:情報」という形式になっています。IPv4ソケットでは「inet:ポート番号」、「inet:ポート番号&commat;ホスト名」、「inet:ポート番号&commat;[IPv4アドレス]」が正しい形式です。IPv6ソケットでは、「inet6:ポート番号」、「inet6:ポート番号&commat;ホスト名」、「inet6:ポート番号&commat;[IPv6アドレス]」が正しい形式です。UNIXドメインソケットでは「unix:パス」が正しい形式です。

`MilterClient`は"connection-established"シグナルを発行します。`MilterClientContext`のセットアップはこのシグナルの中で行います。多くの場合、渡された`MilterClientContext`にコールバックを接続します。利用可能なシグナルは`MilterClientContext`を見てください。

`milter_client_main()`はメインループ関数です。`MilterClient`の準備が終わったらメインループには行ってください。

milter-clientライブラリを使った例です。tool/milter-test-client.cも見てください。milter-test-client.cはmilter-clientライブラリを使ったmilterの実装例です。

    #include <stdlib.h>
    #include <milter/client.h>

    static void
    cb_connection_established (MilterClient *client,
                               MilterClientContext *context,
                               gpointer user_data)
    {
       connect_to_your_interesting_signals(client, context, user_data);
    }

    int
    main (int argc, char **argv)
    {
        gboolean success;
        const gchar spec[] = "inet:10025@localhost";
        MilterClient *client;
        GError *error = NULL;

        milter_init();
        milter_client_init();

        client = milter_client_new();
        if (!milter_client_set_connection_spec(client, spec, &error)) {
            g_print("%s\n", error->message);
            g_error_free(error);
            return EXIT_FAILURE;
        }
        g_signal_connect(client, "connection-established",
                         G_CALLBACK(cb_connection_established), NULL);
        milter_client_run(client);

        milter_client_quit();
        milter_quit();

        return success ? EXIT_SUCCESS : EXIT_FAILURE;
    }

### 処理モデル

Sendmailが提供するlibmilterは各接続毎にスレッドを生成するモデルです。しかし、milter-clientライブラリはこのモデルを使いません。milter-clientライブラリは2つのスレッドを使います。1つのスレッドは`MilterClient`用のスレッドで、もう1つのスレッドは`MilterClientContext`用のスレッドです。1つ目のスレッドでは`MilterClient`がMTAからの接続を受け付けて、それを割り振るだけです。`MilterClientContext`GMainLoop

libmilterのモデルは接続を受け付けるためにmilter-clientライブラリのモデルよりも多くコストがかかります。これは、libmilterのモデルがスレッドを生成するのに対して、milter-clientライブラリは単に`MilterClientContext`オブジェクトを生成するだけだからです。ただし、多くの場合、この違いはボトルネックとはなりません。:-|

## 詳細

### MILTER_CLIENT_ERROR

    #define MILTER_CLIENT_ERROR           (milter_client_error_quark())

MilterClientのエラー用のGErrorクォークを取得するために使われます。

### enum MilterClientError

    typedef enum {
        MILTER_CLIENT_ERROR_RUNNING,
        MILTER_CLIENT_ERROR_UNIX_SOCKET,
        MILTER_CLIENT_ERROR_IO_ERROR,
        MILTER_CLIENT_ERROR_THREAD,
        MILTER_CLIENT_ERROR_PASSWORD_ENTRY,
        MILTER_CLIENT_ERROR_GROUP_ENTRY,
        MILTER_CLIENT_ERROR_DROP_PRIVILEGE,
        MILTER_CLIENT_ERROR_DETACH_IO,
        MILTER_CLIENT_ERROR_DAEMONIZE,
        MILTER_CLIENT_ERROR_NOT_LISTENED_YET,
        MILTER_CLIENT_ERROR_PROCESS,
        MILTER_CLIENT_ERROR_PID_FILE
    } MilterClientError;

`MilterClient`の関数呼び出し中に発生するエラーを識別します。

`MILTER_CLIENT_ERROR_RUNNING`

  メインループがすでに回っていることを示します。

`MILTER_CLIENT_ERROR_UNIX_SOCKET`

  UNIXドメインソケット関連のエラーであることを示します。

`MILTER_CLIENT_ERROR_IO_ERROR`

  IO関連のエラーであることを示します。

`MILTER_CLIENT_ERROR_THREAD`

`MILTER_CLIENT_ERROR_PASSWORD_ENTRY`

`MILTER_CLIENT_ERROR_GROUP_ENTRY`

`MILTER_CLIENT_ERROR_DROP_PRIVILEGE`

`MILTER_CLIENT_ERROR_DETACH_IO`

`MILTER_CLIENT_ERROR_DAEMONIZE`

`MILTER_CLIENT_ERROR_NOT_LISTENED_YET`

`MILTER_CLIENT_ERROR_PROCESS`

`MILTER_CLIENT_ERROR_PID_FILE`

### MilterClient

    typedef struct _MilterClient MilterClient;

`MilterClient`は前面にでるオブジェクトです。このオブジェクトがMTAからの接続を受け付けて、各コンテキストに割り振ります。

### milter_client_error_quark ()

    GQuark              milter_client_error_quark           (void);

### milter_client_new ()

    MilterClient *      milter_client_new                   (void);

新しいクライアントを生成します。

返値 :

  新しい`MilterClient`オブジェクト。

### milter_client_get_default_connection_spec ()

    gchar *             milter_client_get_default_connection_spec
                                                            (MilterClient *client);

既定の接続指定を取得します。必要がなくなったら、既定の接続指定を開放してください。

`client` :

  `MilterClient`。

返値 :

  既定の接続指定のコピー。

### milter_client_set_connection_spec ()

    gboolean            milter_client_set_connection_spec   (MilterClient *client,
                                                             const gchar *spec,
                                                             GError **error);

接続指定を設定します。`spec`が不正な形式で、`error`が`NULL`でない場合は、エラーの詳細は`error`に設定されます。

`client` :

  `MilterClient`。

`spec` :

  inet:10025のような接続指定。

`error` :

  エラーを受け取る場所のアドレス、または`NULL`。

返値 :

  成功時は`TRUE`。

### milter_client_get_listen_channel ()

    GIOChannel *        milter_client_get_listen_channel    (MilterClient *client);

接続待ち用のチャンネルを取得します。

`client` :

  `MilterClient`。

返値 :

  接続待ち用チャンネル。

### milter_client_set_listen_channel ()

    void                milter_client_set_listen_channel    (MilterClient *client,
                                                             GIOChannel *channel);

接続待ち用チャンネルを設定します。

`client` :

  `MilterClient`。

`channel` :

  接続待ち用のチャンネル。

### milter_client_set_listen_backlog ()

    void                milter_client_set_listen_backlog    (MilterClient *client,
                                                             gint backlog);

listen(2)用のバックログを設定します。

`client` :

  `MilterClient`。

`backlog` :

  listen(2)用のバックログ。

### milter_client_is_remove_unix_socket_on_create ()

    gboolean            milter_client_is_remove_unix_socket_on_create
                                                            (MilterClient *client);

新しいUNIXドメインソケットを作成する前に既存のUNIXドメインソケットを削除するかどうかを取得します。

`client` :

  `MilterClient`。

返値 :

  作成時に既存のUNIXドメインソケットを削除する場合は`TRUE`、そうでない場合は`FALSE`。

### milter_client_set_remove_unix_socket_on_create ()

    void                milter_client_set_remove_unix_socket_on_create
                                                            (MilterClient *client,
                                                             gboolean remove);

新しいUNIXドメインソケットを作成する前に既存のUNIXドメインソケットを削除するかどうかを設定します。

`client` :

  `MilterClient`。

`remove` :

  新しいUNIXドメインソケットを作成する前に既存のUNIXドメインソケットを削除するなら`TRUE`。

### milter_client_set_timeout ()

    void                milter_client_set_timeout           (MilterClient *client,
                                                             guint timeout);

接続が確立した`MilterClientContext`に設定するタイムアウト値を設定します。

`client` :

  `MilterClient`。

`timeout` :

  秒単位でのタイムアウト。

### milter_client_get_unix_socket_mode ()

    guint               milter_client_get_unix_socket_mode  (MilterClient *client);

UNIXドメインソケットのモードを取得します。

`client` :

  `MilterClient`。

返値 :

  UNIXドメインソケットのモード。

### milter_client_get_default_unix_socket_mode ()

    guint               milter_client_get_default_unix_socket_mode
                                                            (MilterClient *client);

既定のUNIXドメインソケットのモードを取得します。

`client` :

  `MilterClient`。

返値 :

  既定のUNIXドメインソケットのモード。

### milter_client_set_default_unix_socket_mode ()

    void                milter_client_set_default_unix_socket_mode
                                                            (MilterClient *client,
                                                             guint mode);

既定のUNIXドメインソケットモードを設定します。

`client` :

  `MilterClient`。

`mode` :

  UNIXドメインソケットのモード。

### milter_client_get_unix_socket_group ()

    const gchar *       milter_client_get_unix_socket_group (MilterClient *client);

UNIXドメインソケットのグループを設定します。

`client` :

  `MilterClient`。

返値 :

  UNIXドメインソケットのグループ名。

### milter_client_get_default_unix_socket_group ()

    const gchar *       milter_client_get_default_unix_socket_group
                                                            (MilterClient *client);

既定のUNIXドメインソケットグループを取得します。

`client` :

  `MilterClient`。

返値 :

  既定のUNIXドメインソケットグループ名。

### milter_client_set_default_unix_socket_group ()

    void                milter_client_set_default_unix_socket_group
                                                            (MilterClient *client,
                                                             const gchar *group);

既定のUNIXドメインソケットグループを設定します。

`client` :

  `MilterClient`。

`group` :

  グループ名。

### milter_client_is_remove_unix_socket_on_close ()

    gboolean            milter_client_is_remove_unix_socket_on_close
                                                            (MilterClient *client);

UNIXドメインソケットを閉じた後に削除するかどうかを取得します。

`client` :

  `MilterClient`。

返値 :

  UNIXドメインソケットを閉じたときに削除するなら`TRUE`、そうでなければ`FALSE`。

### milter_client_get_default_remove_unix_socket_on_close ()

    gboolean            milter_client_get_default_remove_unix_socket_on_close
                                                            (MilterClient *client);

ソケットを閉じた後にUNIXドメインソケットを削除するかどうかの既定の値を取得します。

`client` :

  `MilterClient`。

返値 :

  UNIXドメインソケットを閉じたときに削除するなら`TRUE`、そうでなければ`FALSE`。

### milter_client_set_default_remove_unix_socket_on_close ()

    void                milter_client_set_default_remove_unix_socket_on_close
                                                            (MilterClient *client,
                                                             gboolean remove);

ソケットを閉じた後にUNIXドメインソケットを削除するかどうかの既定の値を取得します。

`client` :

  `MilterClient`。

`remove` :

  ソケットを閉じた後にUNIXドメインソケットを削除するなら`TRUE`。

### milter_client_main ()

    gboolean            milter_client_main                  (MilterClient *client);

`milter_client_main` has been deprecated since version 1.6.2 and should not be used in newly-written code. Use `milter_client_run()` instead.

メインループを実行します。

`client` :

  `MilterClient`。

返値 :

  `TRUE` if main loop is quitted successfully, `FALSE` otherwise.

### milter_client_shutdown ()

    void                milter_client_shutdown              (MilterClient *client);

メインループを終了します。

`client` :

  `MilterClient`。

## プロパティ詳細

### `"connection-spec"`プロパティ

      "connection-spec"          gchar*                : Read

クライアントの接続指定。

デフォルト値: NULL

### `"custom-fork`プロパティ

      "custom-fork"              gpointer              : Read / Write

The custom fork.

### `"default-packet-buffer-size"`プロパティ

      "default-packet-buffer-size" guint                 : Read / Write

The default packet buffer size of each client context of the client.

デフォルト値: 0

### `"event-loop"`プロパティ

      "event-loop"               MilterEventLoop*      : Read

クライアントのイベントループ。

### `"event-loop-backend"`プロパティ

      "event-loop-backend"       MilterClientEventLoopBackend  : Read / Write

クライアントのイベントループバックエンド。

Default value: MILTER_CLIENT_EVENT_LOOP_BACKEND_DEFAULT

### `"maintenance-interval"`プロパティ

      "maintenance-interval"     guint                 : Read / Write

Maintenance interval of the client. each 'maintenance-interval' sessions finished 'maintenance' signal is emitted. 0 means 'disabled'.

デフォルト値: 0

### The `"max-pending-finished-sessions"` property

      "max-pending-finished-sessions" guint                 : Read / Write

The maximum number of pending finished sessions of the client.

デフォルト値: 0

### `"n-workers"`プロパティ

      "n-workers"                guint                 : Read / Write

The Number of worker processes of the client.

Allowed values: <= 1000

デフォルト値: 0

### `"pid-file"`プロパティ

      "pid-file"                 gchar*                : Read / Write

クライアントのPIDファイル。

デフォルト値: NULL

### `"remove-pid-file-on-exit"`プロパティ

      "remove-pid-file-on-exit"  gboolean              : Read / Write

Whether removing PID file of the client on exist.

デフォルト値: TRUE

### `"run-as-daemon"`プロパティ

      "run-as-daemon"            gchar*                : Read / Write

Whether running the client as a daemon or not.

デフォルト値: NULL

### The `"start-syslog"` property

      "start-syslog"             gboolean              : Write

Start syslog for the client.

Default value: FALSE

### `"syslog-facility"`プロパティ

      "syslog-facility"          gchar*                : Read / Write

クライアントのsyslogファシリティ名。

デフォルト値: NULL

### `"syslog-identify"`プロパティ

      "syslog-identify"          gchar*                : Read / Write

Syslog identify of the client.

デフォルト値: NULL

### `"worker-id"`プロパティ

      "worker-id"                guint                 : Read

クライアントのワーカープロセスID。

Allowed values: <= 1000

デフォルト値: 0

## シグナル詳細

### `"connection-established"`シグナル

    void                user_function                      (MilterClient        *milterclient,
                                                            MilterClientContext *arg1,
                                                            gpointer             user_data)         : Run Last

`milterclient` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.

### `"event-loop-created"`シグナル

    void                user_function                      (MilterClient    *milterclient,
                                                            MilterEventLoop *arg1,
                                                            gpointer         user_data)         : Run Last

`milterclient` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.

### `"listen-started"`シグナル

    void                user_function                      (MilterClient *milterclient,
                                                            gpointer      arg1,
                                                            guint         arg2,
                                                            gpointer      user_data)         : Run Last

`milterclient` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.

### `"maintain"`シグナル

    void                user_function                      (MilterClient *milterclient,
                                                            gpointer      user_data)         : Run Last

`milterclient` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.

### `"sessions-finished"`シグナル

    void                user_function                      (MilterClient *milterclient,
                                                            guint         arg1,
                                                            gpointer      user_data)         : Run Last

`milterclient` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.