# porter/include/porter_type.h

# 1 ファイル

## 1.1 porter/include/porter_type.h

通信ライブラリの型定義ファイル。

### 1.1.1 作者

c-modernization-kit sample team

### 1.1.2 バージョン

1.0.0

### 1.1.3 日付

2026/03/04

### 1.1.4 著作権

Copyright (C) CompanyName, Ltd. 2026. All rights reserved.

# 2 型

## 2.1 PotrType

通信種別。

サービス定義の通信方式を表します。

- POTR_TYPE_UNICAST_RAW, POTR_TYPE_MULTICAST_RAW, POTR_TYPE_BROADCAST_RAW
  RAW モード (再送なし、ベストエフォート)。
  受信ウィンドウによる順序整列とセッション管理は有効。
  ギャップ検出時は NACK の代わりに POTR_EVENT_DISCONNECTED を発行する。
  通番は AES ノンス用にインクリメントするが、再送制御には使用しない。
  potrSend は常にブロッキング送信。マルチパス対応。
  PING ヘルスチェックは health_interval_ms / health_timeout_ms の設定に従う。

- POTR_TYPE_UNICAST, POTR_TYPE_MULTICAST, POTR_TYPE_BROADCAST
  再送制御あり UDP モード。
  NACK / 再送・スライディングウィンドウによる信頼性・順序保証。
  ギャップ検出時は RECEIVER が SENDER に NACK を送信し再送を要求する。
  再送不可能な場合は REJECT を送出し POTR_EVENT_DISCONNECTED を発行する。
  potrSend は送信ウィンドウに空きがある場合は非同期、満杯の場合はブロッキング。

- POTR_TYPE_UNICAST_BIDIR
  双方向 1:1 通信 (UDP ユニキャスト)。
  SENDER / RECEIVER ともに送受信・NACK・ヘルスチェックを独立して行う。
  両端それぞれが src_addr:src_port で bind し、相手の dst_addr:dst_port へ送信する。
  src_port = 0 を指定すると SENDER はエフェメラルポートで bind し、
  RECEIVER は最初のパケット受信時に SENDER のポートを動的学習して返信する。
  src_addr を省略した場合:
  SENDER : INADDR_ANY で bind し、OS がルーティングに基づきアダプタを自動選択する。
  RECEIVER: 最初の受信パケットから SENDER のアドレスを動的学習する (1:1 通信を維持)。
  SENDER も callback が必須。

- POTR_TYPE_UNICAST_BIDIR_N1
  N:1 双方向通信 (UDP ユニキャスト)。
  サーバ側は dst_addr:dst_port で bind し、複数クライアントを同時に受け入れる。
  クライアントは POTR_TYPE_UNICAST_BIDIR (1:1) として接続する。
  max_peers で最大同時接続数を制御 (省略時: 1024)。
  src_addr は不要。src_port 指定でポートフィルタ付き N:1 になる。

- POTR_TYPE_TCP, POTR_TYPE_TCP_BIDIR
  TCP ユニキャスト通信。
  TCP 3way handshake による接続確立。SENDER が connect()、RECEIVER が accept()。
  NACK / 再送なし (TCP 自体が信頼性・順序を保証)。
  スライディングウィンドウなし (TCP のフロー制御に委ねる)。
  SENDER 側は reconnect_interval_ms / connect_timeout_ms で再接続挙動を制御。
  接続切断時は POTR_EVENT_DISCONNECTED を発行する。

列挙子 | 値 | 説明
--- | --- | ---
POTR_TYPE_UNICAST_RAW | 1 | 1:1 通信 RAW モード (UDP ユニキャスト)。
POTR_TYPE_MULTICAST_RAW | 2 | 1:N 通信 RAW モード (UDP マルチキャスト)。
POTR_TYPE_BROADCAST_RAW | 3 | 1:N 通信 RAW モード (UDP ブロードキャスト)。
POTR_TYPE_UNICAST | 4 | 1:1 通信 (UDP ユニキャスト)。
POTR_TYPE_MULTICAST | 5 | 1:N 通信 (UDP マルチキャスト)。
POTR_TYPE_BROADCAST | 6 | 1:N 通信 (UDP ブロードキャスト)。
POTR_TYPE_UNICAST_BIDIR | 7 | 双方向 1:1 通信 (UDP ユニキャスト)。
POTR_TYPE_UNICAST_BIDIR_N1 | 8 | N:1 双方向通信 (UDP ユニキャスト)。
POTR_TYPE_TCP | 9 | TCP ユニキャスト通信 (単方向: SENDER のみ potrSend 可)。
POTR_TYPE_TCP_BIDIR | 10 | TCP 双方向通信 (両端が potrSend 可)。

