Document of c-modernization-kit (porter) 1.0.0

Loading...
Searching...
No Matches
Macros | Functions
porter.h File Reference

通信ライブラリ (動的リンク用) のヘッダーファイル。 More...

`#include <porter_type.h>`
Include dependency graph for porter.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros
#define | POTR_EXPORT
| DLL エクスポート/インポート制御マクロ。
#define | POTR_API
| 呼び出し規約マクロ。

## Functions
POTR_EXPORT int POTR_API | potrOpenService (const PotrGlobalConfig *global, const PotrServiceDef *service, PotrRole role, PotrRecvCallback callback, PotrHandle *handle)
| 設定構造体から指定サービスを開きます。
POTR_EXPORT int POTR_API | potrOpenServiceFromConfig (const char *config_path, int64_t service_id, PotrRole role, PotrRecvCallback callback, PotrHandle *handle)
| 設定ファイルから指定サービスを開きます。
POTR_EXPORT int POTR_API | potrSend (PotrHandle handle, PotrPeerId peer_id, const void *data, size_t len, int flags)
| メッセージを送信します。
POTR_EXPORT int POTR_API | potrDisconnectPeer (PotrHandle handle, PotrPeerId peer_id)
| 指定ピアを切断します (N:1 モード専用)。
POTR_EXPORT int POTR_API | potrCloseService (PotrHandle handle)
| サービスを閉じます。
POTR_EXPORT int POTR_API | potrLogConfig (PotrLogLevel level, const char *log_file, int console)
| ロガーを設定します。
POTR_EXPORT int POTR_API | potrGetServiceType (const char *config_path, int64_t service_id, PotrType *type)
| 設定ファイルから指定サービスの通信種別を取得します。

## Detailed Description

通信ライブラリ (動的リンク用) のヘッダーファイル。

Author
  c-modernization-kit sample team

Date
  2026/03/04

Version
  1.0.0

このライブラリは UDP/IP を用いたプラットフォーム間通信を提供します。
Linux / Windows クロスプラットフォーム対応の DLL として提供されます。

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

Definition in file porter.h.

## Macro Definition Documentation

## ◆ POTR_EXPORT

#define POTR_EXPORT

DLL エクスポート/インポート制御マクロ。

ビルド条件に応じて以下の値を取ります。

条件 | 値
--- | ---
Linux (非 Windows) | (空)
Windows / __INTELLISENSE__ 定義時 | (空)
Windows / POTR_STATIC 定義時 (静的リンク) | (空)
Windows / POTR_EXPORTS 定義時 (DLL ビルド) | __declspec(dllexport)
Windows / POTR_EXPORTS 未定義時 (DLL 利用側) | __declspec(dllimport)

Definition at line 37 of file porter.h.

Referenced by potrCloseService(), potrDisconnectPeer(), potrGetServiceType(), potrLogConfig(), potrOpenService(), potrOpenServiceFromConfig(), and potrSend().

## ◆ POTR_API

#define POTR_API

呼び出し規約マクロ。

Windows 環境では __stdcall 呼び出し規約を指定します。
Linux (非 Windows) 環境では空に展開されます。
既に定義済みの場合は再定義されません。

Definition at line 46 of file porter.h.

Referenced by potrCloseService(), potrDisconnectPeer(), potrGetServiceType(), potrLogConfig(), potrOpenService(), potrOpenServiceFromConfig(), and potrSend().

## Function Documentation

## ◆ potrOpenService()

POTR_EXPORT int POTR_API potrOpenService | ( | const PotrGlobalConfig * | global,
|  | const PotrServiceDef * | service,
|  | PotrRole | role,
|  | PotrRecvCallback | callback,
|  | PotrHandle * | handle )
| extern

設定構造体から指定サービスを開きます。

Parameters

  [in] | global | グローバル設定構造体へのポインタ。
  [in] | service | サービス定義構造体へのポインタ。
  [in] | role | 役割種別。POTR_ROLE_SENDER または POTR_ROLE_RECEIVER。
  [in] | callback | イベント発生時に呼び出されるコールバック関数 (PotrRecvCallback)。 POTR_ROLE_RECEIVER の場合は必須。データ受信・接続検知・切断検知を受け取る。 POTR_ROLE_SENDER の場合は通常 NULL を指定すること。 ただし POTR_TYPE_TCP_BIDIR および POTR_TYPE_UNICAST_BIDIR では SENDER にもコールバックが必須。これらの種別では POTR_ROLE_SENDER でも callback が NULL の場合は失敗を返します。
  [out] | handle | 成功時にセッションハンドルを格納するポインタ。

Returns
  成功時は POTR_SUCCESS、失敗時は POTR_ERROR を返します。

設定構造体からサービス定義を取得し、UDP ソケットを初期化します。
role と callback の組み合わせが不正な場合は POTR_ERROR を返します。
role と設定の IP アドレスが不整合 (bind 失敗など) の場合も POTR_ERROR を返します。
通信種別・役割に応じて以下のソケット設定を行います。

