クライアントライブラリ

クライアントライブラリ — 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);

説明

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

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

使用法概観

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

接続指定はMTAがMilterClientに接続するためのエントリポイントです。接続指定は「プロトコル:情報」という形式になっています。IPv4ソケットでは「inet:ポート番号」、「inet:ポート番号@ホスト名」、「inet:ポート番号@[IPv4アドレス]」が正しい形式です。IPv6ソケットでは、「inet6:ポート番号」、「inet6:ポート番号@ホスト名」、「inet6:ポート番号@[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();

    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_main(client);

    milter_quit();

    return success ? EXIT_SUCCESS : EXIT_FAILURE;
}

処理モデル

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

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

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

MILTER_CLIENT_ERROR_RUNNING

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

MILTER_CLIENT_ERROR_UNIX_SOCKET

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

MILTER_CLIENT_ERROR_IO_ERROR

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

MilterClient

typedef struct {
    GObject object;
} 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が不正な形式で、errorNULLでない場合は、エラーの詳細は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);

メインループをはじめます。

client :

MilterClient

返値 :

メインループが正常終了したらTRUE、そうでなければFALSE

milter_client_shutdown ()

void                milter_client_shutdown              (MilterClient *client);

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

client :

MilterClient