## 2.2 PotrRole

役割種別。

potrOpenService() の呼び出し元がデータを送信する役割か受信する役割かを明示します。

列挙子 | 値 | 説明
--- | --- | ---
POTR_ROLE_SENDER | 1 | 送信者。
POTR_ROLE_RECEIVER | 2 | 受信者。

## 2.3 PotrEvent

受信イベント種別。

PotrRecvCallback の第 2 引数に渡されるイベント種別です。

列挙子 | 値 | 説明
--- | --- | ---
POTR_EVENT_DATA | 0 | データ受信。data/len に内容が格納される。
POTR_EVENT_CONNECTED | 1 | 送信者からの疎通を初検知 or 復帰。data=NULL, len=0。
POTR_EVENT_DISCONNECTED | 2 | 切断を検知 (タイムアウト / FIN 受信 / REJECT 受信)。data=NULL, len=0。

### 2.3.1 補足

POTR_EVENT_CONNECTED / POTR_EVENT_DISCONNECTED は、data=NULL, len=0 で呼び出されます。
すべてのイベントは受信スレッドから直列に呼び出されるため、順序性が保証されます。
ヘルスチェックの有効/無効に関わらず、初回パケット受信時に CONNECTED が発火し、接続状態を管理します。
DISCONNECTED の発火条件:

- ヘルスチェック有効時 (health_timeout_ms > 0): タイムアウト / FIN 受信 / REJECT 受信

- ヘルスチェック無効時 (health_timeout_ms = 0): FIN 受信 / REJECT 受信
  REJECT 受信後は DISCONNECTED の直後に、次のパケット受信で CONNECTED が発火します。

## 2.4 PotrLogLevel

ログレベル。

potrLogConfig() の level 引数に指定するログ出力レベルです。
数値が小さいほど重大度が高く、指定したレベル以下 (より重大) のメッセージのみが出力されます。
数値順序は trace-util の enum trace_level と対応しています。

PotrLogLevel | 値 | trace_level | syslog priority
--- | --- | --- | ---
POTR_TRACE_CRITICAL | 0 | TRACE_LV_CRITICAL | LOG_CRIT
POTR_TRACE_ERROR | 1 | TRACE_LV_ERROR | LOG_ERR
POTR_TRACE_WARNING | 2 | TRACE_LV_WARNING | LOG_WARNING
POTR_TRACE_INFO | 3 | TRACE_LV_INFO | LOG_INFO
POTR_TRACE_VERBOSE | 4 | TRACE_LV_VERBOSE | LOG_DEBUG
POTR_TRACE_NONE | 5 | TRACE_LV_NONE | -

列挙子 | 値 | 説明
--- | --- | ---
POTR_TRACE_CRITICAL | 0 | 致命的エラー。回復不能な障害を記録。TRACE_LV_CRITICAL (0) と同値。
POTR_TRACE_ERROR | 1 | エラー。操作の失敗を記録。TRACE_LV_ERROR (1) と同値。
POTR_TRACE_WARNING | 2 | 警告。回復可能な異常を記録。TRACE_LV_WARNING (2) と同値。
POTR_TRACE_INFO | 3 | 情報。TRACE_LV_INFO (3) と同値。
POTR_TRACE_VERBOSE | 4 | 詳細情報 (デバッグ)。TRACE_LV_VERBOSE (4) と同値。
POTR_TRACE_NONE | 5 | ログ出力無効。TRACE_LV_NONE (5) と同値。

## 2.5 PotrPeerId

    typedef uint32_t PotrPeerId;

ピア識別子。

N:1 モードで各クライアントを識別する ID です。
N:1 モードでは有効なピア ID は常に POTR_PEER_NA および POTR_PEER_ALL 以外の値です。
1:1 モードおよびその他の通信種別では peer_id は常に POTR_PEER_NA です。