通信種別 | 役割 | bind アドレス | bind ポート
--- | --- | --- | ---
POTR_TYPE_UNICAST | 送信者 | src_addr | src_port
POTR_TYPE_UNICAST | 受信者 | dst_addr | dst_port
POTR_TYPE_MULTICAST | 送信者 | INADDR_ANY | src_port
POTR_TYPE_MULTICAST | 受信者 | INADDR_ANY | dst_port
POTR_TYPE_BROADCAST | 送信者 | src_addr | src_port
POTR_TYPE_BROADCAST | 受信者 | INADDR_ANY | dst_port

POTR_ROLE_RECEIVER の場合、内部で受信スレッドを起動します。

使用例 (受信者)
  void on_recv(int64_t service_id, PotrPeerId peer_id,
  PotrEvent event, const void *data, size_t len) {
  (void)peer_id; // 1:1 モードでは常に POTR_PEER_NA
  if (event == POTR_EVENT_CONNECTED)
  printf("service %" PRId64 ": connected\n", service_id);
  else if (event == POTR_EVENT_DISCONNECTED)
  printf("service %" PRId64 ": disconnected\n", service_id);
  else
  printf("service %" PRId64 ": received %zu bytes\n", service_id, len);
  }
  PotrGlobalConfig global = {0};
  global.window_size = 16;
  global.max_payload = 1400;
  global.max_message_size = 65535;
  global.send_queue_depth = 64;
  PotrServiceDef service = {0};
  service.service_id = 1001;
  service.type = POTR_TYPE_UNICAST;
  service.dst_port = 49001;
  strncpy(service.src_addr[0], "127.0.0.1", POTR_MAX_ADDR_LEN - 1);
  strncpy(service.dst_addr[0], "127.0.0.1", POTR_MAX_ADDR_LEN - 1);
  PotrHandle handle;
  if (potrOpenService(&global, &service,
  POTR_ROLE_RECEIVER, on_recv, &handle) == POTR_SUCCESS) {
  // 受信待機中 (受信スレッドが動作)
  potrCloseService(handle);
  }
  POTR_MAX_ADDR_LEN
  #define POTR_MAX_ADDR_LEN
  アドレス文字列の最大長 (バイト、終端 NUL を含む)。
  Definition porter_const.h:93
  POTR_SUCCESS
  #define POTR_SUCCESS
  成功の戻り値を表す定数。
  Definition porter_const.h:30
  potrOpenService
  POTR_EXPORT int POTR_API potrOpenService(const PotrGlobalConfig *global, const PotrServiceDef *service, PotrRole role, PotrRecvCallback callback, PotrHandle *handle)
  設定構造体から指定サービスを開きます。
  Definition potrOpenService.c:445
  potrCloseService
  POTR_EXPORT int POTR_API potrCloseService(PotrHandle handle)
  サービスを閉じます。
  Definition potrCloseService.c:120
  POTR_TYPE_UNICAST
  @ POTR_TYPE_UNICAST
  1:1 通信 (UDP ユニキャスト)。
  Definition porter_type.h:90
  PotrHandle
  struct PotrContext_ * PotrHandle
  セッションハンドル。
  Definition porter_type.h:238
  POTR_ROLE_RECEIVER
  @ POTR_ROLE_RECEIVER
  受信者。
  Definition porter_type.h:116
  PotrPeerId
  uint32_t PotrPeerId
  ピア識別子。
  Definition porter_type.h:32
  PotrEvent
  PotrEvent
  受信イベント種別。
  Definition porter_type.h:284
  POTR_EVENT_DISCONNECTED
  @ POTR_EVENT_DISCONNECTED
  切断を検知 (タイムアウト / FIN 受信 / REJECT 受信)。data=NULL, len=0。
  Definition porter_type.h:287
  POTR_EVENT_CONNECTED
  @ POTR_EVENT_CONNECTED
  送信者からの疎通を初検知 or 復帰。data=NULL, len=0。
  Definition porter_type.h:286
  on_recv
  static void on_recv(int64_t service_id, PotrPeerId peer_id, PotrEvent event, const void *data, size_t len)
  受信コールバック関数。
  Definition recv.c:122
  PotrGlobalConfig
  グローバル設定。
  Definition porter_type.h:177
  PotrGlobalConfig::window_size
  uint16_t window_size
  スライディングウィンドウサイズ (パケット数)。
  Definition porter_type.h:178
  PotrGlobalConfig::send_queue_depth
  uint32_t send_queue_depth
  非同期送信キューの最大エントリ数。デフォルト: POTR_SEND_QUEUE_DEPTH。
  Definition porter_type.h:184
  PotrGlobalConfig::max_payload
  uint16_t max_payload
  最大ペイロード長 (バイト)。
  Definition porter_type.h:179
  PotrGlobalConfig::max_message_size
  uint32_t max_message_size
  1 回の potrSend で送信できる最大メッセージ長 (バイト)。デフォルト: POTR_MAX_MESSAGE_SIZE。
  Definition porter_type.h:183
  PotrServiceDef
  サービス定義。
  Definition porter_type.h:130
  PotrServiceDef::dst_port
  uint16_t dst_port
  宛先ポート番号。サービスの識別子。受信者の bind ポート / 送信者の送信先ポート。(全通信種別で必須)
  Definition porter_type.h:135
  PotrServiceDef::src_addr
  char src_addr[POTR_MAX_PATH][POTR_MAX_ADDR_LEN]
  送信元アドレス [0]=src_addr1 〜 [3]=src_addr4。送信者は bind / 送信インターフェース、受信者は送信元フィルタ。(全通信種別で必須)
  Definition porter_type.h:149
  PotrServiceDef::type
  PotrType type
  通信種別。
  Definition porter_type.h:132
  PotrServiceDef::service_id
  int64_t service_id
  サービス ID。
  Definition porter_type.h:131
  PotrServiceDef::dst_addr
  char dst_addr[POTR_MAX_PATH][POTR_MAX_ADDR_LEN]
  宛先アドレス [0]=dst_addr1 〜 [3]=dst_addr4。送信者は送信先、受信者は bind アドレス。(unicast のみ)
  Definition porter_type.h:150

