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

## Functions

#define | MILTER_CLIENT_ERROR
GQuark | milter_client_error_quark ()
MilterClient * | milter_client_new ()
gchar * | milter_client_get_default_connection_spec ()
gboolean | milter_client_set_connection_spec ()
GIOChannel * | milter_client_get_listen_channel ()
void | milter_client_set_listen_channel ()
void | milter_client_set_listen_backlog ()
gboolean | milter_client_is_remove_unix_socket_on_create ()
void | milter_client_set_remove_unix_socket_on_create ()
void | milter_client_set_timeout ()
guint | milter_client_get_unix_socket_mode ()
guint | milter_client_get_default_unix_socket_mode ()
void | milter_client_set_default_unix_socket_mode ()
const gchar * | milter_client_get_unix_socket_group ()
const gchar * | milter_client_get_default_unix_socket_group ()
void | milter_client_set_default_unix_socket_group ()
gboolean | milter_client_is_remove_unix_socket_on_close ()
gboolean | milter_client_get_default_remove_unix_socket_on_close ()
void | milter_client_set_default_remove_unix_socket_on_close ()
gboolean | milter_client_main ()
void | milter_client_shutdown ()

## プロパティ

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

## シグナル

void | connection-established | Run Last
void | event-loop-created | Run Last
void | listen-started | Run Last
void | maintain | Run Last
void | sessions-finished | Run Last
void | worker-created | Run Last
void | workers-created | Run Last

## Types and Values

enum | MilterClientError
| MilterClient

## オブジェクト階層

        GObject
        ╰── MilterClient

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

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

## 説明

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

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

== Usage overview You need to set connection spec and connect “connection-established” signal before entering mail loop. Connection spec is a entry point of `MilterClient` for MTA. It has 'PROTOCOL:INFORMATION' format. For IPv4 socket, 'inet:PORT', 'inet:PORT@HOST' or 'inet:PORT@[ADDRESS]' are valid formats. For IPv6 socket, 'inet6:PORT', 'inet6:PORT@HOST' or 'inet6:PORT@[ADDRESS]' are valid formats. For UNIX domain socket, 'unix:PATH' is a valid format. `MilterClient` emits “connection-established” signal. `MilterClientContext` setup should be done in the signal. In many cases, you just connect callbacks to the passed `MilterClientContext`. See `MilterClientContext` for available signals. `milter_client_run()` is running main loop function. You can enter into main loop after you finish to prepare your `MilterClient`. Here is an example codes that uses the milter-client library. See also tool/milter-test-client.c. It is an example milter implementation using the milter-client library.

    #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;
    }