N:1 通信モード (`POTR_TYPE_UNICAST_BIDIR` src 情報なし) で各接続ピアを識別する ID です。
1:1 通信モードおよびその他の通信種別では常に `POTR_PEER_NA` を使用します。
有効な N:1 ピア ID は常に `POTR_PEER_NA` および `POTR_PEER_ALL` 以外の値となります（ピア ID 生成ロジックにより保証）。
予約値については ピア ID 予約値 を参照してください。

## 2.6 PotrHandle

    typedef struct PotrContext_ *PotrHandle;

セッションハンドル。

potrOpenService() が返す不透明ポインタです。
内部実装の詳細はライブラリ利用者からは隠蔽されます。

## 2.7 PotrRecvCallback

    typedef void (*PotrRecvCallback) (int64_t service_id, PotrPeerId peer_id, PotrEvent event, const void *data, size_t len);

受信コールバック関数型 (全通信種別共通)。

データ受信またはヘルスチェック状態変化時に、受信スレッドから呼び出されます。
コールバック内でブロッキング処理を行わないようにしてください。
すべてのイベントは受信スレッドから直列に呼び出されるため、順序性が保証されます。

### 2.7.1 引数

- service_id [in] サービスの ID。
- peer_id [in] ピア識別子。N:1 モード時は接続ピアの ID (`POTR_PEER_NA` / `POTR_PEER_ALL` 以外)。
  1:1 モードおよびその他の通信種別では常に POTR_PEER_NA。
- event [in] イベント種別 (PotrEvent)。
- data [in] 受信データへのポインタ。POTR_EVENT_DATA 時のみ有効。 コールバック復帰後は無効になります。
- len [in] 受信データのバイト数。POTR_EVENT_DATA 時のみ有効。

# 3 クラス/構造体

## 3.1 PotrServiceDef

    struct PotrServiceDef {
        int64_t service_id;
        PotrType type;
        uint16_t dst_port;
        uint16_t src_port;
        uint8_t ttl;
        uint8_t[3] _pad;
        uint32_t pack_wait_ms;
        char[POTR_MAX_ADDR_LEN] multicast_group;
        char[POTR_MAX_ADDR_LEN] broadcast_addr;
        char[POTR_MAX_PATH][POTR_MAX_ADDR_LEN] src_addr;
        char[POTR_MAX_PATH][POTR_MAX_ADDR_LEN] dst_addr;
        uint8_t[POTR_CRYPTO_KEY_SIZE] encrypt_key;
        int encrypt_enabled;
        uint32_t max_peers;
        uint32_t health_interval_ms;
        uint32_t health_timeout_ms;
        uint32_t reconnect_interval_ms;
        uint32_t connect_timeout_ms;
    }

サービス定義。

設定ファイルの [service.N] セクションから読み込まれるサービス設定です。

通信種別によって有効なフィールドが異なります。

### 3.1.1 属性

#### 3.1.1.1 service_id

    int64_t service_id;

サービス ID。

#### 3.1.1.2 type

    PotrType type;

通信種別。

#### 3.1.1.3 dst_port

    uint16_t dst_port;

宛先ポート番号。サービスの識別子。受信者の bind ポート / 送信者の送信先ポート。(全通信種別で必須)

#### 3.1.1.4 src_port

    uint16_t src_port;

送信者の送信元 bind ポート番号。0 = OS 自動選定。(全通信種別で省略可)

#### 3.1.1.5 ttl

    uint8_t ttl;

マルチキャスト TTL。(multicast のみ)

#### 3.1.1.6 _pad

    uint8_t[3] _pad;

パディング (pack_wait_ms を 4 バイト境界に揃える)。

#### 3.1.1.7 pack_wait_ms

    uint32_t pack_wait_ms;

パッキング待ち時間 (ミリ秒)。最初の送信要求からこの時間だけ待ち合わせ、複数メッセージを 1 パケットにまとめる。0 = 即時送信 (パッキング待ちなし)。パケット容量が満杯になった場合はタイマーを無視して即時送信する。

#### 3.1.1.8 multicast_group

    char[POTR_MAX_ADDR_LEN] multicast_group;

マルチキャストグループアドレス。(multicast のみ)

#### 3.1.1.9 broadcast_addr

    char[POTR_MAX_ADDR_LEN] broadcast_addr;

ブロードキャスト宛先アドレス。省略時は 255.255.255.255。(broadcast のみ)