使用例 (送信者)
  PotrGlobalConfig global = {0};
  global.window_size = 16;
  global.max_payload = 1400;
  global.max_message_size = 65535;
  global.send_queue_depth = 64;
  PotrServiceDef service = {0};
  service.service_id = 1001;
  service.type = POTR_TYPE_UNICAST;
  service.dst_port = 49001;
  strncpy(service.src_addr[0], "127.0.0.1", POTR_MAX_ADDR_LEN - 1);
  strncpy(service.dst_addr[0], "127.0.0.1", POTR_MAX_ADDR_LEN - 1);
  PotrHandle handle;
  if (potrOpenService(&global, &service,
  POTR_ROLE_SENDER, NULL, &handle) == POTR_SUCCESS) {
  potrSend(handle, POTR_PEER_NA, "hello", 5, 0);
  potrCloseService(handle);
  }
  POTR_PEER_NA
  #define POTR_PEER_NA
  ピア ID 未割当を示す予約値。 1:1 モードのコールバックで渡される (ピアの概念がない)。 potrSend() に N:1 モードで指定した場合はエラーを返す。
  Definition porter_type.h:258
  potrSend
  POTR_EXPORT int POTR_API potrSend(PotrHandle handle, PotrPeerId peer_id, const void *data, size_t len, int flags)
  メッセージを送信します。
  Definition potrSend.c:88
  POTR_ROLE_SENDER
  @ POTR_ROLE_SENDER
  送信者。
  Definition porter_type.h:115

スレッド セーフティ
  本関数はスレッドセーフです。
  異なるスレッドから独立したハンドルを取得するために並行して呼び出すことができます。
  ただし取得したハンドルはスレッドセーフではありません。
  同一ハンドルに対する操作は 1 スレッドから行ってください。

Warning
  global が NULL の場合は失敗を返します。
  service が NULL の場合は失敗を返します。
  handle が NULL の場合は失敗を返します。
  POTR_ROLE_RECEIVER かつ callback が NULL の場合は失敗を返します。
  POTR_ROLE_SENDER かつ callback が NULL でない場合は失敗を返します。
  ただし POTR_TYPE_TCP_BIDIR および POTR_TYPE_UNICAST_BIDIR では SENDER にも
  コールバックが必須であり、この場合 callback が NULL の場合は失敗を返します。

Definition at line 445 of file potrOpenService.c.