== Processing model The libmilter provided by Sendmail uses a thread for each connection model. But the milter-client library doesn't use it. The milter-client library uses two threads. One thread is for `MilterClient` and other thread is for `MilterClientContext`s. `MilterClient` just accepting connections from MTA and dispatches it in the first thread. Each connection is associated with `MilterClientContext` and they are processed in the second thread. The milter-client library's model is the same model of memcached. (memcached uses libevent as its event loop backend but the milter-client library uses GLib's `GMainLoop` for it.) The libmilter's model will have more cost to accept a connection rather than the milter-client library's model. Because the libmilter's model creates a thread but the milter-client library just allocate `MilterClientContext`. But in many case, this difference is not bottleneck. :-|

## Functions

### MILTER_CLIENT_ERROR

    #define MILTER_CLIENT_ERROR           (milter_client_error_quark())

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

MILTER_CLIENT_ERROR

### milter_client_error_quark ()

    GQuark
    milter_client_error_quark (void);

#### Returns

milter_client_error_quark

### milter_client_new ()

    MilterClient *
    milter_client_new (void);

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

#### Returns

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

milter_client_new

### milter_client_get_default_connection_spec ()

    gchar *
    milter_client_get_default_connection_spec
                                   (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

#### Returns

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

milter_client_get_default_connection_spec

### milter_client_set_connection_spec ()

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

Sets a connection specification. If spec is invalid format and error is not `NULL`, error detail is stored into error .

#### Parameters

client | `MilterClient`。 |
spec | inet:10025のような接続指定。 |
error | エラーを受け取る場所のアドレス、または`NULL`。 |

#### Returns

成功時は`TRUE`。

milter_client_set_connection_spec

### milter_client_get_listen_channel ()

    GIOChannel *
    milter_client_get_listen_channel (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

#### Returns

接続待ち用チャンネル。

milter_client_get_listen_channel

### milter_client_set_listen_channel ()

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

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

#### Parameters

client | `MilterClient`。 |
channel | 接続待ち用のチャンネル。 |

milter_client_set_listen_channel

### milter_client_set_listen_backlog ()

    void
    milter_client_set_listen_backlog (MilterClient *client,
                                      gint backlog);

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

#### Parameters

client | `MilterClient`。 |
backlog | listen(2)用のバックログ。 |

milter_client_set_listen_backlog

### milter_client_is_remove_unix_socket_on_create ()

    gboolean
    milter_client_is_remove_unix_socket_on_create
                                   (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

#### Returns

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

milter_client_is_remove_unix_socket_on_create

### milter_client_set_remove_unix_socket_on_create ()

    void
    milter_client_set_remove_unix_socket_on_create
                                   (MilterClient *client,
                                    gboolean remove);

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

#### Parameters

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

milter_client_set_remove_unix_socket_on_create

### milter_client_set_timeout ()

    void
    milter_client_set_timeout (MilterClient *client,
                               guint timeout);

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

#### Parameters

client | `MilterClient`。 |
timeout | 秒単位でのタイムアウト。 |

milter_client_set_timeout

### milter_client_get_unix_socket_mode ()

    guint
    milter_client_get_unix_socket_mode (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

#### Returns

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

milter_client_get_unix_socket_mode

### milter_client_get_default_unix_socket_mode ()

    guint
    milter_client_get_default_unix_socket_mode
                                   (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

#### Returns

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

milter_client_get_default_unix_socket_mode

### milter_client_set_default_unix_socket_mode ()

    void
    milter_client_set_default_unix_socket_mode
                                   (MilterClient *client,
                                    guint mode);

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

#### Parameters

client | `MilterClient`。 |
mode | UNIXドメインソケットのモード。 |

milter_client_set_default_unix_socket_mode

### milter_client_get_unix_socket_group ()

    const gchar *
    milter_client_get_unix_socket_group (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

#### Returns

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

milter_client_get_unix_socket_group

### milter_client_get_default_unix_socket_group ()

    const gchar *
    milter_client_get_default_unix_socket_group
                                   (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

#### Returns

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

milter_client_get_default_unix_socket_group

### milter_client_set_default_unix_socket_group ()

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

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

#### Parameters

client | `MilterClient`。 |
group | グループ名。 |

milter_client_set_default_unix_socket_group

### milter_client_is_remove_unix_socket_on_close ()

    gboolean
    milter_client_is_remove_unix_socket_on_close
                                   (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

#### Returns

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

milter_client_is_remove_unix_socket_on_close

### milter_client_get_default_remove_unix_socket_on_close ()

    gboolean
    milter_client_get_default_remove_unix_socket_on_close
                                   (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

#### Returns

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

milter_client_get_default_remove_unix_socket_on_close

### milter_client_set_default_remove_unix_socket_on_close ()

    void
    milter_client_set_default_remove_unix_socket_on_close
                                   (MilterClient *client,
                                    gboolean remove);

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

#### Parameters

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

milter_client_set_default_remove_unix_socket_on_close

### 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.

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

#### Parameters

client | `MilterClient`。 |

#### Returns

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

milter_client_main

### milter_client_shutdown ()

    void
    milter_client_shutdown (MilterClient *client);

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

#### Parameters

client | `MilterClient`。 |

milter_client_shutdown

## Types and Values

### enum MilterClientError

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

#### Members

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 |  |

MilterClientError

### MilterClient

    typedef struct _MilterClient MilterClient;

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

MilterClient

## プロパティ詳細

### The `“connection-spec”` property

      “connection-spec”          gchar *

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

Flags: Read

デフォルト値: NULL

MilterClient:connection-spec

### The `“custom-fork”` property

      “custom-fork”              gpointer

The custom fork.

Flags: Read / Write

MilterClient:custom-fork

### The `“default-packet-buffer-size”` property

      “default-packet-buffer-size” guint

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

Flags: Read / Write

デフォルト値: 0

MilterClient:default-packet-buffer-size

### The `“event-loop”` property

      “event-loop”               MilterEventLoop *

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

Flags: Read

MilterClient:event-loop

### The `“event-loop-backend”` property

      “event-loop-backend”       MilterClientEventLoopBackend

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

Flags: Read / Write

Default value: MILTER_CLIENT_EVENT_LOOP_BACKEND_DEFAULT

MilterClient:event-loop-backend

### The `“maintenance-interval”` property

      “maintenance-interval”     guint

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

Flags: Read / Write

デフォルト値: 0

MilterClient:maintenance-interval

### The `“max-pending-finished-sessions”` property

      “max-pending-finished-sessions” guint

The maximum number of pending finished sessions of the client.

Flags: Read / Write

デフォルト値: 0

MilterClient:max-pending-finished-sessions

### The `“n-workers”` property

      “n-workers”                guint

The Number of worker processes of the client.

Flags: Read / Write

Allowed values: <= 1000

デフォルト値: 0

MilterClient:n-workers

### The `“pid-file”` property

      “pid-file”                 gchar *

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

Flags: Read / Write

デフォルト値: NULL

MilterClient:pid-file

### The `“remove-pid-file-on-exit”` property

      “remove-pid-file-on-exit”  gboolean

Whether removing PID file of the client on exist.

Flags: Read / Write

デフォルト値: TRUE

MilterClient:remove-pid-file-on-exit

### The `“run-as-daemon”` property

      “run-as-daemon”            gchar *

Whether running the client as a daemon or not.

Flags: Read / Write

デフォルト値: NULL

MilterClient:run-as-daemon

### The `“start-syslog”` property

      “start-syslog”             gboolean

Start syslog for the client.

Flags: Write

Default value: FALSE

MilterClient:start-syslog

### The `“syslog-facility”` property

      “syslog-facility”          gchar *

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

Flags: Read / Write

デフォルト値: NULL

MilterClient:syslog-facility

### The `“syslog-identify”` property

      “syslog-identify”          gchar *

Syslog identify of the client.

Flags: Read / Write

デフォルト値: NULL

MilterClient:syslog-identify

### The `“worker-id”` property

      “worker-id”                guint

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

Flags: Read

Allowed values: <= 1000

デフォルト値: 0

MilterClient:worker-id

## シグナル詳細

### The `“connection-established”` signal

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

#### Parameters

milterclient | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

MilterClient::connection-established

### The `“event-loop-created”` signal

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

#### Parameters

milterclient | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

MilterClient::event-loop-created

### The `“listen-started”` signal

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

#### Parameters

milterclient | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

MilterClient::listen-started

### The `“maintain”` signal

    void
    user_function (MilterClient *milterclient,
                   gpointer      user_data)

#### Parameters

milterclient | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

MilterClient::maintain

### The `“sessions-finished”` signal

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

#### Parameters

milterclient | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

MilterClient::sessions-finished

### The `“worker-created”` signal

    void
    user_function (MilterClient *milterclient,
                   gpointer      user_data)

#### Parameters

milterclient | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

MilterClient::worker-created

### The `“workers-created”` signal

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

#### Parameters

milterclient | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

MilterClient::workers-created