#### 3.1.1.10 src_addr

    char[POTR_MAX_PATH][POTR_MAX_ADDR_LEN] src_addr;

送信元アドレス [0]=src_addr1 〜 [3]=src_addr4。送信者は bind / 送信インターフェース、受信者は送信元フィルタ。(全通信種別で必須)

#### 3.1.1.11 dst_addr

    char[POTR_MAX_PATH][POTR_MAX_ADDR_LEN] dst_addr;

宛先アドレス [0]=dst_addr1 〜 [3]=dst_addr4。送信者は送信先、受信者は bind アドレス。(unicast のみ)

#### 3.1.1.12 encrypt_key

    uint8_t[POTR_CRYPTO_KEY_SIZE] encrypt_key;

AES-256-GCM 事前共有鍵 (32 バイト)。encrypt_enabled が 0 の場合は未使用。

#### 3.1.1.13 encrypt_enabled

    int encrypt_enabled;

非 0 のとき暗号化有効。設定ファイルに有効な encrypt_key が存在するときに 1 に設定される。

#### 3.1.1.14 max_peers

    uint32_t max_peers;

N:1 モード時の最大同時接続ピア数。省略時: 1024。1:1 モードでは無視される。

#### 3.1.1.15 health_interval_ms

    uint32_t health_interval_ms;

グローバルの udp/tcp_health_interval_ms をサービス単位で上書きする。0 = グローバル値を使用。

#### 3.1.1.16 health_timeout_ms

    uint32_t health_timeout_ms;

グローバルの udp/tcp_health_timeout_ms をサービス単位で上書きする。0 = グローバル値を使用。

#### 3.1.1.17 reconnect_interval_ms

    uint32_t reconnect_interval_ms;

SENDER 自動再接続間隔 (ms)。0 = 再接続なし。デフォルト: POTR_DEFAULT_RECONNECT_INTERVAL_MS。

#### 3.1.1.18 connect_timeout_ms

    uint32_t connect_timeout_ms;

SENDER TCP 接続タイムアウト (ms)。0 = OS デフォルト。デフォルト: POTR_DEFAULT_CONNECT_TIMEOUT_MS。

## 3.2 PotrGlobalConfig

    struct PotrGlobalConfig {
        uint16_t window_size;
        uint16_t max_payload;
        uint32_t health_interval_ms;
        uint32_t health_timeout_ms;
        uint32_t reorder_timeout_ms;
        uint32_t max_message_size;
        uint32_t send_queue_depth;
        uint32_t tcp_health_interval_ms;
        uint32_t tcp_health_timeout_ms;
    }

グローバル設定。

設定ファイルの [global] セクションから読み込まれる共通プロトコル設定です。

### 3.2.1 属性

#### 3.2.1.1 window_size

    uint16_t window_size;

スライディングウィンドウサイズ (パケット数)。

#### 3.2.1.2 max_payload

    uint16_t max_payload;

最大ペイロード長 (バイト)。

#### 3.2.1.3 health_interval_ms

    uint32_t health_interval_ms;

UDP 通信種別の PING 送信間隔 (ミリ秒)。最終 DATA/PING 送信から本値が経過したら PING 送信。0 = 無効。設定ファイルキー: udp_health_interval_ms。

#### 3.2.1.4 health_timeout_ms

    uint32_t health_timeout_ms;

UDP 通信種別の受信タイムアウト (ミリ秒)。RECEIVER 側で使用。0 = 無効。設定ファイルキー: udp_health_timeout_ms。

#### 3.2.1.5 reorder_timeout_ms

    uint32_t reorder_timeout_ms;

受信ウィンドウ欠番検出後、NACK または切断を遅延する時間 (ミリ秒)。マルチパスや近距離 WAN での追い越し吸収用。0 = 即時 (デフォルト)。推奨値: LAN/マルチパス=10〜30 ms、遠距離 WAN=30〜100 ms。

#### 3.2.1.6 max_message_size

    uint32_t max_message_size;

1 回の potrSend で送信できる最大メッセージ長 (バイト)。デフォルト: POTR_MAX_MESSAGE_SIZE。

#### 3.2.1.7 send_queue_depth

    uint32_t send_queue_depth;

非同期送信キューの最大エントリ数。デフォルト: POTR_SEND_QUEUE_DEPTH。