References PotrServiceDef::broadcast_addr, PotrContext_::callback, comm_recv_thread_start(), PotrContext_::compress_buf, PotrContext_::compress_buf_size, PotrContext_::crypto_buf, PotrContext_::crypto_buf_size, ctx_cleanup(), PotrContext_::dest_addr, PotrServiceDef::dst_addr, PotrContext_::dst_addr_resolved, PotrServiceDef::dst_port, PotrServiceDef::encrypt_enabled, PotrContext_::frag_buf, generate_session(), PotrContext_::global, PotrGlobalConfig::health_interval_ms, PotrServiceDef::health_interval_ms, PotrContext_::health_mutex, PotrGlobalConfig::health_timeout_ms, PotrServiceDef::health_timeout_ms, PotrContext_::health_wakeup, PotrContext_::is_multi_peer, PotrGlobalConfig::max_message_size, PotrGlobalConfig::max_payload, PotrContext_::max_peers, PotrServiceDef::max_peers, PotrServiceDef::multicast_group, PotrContext_::n_path, open_socket_broadcast(), open_socket_multicast(), open_socket_tcp_receiver(), open_socket_tcp_sender(), open_socket_unicast(), PACKET_HEADER_SIZE, parse_ipv4_addr(), peer_table_init(), POTR_API, POTR_COMPRESS_HEADER_SIZE, potr_connect_thread_start(), POTR_CRYPTO_TAG_SIZE, POTR_ERROR, POTR_EXPORT, potr_health_thread_start(), potr_health_thread_stop(), POTR_INVALID_SOCKET, potr_is_tcp_type(), POTR_LOG, POTR_MAX_PATH, POTR_MAX_PAYLOAD, POTR_MAX_WINDOW_SIZE, potr_raw_base_type(), POTR_ROLE_RECEIVER, POTR_ROLE_SENDER, potr_send_queue_destroy(), potr_send_queue_init(), potr_send_thread_start(), potr_send_thread_stop(), POTR_SUCCESS, POTR_TRACE_ERROR, POTR_TRACE_INFO, POTR_TRACE_VERBOSE, POTR_TYPE_BROADCAST, POTR_TYPE_BROADCAST_RAW, POTR_TYPE_MULTICAST, POTR_TYPE_MULTICAST_RAW, POTR_TYPE_TCP, POTR_TYPE_TCP_BIDIR, POTR_TYPE_UNICAST, POTR_TYPE_UNICAST_BIDIR, POTR_TYPE_UNICAST_BIDIR_N1, POTR_TYPE_UNICAST_RAW, PotrContext_::recv_buf, PotrContext_::recv_window, PotrContext_::recv_window_mutex, resolve_ipv4_addr(), PotrContext_::role, PotrContext_::send_queue, PotrGlobalConfig::send_queue_depth, PotrContext_::send_window, PotrContext_::send_wire_buf, PotrContext_::service, PotrServiceDef::service_id, PotrContext_::sock, PotrServiceDef::src_addr, PotrContext_::src_addr_resolved, PotrServiceDef::src_port, PotrContext_::tcp_conn_fd, PotrGlobalConfig::tcp_health_interval_ms, PotrGlobalConfig::tcp_health_timeout_ms, PotrContext_::tcp_listen_sock, PotrContext_::tcp_send_mutex, PotrContext_::tcp_state_cv, PotrContext_::tcp_state_mutex, PotrServiceDef::type, window_init(), and PotrGlobalConfig::window_size.

Referenced by potrOpenServiceFromConfig().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ potrOpenServiceFromConfig()

POTR_EXPORT int POTR_API potrOpenServiceFromConfig | ( | const char * | config_path,
|  | int64_t | service_id,
|  | PotrRole | role,
|  | PotrRecvCallback | callback,
|  | PotrHandle * | handle )
| extern

設定ファイルから指定サービスを開きます。

Parameters

  [in] | config_path | 設定ファイルのパス。
  [in] | service_id | 開くサービスの ID。
  [in] | role | 役割種別。POTR_ROLE_SENDER または POTR_ROLE_RECEIVER。
  [in] | callback | イベント発生時に呼び出されるコールバック関数 (PotrRecvCallback)。 POTR_ROLE_RECEIVER の場合は必須。データ受信・接続検知・切断検知を受け取る。 POTR_ROLE_SENDER の場合は通常 NULL を指定すること。 ただし POTR_TYPE_TCP_BIDIR および POTR_TYPE_UNICAST_BIDIR では SENDER にもコールバックが必須。これらの種別では POTR_ROLE_SENDER でも callback が NULL の場合は失敗を返します。
  [out] | handle | 成功時にセッションハンドルを格納するポインタ。

Returns
  成功時は POTR_SUCCESS、失敗時は POTR_ERROR を返します。

設定ファイルを解析してサービス定義を取得し、potrOpenService() を呼び出します。
role と callback の組み合わせが不正な場合は POTR_ERROR を返します。
role と設定ファイルの IP アドレスが不整合 (bind 失敗など) の場合も POTR_ERROR を返します。
通信種別・役割に応じて以下のソケット設定を行います。

通信種別 | 役割 | bind アドレス | bind ポート
--- | --- | --- | ---
POTR_TYPE_UNICAST | 送信者 | src_addr | src_port
POTR_TYPE_UNICAST | 受信者 | dst_addr | dst_port
POTR_TYPE_MULTICAST | 送信者 | INADDR_ANY | src_port
POTR_TYPE_MULTICAST | 受信者 | INADDR_ANY | dst_port
POTR_TYPE_BROADCAST | 送信者 | src_addr | src_port
POTR_TYPE_BROADCAST | 受信者 | INADDR_ANY | dst_port

POTR_ROLE_RECEIVER の場合、内部で受信スレッドを起動します。

使用例 (受信者)
  void on_recv(int64_t service_id, PotrPeerId peer_id,
  PotrEvent event, const void *data, size_t len) {
  (void)peer_id; // 1:1 モードでは常に POTR_PEER_NA
  if (event == POTR_EVENT_CONNECTED)
  printf("service %" PRId64 ": connected\n", service_id);
  else if (event == POTR_EVENT_DISCONNECTED)
  printf("service %" PRId64 ": disconnected\n", service_id);
  else
  printf("service %" PRId64 ": received %zu bytes\n", service_id, len);
  }
  PotrHandle handle;
  if (potrOpenServiceFromConfig("porter-services.conf", 1001,
  POTR_ROLE_RECEIVER, on_recv, &handle) == POTR_SUCCESS) {
  // 受信待機中 (受信スレッドが動作)
  potrCloseService(handle);
  }
  potrOpenServiceFromConfig
  POTR_EXPORT int POTR_API potrOpenServiceFromConfig(const char *config_path, int64_t service_id, PotrRole role, PotrRecvCallback callback, PotrHandle *handle)
  設定ファイルから指定サービスを開きます。
  Definition potrOpenServiceFromConfig.c:22

使用例 (送信者)
  PotrHandle handle;
  if (potrOpenServiceFromConfig("porter-services.conf", 1001,
  POTR_ROLE_SENDER, NULL, &handle) == POTR_SUCCESS) {
  potrSend(handle, POTR_PEER_NA, "hello", 5, 0);
  potrCloseService(handle);
  }

スレッド セーフティ
  本関数はスレッドセーフです。
  異なるスレッドから独立したハンドルを取得するために並行して呼び出すことができます。
  ただし取得したハンドルはスレッドセーフではありません。
  同一ハンドルに対する操作は 1 スレッドから行ってください。

Warning
  handle が NULL の場合は失敗を返します。
  config_path が NULL または存在しない場合は失敗を返します。
  指定した service_id が設定ファイルに存在しない場合は失敗を返します。
  POTR_ROLE_RECEIVER かつ callback が NULL の場合は失敗を返します。
  POTR_ROLE_SENDER かつ callback が NULL でない場合は失敗を返します。
  ただし POTR_TYPE_TCP_BIDIR および POTR_TYPE_UNICAST_BIDIR では SENDER にも
  コールバックが必須であり、この場合 callback が NULL の場合は失敗を返します。

Definition at line 22 of file potrOpenServiceFromConfig.c.

References config_load_global(), config_load_service(), POTR_API, POTR_ERROR, POTR_EXPORT, POTR_LOG, POTR_SUCCESS, POTR_TRACE_ERROR, POTR_TRACE_VERBOSE, and potrOpenService().

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ potrSend()

POTR_EXPORT int POTR_API potrSend | ( | PotrHandle | handle,
|  | PotrPeerId | peer_id,
|  | const void * | data,
|  | size_t | len,
|  | int | flags )
| extern

メッセージを送信します。

Parameters

  [in] | handle | potrOpenService() で取得したセッションハンドル。
  [in] | peer_id | 送信先ピア識別子。 N:1 モード: 有効なピア ID (POTR_PEER_NA / POTR_PEER_ALL 以外) を指定します。 N:1 モード: POTR_PEER_ALL を指定すると全接続ピアへ一斉送信します。 N:1 モード: POTR_PEER_NA を指定すると POTR_ERROR を返します。 1:1 モードおよびその他の通信種別: POTR_PEER_NA または POTR_PEER_ALL を指定します (通常は POTR_PEER_NA を使用)。
  [in] | data | 送信するメッセージへのポインタ。
  [in] | len | 送信するメッセージのバイト数。
  [in] | flags | 送信オプションフラグ。以下のフラグを論理和で組み合わせて指定します。 0 を指定すると非圧縮・ノンブロッキング送信になります。

フラグ | 説明
--- | ---
POTR_SEND_COMPRESS | メッセージを圧縮して送信します。
POTR_SEND_BLOCKING | ブロッキング送信を行います。

Returns
  成功時は POTR_SUCCESS、失敗時は POTR_ERROR を返します。

通信種別に応じて以下の宛先へ UDP パケットを送信します。

通信種別 | 送信先
--- | ---
POTR_TYPE_UNICAST | 接続相手の dst_port 宛にユニキャスト送信
POTR_TYPE_MULTICAST | multicast_group:dst_port へ送信
POTR_TYPE_BROADCAST | broadcast_addr:dst_port へ送信
POTR_TYPE_UNICAST_BIDIR (N:1) | peer_id で指定したピアへ送信

compress に POTR_SEND_COMPRESS を指定した場合、内部で圧縮処理を行ってから送信します。
圧縮後のサイズが元のサイズ以上になった場合は、自動的に非圧縮で送信します。
受信側の PotrRecvCallback には、解凍済みの元メッセージが渡されます。
送受信ともにフラグメント化と組み合わせて使用できます。