#### 3.2.1.8 tcp_health_interval_ms

    uint32_t tcp_health_interval_ms;

TCP 通信種別の PING 送信間隔 (ミリ秒)。DATA 送信頻度に関わらず定期的に PING を送信。0 = 無効。設定ファイルキー: tcp_health_interval_ms。

#### 3.2.1.9 tcp_health_timeout_ms

    uint32_t tcp_health_timeout_ms;

TCP 通信種別の PING 応答待機タイムアウト (ミリ秒)。SENDER 側で使用。0 = 無効。設定ファイルキー: tcp_health_timeout_ms。

## 3.3 PotrPacket

    struct PotrPacket {
        int64_t service_id;
        int64_t session_tv_sec;
        uint32_t session_id;
        int32_t session_tv_nsec;
        uint32_t seq_num;
        uint32_t ack_num;
        uint16_t flags;
        uint16_t payload_len;
        uint32_t _reserved;
        const uint8_t *payload;
    }

ネットワーク送受信用パケット構造体。

UDP で送受信される物理パケットのレイアウトです。
各フィールドはネットワークバイトオーダー (ビッグエンディアン) で格納します。
ヘッダー固定長: offsetof(PotrPacket, payload) = 40 バイト (64 ビット環境)。
payload フィールドはポインタであり、wire データとして直接 sendto に渡せません。
送信時は PotrContext_ の send_wire_buf / recv_buf に wire データを組み立ててください。

ワイヤーフォーマット (バイトオフセット):

     0: service_id      (int64_t,  8 bytes)
     8: session_tv_sec  (int64_t,  8 bytes)
    16: session_id      (uint32_t, 4 bytes)
    20: session_tv_nsec (int32_t,  4 bytes)
    24: seq_num         (uint32_t, 4 bytes)
    28: ack_num         (uint32_t, 4 bytes)
    32: flags           (uint16_t, 2 bytes)
    34: payload_len     (uint16_t, 2 bytes)
    36: _reserved       (uint32_t, 4 bytes, padding)
    40: payload         (pointer)

### 3.3.1 属性

#### 3.3.1.1 service_id

    int64_t service_id;

サービス識別子 (NBO)。受信時に照合する。

#### 3.3.1.2 session_tv_sec

    int64_t session_tv_sec;

セッション開始時刻 秒部 (NBO)。struct timespec の tv_sec 相当。

#### 3.3.1.3 session_id

    uint32_t session_id;

セッション識別子 (NBO)。potrOpenService 時に決定する乱数。

#### 3.3.1.4 session_tv_nsec

    int32_t session_tv_nsec;

セッション開始時刻 ナノ秒部 (NBO)。struct timespec の tv_nsec 相当。

#### 3.3.1.5 seq_num

    uint32_t seq_num;

通番。送信側が付与する連番 (NBO)。

#### 3.3.1.6 ack_num

    uint32_t ack_num;

再送要求番号 / 再送不能通番 (NBO)。NACK では要求通番、REJECT では再送不能通番を格納する。

#### 3.3.1.7 flags

    uint16_t flags;

パケット種別フラグ (POTR_FLAG_*) (NBO)。

#### 3.3.1.8 payload_len

    uint16_t payload_len;

ペイロード長 (バイト) (NBO)。

#### 3.3.1.9 _reserved

    uint32_t _reserved;

パディング (payload ポインタを 8 バイト境界に揃える)。

#### 3.3.1.10 payload

    const uint8_t *payload;

ペイロードデータへのポインタ (読み取り専用)。ウィンドウプールまたは受信バッファ内を指す。

# 4 カテゴリー

## 4.1 ピア ID 予約値

### 4.1.1 定数、マクロ

#### 4.1.1.1 POTR_PEER_NA

    #define POTR_PEER_NA ((PotrPeerId)0U)

ピア ID 未割当を示す予約値。 1:1 モードのコールバックで渡される (ピアの概念がない)。 `potrSend()` に N:1 モードで指定した場合はエラーを返す。

#### 4.1.1.2 POTR_PEER_ALL

    #define POTR_PEER_ALL ((PotrPeerId)UINT32_MAX)

全接続ピアへの一斉送信を指示する予約ピア ID。 N:1 モードでは全アクティブピアへユニキャスト送信する。 1:1 モードでは唯一のピアへの送信として動作する。