ノンブロッキング送信 (flags に POTR_SEND_BLOCKING を指定しない場合)
  メッセージを内部送信キューに登録して即座に返ります。
  実際の sendto はバックグラウンド送信スレッドが非同期に実行します。
  キューが満杯の場合は空きが生じるまで待機してからメッセージを登録し、登録後に返ります。

ブロッキング送信 (flags に POTR_SEND_BLOCKING を指定した場合)
  呼び出し前に滞留しているノンブロッキング送信のメッセージが すべて sendto 完了するまで待機します。
  その後、本呼び出しのメッセージをキューを通じて sendto して返ります。
  本関数が返った時点で、自身のメッセージの sendto は完了しています。

Note
  圧縮フォーマットには raw DEFLATE (RFC 1951) を使用します。
  Linux (zlib) と Windows (Compression API MSZIP|COMPRESS_RAW) は 同一フォーマットを出力するため、クロスプラットフォーム通信に対応します。
  圧縮効果がない場合 (圧縮後サイズ >= 元サイズ) は、アプリケーションへの通知なしに 内部で非圧縮に切り替えて送信します。送受信のデータ内容に影響はありません。

スレッド セーフティ
  本関数はスレッドセーフではありません。
  同一ハンドルへの並行呼び出しは未定義動作です。
  送信は 1 スレッドから行ってください。

Warning
  handle が NULL の場合は失敗を返します。
  data が NULL の場合は失敗を返します。
  len が 0 の場合は失敗を返します。
  len が POTR_MAX_MESSAGE_SIZE を超える場合は失敗を返します。
  送信スレッドが停止している場合 (potrCloseService 呼び出し後など) は失敗を返します。
  N:1 モードで peer_id = POTR_PEER_NA (0) を指定した場合は失敗を返します。
  TCP 通信種別 (POTR_TYPE_TCP / POTR_TYPE_TCP_BIDIR) で全 TCP path が切断中に
  呼び出した場合は POTR_ERROR_DISCONNECTED (1) を返します
  (connect スレッドが非同期に接続を試みている間)。

Definition at line 88 of file potrSend.c.

References PotrPeerContext_::active, PotrContext_::compress_buf, PotrContext_::compress_buf_size, PotrContext_::global, PotrContext_::is_multi_peer, PotrGlobalConfig::max_message_size, PotrContext_::max_peers, peer_find_by_id(), PotrPeerContext_::peer_id, PotrContext_::peers, PotrContext_::peers_mutex, POTR_API, potr_compress(), POTR_ERROR, POTR_ERROR_DISCONNECTED, POTR_EXPORT, POTR_FLAG_COMPRESSED, potr_is_raw_type(), potr_is_tcp_type(), POTR_LOG, POTR_MUTEX_LOCK_LOCAL, POTR_MUTEX_UNLOCK_LOCAL, POTR_PEER_ALL, POTR_PEER_NA, POTR_SEND_BLOCKING, POTR_SEND_COMPRESS, POTR_SUCCESS, POTR_TRACE_ERROR, POTR_TRACE_VERBOSE, send_to_peer(), PotrContext_::service, PotrServiceDef::service_id, PotrContext_::tcp_active_paths, and PotrServiceDef::type.

Referenced by bidir_send_thread_func(), and main().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ potrDisconnectPeer()

POTR_EXPORT int POTR_API potrDisconnectPeer | ( | PotrHandle | handle,
|  | PotrPeerId | peer_id )
| extern

指定ピアを切断します (N:1 モード専用)。

Parameters

  [in] | handle | potrOpenService() で取得したセッションハンドル。
  [in] | peer_id | 切断するピアの識別子 (POTR_PEER_NA および POTR_PEER_ALL 以外)。

Returns
  成功時は POTR_SUCCESS、失敗時は POTR_ERROR を返します。

指定したピアへ FIN パケットを送信し、ピアのリソースを解放します。
切断完了後に POTR_EVENT_DISCONNECTED コールバックが発火します。
N:1 モード (unicast_bidir かつ src 情報省略) 専用です。
1:1 モードおよびその他の通信種別では POTR_ERROR を返します。

スレッド セーフティ
  本関数はスレッドセーフです。
  内部で peers_mutex により排他制御されるため、複数スレッドから並行して呼び出せます。
  ただし PotrRecvCallback の内部から本関数を呼び出すとデッドロックが発生します。
  コールバック内からの呼び出しは避けてください。

Warning
  handle が NULL の場合は失敗を返します。
  peer_id = POTR_PEER_NA または POTR_PEER_ALL の場合は失敗を返します。
  指定した peer_id が存在しない場合は失敗を返します。
  1:1 モードまたは N:1 モード以外で呼び出した場合は失敗を返します。

Definition at line 35 of file potrDisconnectPeer.c.

References PotrContext_::callback, PotrPeerContext_::health_alive, PotrContext_::is_multi_peer, peer_find_by_id(), peer_free(), PotrPeerContext_::peer_id, peer_send_fin(), PotrContext_::peers_mutex, POTR_API, POTR_ERROR, POTR_EVENT_DISCONNECTED, POTR_EXPORT, POTR_LOG, POTR_MUTEX_LOCK_LOCAL, POTR_MUTEX_UNLOCK_LOCAL, POTR_PEER_ALL, POTR_PEER_NA, POTR_SUCCESS, POTR_TRACE_ERROR, POTR_TRACE_INFO, PotrContext_::service, and PotrServiceDef::service_id.

Here is the call graph for this function:

## ◆ potrCloseService()

POTR_EXPORT int POTR_API potrCloseService | ( | PotrHandle | handle | ) |
| extern

サービスを閉じます。

Parameters

  [in] | handle | potrOpenService() で取得したセッションハンドル。

Returns
  成功時は POTR_SUCCESS、失敗時は POTR_ERROR を返します。

受信スレッドを停止し、ソケットをクローズしてリソースを解放します。
マルチキャストの場合はグループから離脱します。
本関数呼び出し後、handle は無効となります。

Note
  本関数呼び出し時、POTR_EVENT_DISCONNECTED コールバックは発火しません。
  アプリケーション自身が明示的にサービスを閉じる操作は、接続状態変化イベントとして通知しない設計です。
  UDP 通信種別の送信者 (POTR_ROLE_SENDER) が本関数を呼び出した場合は、POTR_FLAG_FIN パケットが送信されます。
  TCP 通信種別 (POTR_TYPE_TCP / POTR_TYPE_TCP_BIDIR) では close() による TCP 切断が FIN 相当として機能します。
  いずれの場合も、相手側では POTR_EVENT_DISCONNECTED が発火します。

スレッド セーフティ
  本関数はスレッドセーフではありません。
  同一ハンドルに対して他の porter API と並行して呼び出さないでください。
  本関数を呼び出す前に、同一ハンドルへのすべての potrSend() が完了していることを確認してください。

Warning
  handle が NULL の場合は失敗を返します。

Definition at line 120 of file potrCloseService.c.

References comm_recv_thread_stop(), PotrContext_::compress_buf, PotrContext_::crypto_buf, PotrContext_::frag_buf, PotrContext_::health_mutex, PotrContext_::health_running, PotrContext_::health_wakeup, PotrContext_::is_multi_peer, PotrServiceDef::multicast_group, PotrContext_::n_path, parse_ipv4_addr(), peer_table_destroy(), PotrContext_::peers, POTR_API, potr_connect_thread_stop(), POTR_ERROR, POTR_EXPORT, potr_health_thread_stop(), POTR_INVALID_SOCKET, potr_is_tcp_type(), POTR_LOG, POTR_MAX_PATH, potr_raw_base_type(), POTR_ROLE_SENDER, potr_send_queue_destroy(), potr_send_queue_wait_drained(), potr_send_thread_stop(), POTR_SUCCESS, POTR_TRACE_ERROR, POTR_TRACE_INFO, POTR_TRACE_VERBOSE, POTR_TYPE_MULTICAST, POTR_TYPE_TCP_BIDIR, PotrContext_::recv_buf, PotrContext_::recv_window, PotrContext_::recv_window_mutex, PotrContext_::role, PotrContext_::running, send_fin(), PotrContext_::send_queue, PotrContext_::send_thread_running, PotrContext_::send_window, PotrContext_::send_wire_buf, PotrContext_::service, PotrServiceDef::service_id, PotrContext_::sock, PotrContext_::src_addr_resolved, PotrContext_::tcp_send_mutex, PotrContext_::tcp_state_cv, PotrContext_::tcp_state_mutex, PotrServiceDef::type, and window_destroy().

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ potrLogConfig()

POTR_EXPORT int POTR_API potrLogConfig | ( | PotrLogLevel | level,
|  | const char * | log_file,
|  | int | console )
| extern

ロガーを設定します。

Parameters

  [in] | level | 出力する最低ログレベル。POTR_TRACE_NONE でログ無効 (デフォルト)。
  [in] | log_file | ログファイルのパス。NULL または空文字列を指定するとファイル出力なし。
  [in] | console | 0 以外を指定すると標準エラー出力 (stderr) にも出力します。

Returns
  成功時は POTR_SUCCESS、log_file が開けない場合は POTR_ERROR を返します。

本関数は potrOpenService() の前に呼び出してください。
複数回呼び出した場合は最後の設定が有効になります。

出力先

  OS | 出力先
  --- | ---
  Linux | syslog (trace-util 経由)、ログファイル (trace-util 経由、log_file 指定時)、stderr (trace-util 経由、console 指定時)
  Windows | ETW (trace-util 経由)、ログファイル (trace-util 経由、log_file 指定時)、stderr (trace-util 経由、console 指定時)

ログフォーマット
  OS トレース (syslog / ETW) およびファイルへの出力フォーマット:
  [file.c:line] message
  stderr への出力フォーマット (タイムスタンプは UTC、L はレベル文字):
  YYYY-MM-DD HH:MM:SS.mmm L [file.c:line] message

ログレベル一覧

  レベル | 値 | 出力内容
  --- | --- | ---
  POTR_TRACE_CRITICAL | 0 | 致命的エラー
  POTR_TRACE_ERROR | 1 | 操作失敗
  POTR_TRACE_WARNING | 2 | NACK・REJECT・回復可能な異常
  POTR_TRACE_INFO | 3 | サービス開始・終了・接続状態変化
  POTR_TRACE_VERBOSE | 4 | ソケット操作・設定値・パケット送受信・スレッド動作
  POTR_TRACE_NONE | 5 | ログ無効 (デフォルト)

使用例
  // INFO 以上をファイルと stderr に出力
  potrLogConfig(POTR_TRACE_INFO, "/var/log/porter.log", 1);
  // VERBOSE 以上をファイルのみに出力
  potrLogConfig(POTR_TRACE_VERBOSE, "/tmp/porter.log", 0);
  // ログを無効化
  potrLogConfig(POTR_TRACE_NONE, NULL, 0);
  potrLogConfig
  POTR_EXPORT int POTR_API potrLogConfig(PotrLogLevel level, const char *log_file, int console)
  ロガーを設定します。
  Definition potrLog.c:72
  POTR_TRACE_NONE
  @ POTR_TRACE_NONE
  ログ出力無効。TRACE_LV_NONE (5) と同値。
  Definition porter_type.h:339
  POTR_TRACE_INFO
  @ POTR_TRACE_INFO
  情報。TRACE_LV_INFO (3) と同値。
  Definition porter_type.h:337
  POTR_TRACE_VERBOSE
  @ POTR_TRACE_VERBOSE
  詳細情報 (デバッグ)。TRACE_LV_VERBOSE (4) と同値。
  Definition porter_type.h:338

スレッド セーフティ
  本関数はスレッドセーフです。
  出力制御は trace-util が内部で排他制御を行うため、ログを出力中のスレッドが存在する場合でも 安全に設定を変更できます。

Warning
  log_file に指定したパスが書き込み不可の場合は POTR_ERROR を返します。

Definition at line 72 of file potrLog.c.

References POTR_API, POTR_ERROR, POTR_EXPORT, POTR_SUCCESS, POTR_TRACE_NONE, and s_trace.

Referenced by main().

Here is the caller graph for this function:

## ◆ potrGetServiceType()

POTR_EXPORT int POTR_API potrGetServiceType | ( | const char * | config_path,
|  | int64_t | service_id,
|  | PotrType * | type )
| extern

設定ファイルから指定サービスの通信種別を取得します。

Parameters

  [in] | config_path | 設定ファイルのパス。
  [in] | service_id | 照会するサービスの ID。
  [out] | type | 成功時に通信種別 (PotrType) を格納するポインタ。

Returns
  成功時は POTR_SUCCESS、失敗時は POTR_ERROR を返します。

設定ファイルを解析して指定サービスの通信種別を返します。
potrOpenService() の前に呼び出すことで、ロール・コールバックの要否を アプリケーション側で判断できます。
本関数はソケットの作成や通信スレッドの起動を行いません。

使用例
  PotrType type;
  if (potrGetServiceType("porter-services.conf", 1031, &type) == POTR_SUCCESS) {
  if (type == POTR_TYPE_UNICAST_BIDIR) {
  // unicast_bidir: コールバックが必須
  potrOpenService("porter-services.conf", 1031,
  POTR_ROLE_SENDER, on_recv, &handle);
  }
  }
  potrGetServiceType
  POTR_EXPORT int POTR_API potrGetServiceType(const char *config_path, int64_t service_id, PotrType *type)
  設定ファイルから指定サービスの通信種別を取得します。
  Definition potrGetServiceType.c:20
  PotrType
  PotrType
  通信種別。
  Definition porter_type.h:85
  POTR_TYPE_UNICAST_BIDIR
  @ POTR_TYPE_UNICAST_BIDIR
  双方向 1:1 通信 (UDP ユニキャスト)。
  Definition porter_type.h:94

スレッド セーフティ
  本関数はスレッドセーフです。
  グローバルな共有状態にアクセスしないため、複数スレッドから並行して呼び出せます。

Warning
  config_path または type が NULL の場合は失敗を返します。
  指定した service_id が設定ファイルに存在しない場合は失敗を返します。

Definition at line 20 of file potrGetServiceType.c.

References config_load_service(), POTR_API, POTR_ERROR, POTR_EXPORT, POTR_SUCCESS, and PotrServiceDef::type.

Referenced by main().

Here is the call graph for this function:
Here is the caller graph for this function: