@aptpod/iscp-ts
Version:
iSCP 2.0 client library for TypeScript
532 lines (531 loc) • 19.2 kB
TypeScript
import { Encoding } from './encoding';
import { DownstreamFilter, DataId, QoS, BaseTime } from './message';
import { Connector, EncodingName, NegotiationParams } from './transport';
import { LogLevel, EventListenerOptions, UpstreamCall as Model$UpstreamCall, UpstreamReplyCall as Model$UpstreamReplyCall, DownstreamCall as Model$DownstreamCall, DownstreamReplyCall as Model$DownstreamReplyCall } from './model';
import { Upstream } from './upstream';
import { Downstream } from './downstream';
import { FlushPolicy } from './flush-policy';
/**
* iSCP接続時に{@link Conn}.{@link Conn.connect}に指定するコンフィグです。
* @category Connection
*/
export interface ConnConfig {
/** 接続先のアドレス。`127.0.0.1:8080` 形式。 */
address: string;
/** トランスポートのコネクターです。 */
connector: Connector;
/**
* エンコーディング名。
* @default {@link Conn}.{@link Conn.DEFAULT_ENCODING_NAME}
*/
encoding?: EncodingName;
/** ノードID。 */
nodeId?: string;
/**
* Ping間隔（秒）。
* @default {@link Conn}.{@link Conn.DEFAULT_PING_INTERVAL}
*/
pingInterval?: number;
/**
* Pingタイムアウト（秒）。タイムアウトが発生した場合トランスポートを切断します。
* @default {@link Conn}.{@link Conn.DEFAULT_PING_TIMEOUT}
*/
pingTimeout?: number;
/** プロジェクトUUID。 */
projectUuid?: string;
/** トークンソース。iSCPコネクションを開くたびに、このメソッドをコールしトークンを取得します。 */
tokenSource?: TokenSource;
/**
* ログの出力レベル。
* @default {@link LOG_LEVEL}.{@link LOG_LEVEL.WARNING}
*/
logLevel?: LogLevel;
/**
* 自動で再接続するか指定します。
* @default {@link Conn}.{@link Conn.DEFAULT_AUTO_RECONNECT}
*/
autoReconnect?: boolean;
/**
* 自動で再接続する際の、リトライ間隔の初期値を秒で指定します。
* 再接続に失敗すると、リトライ間隔を倍にしながらリトライを繰り返します。
* @default {@link Conn}.{@link Conn.DEFAULT_RECONNECT_BASE_INTERVAL}
*/
reconnectBaseInterval?: number;
/**
* 自動で再接続する際の、リトライ間隔を秒で指定します。
* @default {@link Conn}.{@link Conn.DEFAULT_RECONNECT_MAX_INTERVAL}
*/
reconnectMaxInterval?: number;
}
/**
* ダウンストリームを開く時に{@link Conn}.{@link Conn.openDownstream}に指定するコンフィグです。
* @category Connection
*/
export interface DownstreamConfig {
/** ダウンストリームフィルタのリスト。 */
filters: DownstreamFilter[];
/** データIDのリスト。 */
dataIds?: DataId[];
/**
* QoS。
* @default {@link Conn}.{@link Conn.DEFAULT_QOS}
*/
qos?: QoS;
/**
* 有効期限（秒）。
* @default {@link Conn}.{@link Conn.DEFAULT_EXPIRY_INTERVAL}
*/
expiryInterval?: number;
/**
* Ack返却間隔（秒）。
* @default {@link Conn}.{@link Conn.DEFAULT_ACK_INTERVAL}
*/
ackInterval?: number;
/**
* 空チャンク省略フラグ。trueの場合、{@link DownstreamChunk}内の{@link DownstreamChunk.dataPointGroups}が空の時、{@link DownstreamChunk}の送信を省略します。
* @default {@link Conn}.{@link Conn.DEFAULT_OMIT_EMPTY_CHUNK}
*/
omitEmptyChunk?: boolean;
}
/**
* アップストリームを開く時に{@link Conn}.{@link Conn.openUpstream}に指定するコンフィグです。
* @category Connection
*/
export interface UpstreamConfig {
/** セッションID。 */
sessionId: string;
/**
* 有効期限（秒）。
* @default {@link Conn}.{@link Conn.DEFAULT_EXPIRY_INTERVAL}
*/
expiryInterval?: number;
/** データIDのリスト。 */
dataIds?: DataId[];
/**
* QoS。
* @default {@link Conn}.{@link Conn.DEFAULT_QOS}
*/
qos?: QoS;
/**
* Ack返却間隔（秒）。
* @default {@link Conn}.{@link Conn.DEFAULT_ACK_INTERVAL}
*/
ackInterval?: number;
/**
* 永続化するかどうか。
* @default {@link Conn}.{@link Conn.DEFAULT_PERSIST}
*/
persist?: boolean;
/**
* データポイントのフラッシュポリシー。
* @default {@link FlushPolicy}.{@link FlushPolicy.intervalOrBufferSize}()の戻り値。
*/
flushPolicy?: FlushPolicy;
/**
* クローズのタイムアウト（秒）。
* @default {@link Conn}.{@link Conn.DEFAULT_CLOSE_TIMEOUT}
*/
closeTimeout?: number;
/**
* アップストリームクローズ時にセッションをクローズするかどうか。
* @default {@link Conn}.{@link Conn.DEFAULT_CLOSE_SESSION}
*/
closeSession?: boolean;
}
/**
* トークンソースです。
* @returns トークン
* @category Connection
*/
export type TokenSource = () => Promise<string>;
/**
* 基準時刻を送信する時に{@link Conn}.{@link Conn.sendBaseTime}に指定するオプションです。
* @category Connection
*/
export interface SendBaseTimeOptions {
/**
* 永続化するかどうか。
* @default {@link Conn}.{@link Conn.DEFAULT_SEND_BASE_TIME_OPTIONS_PERSIST}
*/
persist?: boolean;
}
type ConnEvent = typeof Conn.EVENT;
/**
* iSCPを切断した時のイベントです。
* @category Connection
*/
export declare class DisconnectedEvent {
/** 内部エラーが発生した場合の例外。 */
error?: Error;
constructor(init: {
error?: DisconnectedEvent['error'];
});
}
/**
* iSCPの再接続を開始した時のイベントです。
* @category Connection
*/
export declare class ReconnectingEvent {
/** 再接続を開始する原因となった例外。 */
error: Error;
constructor(init: {
error: ReconnectingEvent['error'];
});
}
/**
* {@link DownstreamCall}を取得するイベントリスナーです。
* {@link Conn}の{@link Conn.addEventListener}、{@link Conn.removeEventListener}で指定します。
* @category Connection
*/
export type CallEventListener = (downstreamCall: Model$DownstreamCall) => void;
/**
* {@link DownstreamReplyCall}を取得するイベントリスナーです。
* {@link Conn}の{@link Conn.addEventListener}、{@link Conn.removeEventListener}で指定します。
* @category Connection
*/
export type ReplyCallEventListener = (downstreamReplyCall: Model$DownstreamReplyCall) => void;
/**
* {@link DisconnectedEvent}を取得するイベントリスナーです。
* {@link Conn}の{@link Conn.addEventListener}、{@link Conn.removeEventListener}で指定します。
* @category Connection
*/
export type DisconnectedEventListener = (event: DisconnectedEvent) => void;
/**
* {@link ReconnectingEvent}を取得するイベントリスナーです。
* {@link Conn}の{@link Conn.addEventListener}、{@link Conn.removeEventListener}で指定します。
* @category Connection
*/
export type ReconnectingEventListener = (event: ReconnectingEvent) => void;
/**
* iSCPが再接続した時のイベントを取得するイベントリスナーです。
* {@link Conn}の{@link Conn.addEventListener}、{@link Conn.removeEventListener}で指定します。
* @category Connection
*/
export type ReconnectedEventListener = () => void;
/**
* iSCPのコネクションを表すクラスです。
*
* @category Connection
*
* @attention
* このクラスのオブジェクトは、必ず{@link Conn}の{@link Conn.connect}を使用して生成してください。
*
* @example
* ```ts
* const example = async () => {
* const conn = await Conn.connect(...)
* try {
* // ...
* } finally {
* await conn.close()
* }
* }
* ```
*/
export declare class Conn {
#private;
/** エンコーディング名のデフォルト値です。 */
static readonly DEFAULT_ENCODING_NAME: "proto";
/** Ping間隔のデフォルト値です（秒）。 */
static readonly DEFAULT_PING_INTERVAL = 10;
/** Pingタイムアウトのデフォルト値です（秒）。 */
static readonly DEFAULT_PING_TIMEOUT = 1;
/** 有効期限のデフォルト値です（秒）。 */
static readonly DEFAULT_EXPIRY_INTERVAL = 1;
/** Ack返却間隔のデフォルト値です（秒）。 */
static readonly DEFAULT_ACK_INTERVAL = 1;
/** QoSのデフォルト値です。 */
static readonly DEFAULT_QOS: 1;
/** 空チャンク省略フラグのデフォルト値です。 */
static readonly DEFAULT_OMIT_EMPTY_CHUNK = false;
/** 永続化するかどうかのデフォルト値です。 */
static readonly DEFAULT_PERSIST = false;
/** クローズのタイムアウトのデフォルト値です（秒）。 */
static readonly DEFAULT_CLOSE_TIMEOUT = 1;
/** アップストリームクローズ時にセッションをクローズするかどうかのデフォルト値です。 */
static readonly DEFAULT_CLOSE_SESSION = false;
/** 自動で再接続するかのデフォルト値です。 */
static readonly DEFAULT_AUTO_RECONNECT = true;
/** 自動で再接続する際の、リトライ間隔の初期値のデフォルト値です（秒）。 */
static readonly DEFAULT_RECONNECT_BASE_INTERVAL = 0.1;
/** 自動で再接続する際の、リトライ間隔のデフォルト値です（秒）。 */
static readonly DEFAULT_RECONNECT_MAX_INTERVAL = 5;
/** 基準時刻を送信する際に永続化するかどうかのデフォルト値です。 */
static readonly DEFAULT_SEND_BASE_TIME_OPTIONS_PERSIST = false;
/**
* @event イベント
*/
static EVENT: {
/**
* E2Eコールを受信した時に呼び出されるイベントです。
*/
readonly CALL: "call";
/**
* E2Eリプライコールを受信した時に呼び出されるイベントです。
*/
readonly REPLY_CALL: "replyCall";
/**
* iSCPが切断された時に呼び出されるイベントです。
*/
readonly DISCONNECTED: "disconnected";
/**
* iSCPの再接続が開始された時に呼び出されるイベントです。
*/
readonly RECONNECTING: "reconnecting";
/**
* iSCPの再接続が成功した時に呼び出されるイベントです。
*/
readonly RECONNECTED: "reconnected";
};
/**
* iSCP接続を行い{@link Conn}を返却します。
*/
static connect(config: ConnConfig): Promise<Conn>;
/**
* @internal
*/
constructor(config: {
logLevel?: LogLevel;
address: string;
negotiationParams: NegotiationParams;
connector: Connector;
encoding: Encoding;
nodeId?: string;
protocolVersion: string;
pingInterval: number;
pingTimeout: number;
projectUuid?: string;
tokenSource?: TokenSource;
autoReconnect: boolean;
reconnectBaseInterval: number;
reconnectMaxInterval: number;
});
/**
* ノードIDを取得します。
* @returns ノードID
*/
get nodeId(): string | undefined;
/**
* Ping間隔（秒）を取得します。
* @returns Ping間隔（秒）
*/
get pingInterval(): number;
/**
* Pingタイムアウト（秒）を取得します。
* @returns Pingタイムアウト（秒）
*/
get pingTimeout(): number;
/**
* プロジェクトUUIDを取得します。
* @returns プロジェクトUUID
*/
get projectUuid(): string | undefined;
/**
* アドレスを取得します。
* @returns アドレス
*/
get address(): string;
/**
* エンコーディング名を取得します。
* @returns エンコーディング名
*/
get encoding(): EncodingName;
/**
* トランスポート名を取得します。
* @returns トランスポート名
*/
get transport(): import("./transport").TransportName;
/**
* アップストリームを開きます。
* @returns アップストリーム
*/
openUpstream(config: UpstreamConfig): Promise<Upstream>;
/**
* ダウンストリームを開きます。
* @returns ダウンストリーム
*/
openDownstream(config: DownstreamConfig): Promise<Downstream>;
/**
* E2Eコールを送信します。
* @param upstreamCall アップストリームコール。
* @returns コールID。
*/
sendCall(upstreamCall: Model$UpstreamCall): Promise<string>;
/**
* E2Eコールのリプライを送信します。
* @param replyCall アップストリームリプライコール。
* @returns コールID。
*/
sendReplyCall(replyCall: Model$UpstreamReplyCall): Promise<string>;
/**
* E2Eコールを送信し、リプライコールを受信するまで待ちます。
* @param upstreamCall アップストリームコール。
* @returns ダウンストリームリプライコール
*/
sendCallAndWaitReplyCall(upstreamCall: Model$UpstreamCall): Promise<Model$DownstreamReplyCall>;
/**
* 基準時刻を送信します。
* @param baseTime 基準時刻。
* @param options 基準時刻を送信する際のオプションを指定します。
*/
sendBaseTime(baseTime: BaseTime, options?: SendBaseTimeOptions): Promise<void>;
/**
* コネクションを閉じます。
*/
close(): Promise<void>;
/**
* コネクションが閉じるまで待機します。
*/
waitClosed(): Promise<void>;
/**
* {@link Conn.EVENT}.CALLのイベントリスナーを追加します。
* E2Eコールを受信した時にイベントリスナーが呼び出されます。
*
* @example
* ```ts
* conn.addEventListener(Conn.EVENT.CALL, (downstreamCall: DownstreamCall) => {
* ...
* })
* ```
*/
addEventListener(name: ConnEvent['CALL'], listener: CallEventListener, options?: EventListenerOptions): void;
/**
* {@link Conn.EVENT}.REPLY_CALLのイベントリスナーを追加します。
* E2Eリプライコールを受信した時にイベントリスナーが呼び出されます。
*
* @example
* ```ts
* conn.addEventListener(Conn.EVENT.REPLY_CALL, (downstreamReplyCall: DownstreamReplyCall) => {
* ...
* })
* ```
*/
addEventListener(name: ConnEvent['REPLY_CALL'], listener: ReplyCallEventListener, options?: EventListenerOptions): void;
/**
* {@link Conn.EVENT}.DISCONNECTEDのイベントリスナーを追加します。
* iSCPが切断された時にイベントリスナーが呼び出されます。
*
* @example
* ```ts
* conn.addEventListener(Conn.EVENT.DISCONNECTED, (disconnectedEvent) => {
* ...
* })
* ```
*/
addEventListener(name: ConnEvent['DISCONNECTED'], listener: DisconnectedEventListener, options?: EventListenerOptions): void;
/**
* {@link Conn.EVENT}.RECONNECTINGのイベントリスナーを追加します。
* iSCPの再接続が開始された時にイベントリスナーが呼び出されます。
*
* @example
* ```ts
* conn.addEventListener(Conn.EVENT.RECONNECTING, () => {
* ...
* })
* ```
*/
addEventListener(name: ConnEvent['RECONNECTING'], listener: ReconnectingEventListener, options?: EventListenerOptions): void;
/**
* {@link Conn.EVENT}.RECONNECTEDのイベントリスナーを追加します。
* iSCPの再接続が成功した時にイベントリスナーが呼び出されます。
*
* @example
* ```ts
* conn.addEventListener(Conn.EVENT.RECONNECTED, () => {
* ...
* })
* ```
*/
addEventListener(name: ConnEvent['RECONNECTED'], listener: ReconnectedEventListener, options?: EventListenerOptions): void;
/**
* {@link Conn.EVENT}.CALLのイベントリスナーを削除します。
* {@link addEventListener}で指定したイベントリスナーを指定してください。
*
* @example
* ```ts
* const listener = (downstreamCall: DownstreamCall) => {
* ...
* }
*
* conn.addEventListener(Conn.EVENT.CALL, listener)
*
* ...
*
* conn.removeEventListener(Conn.EVENT.CALL, listener)
* ```
*/
removeEventListener(name: ConnEvent['CALL'], listener: CallEventListener, options?: EventListenerOptions): void;
/**
* {@link Conn.EVENT}.REPLY_CALLのイベントリスナーを削除します。
* {@link addEventListener}で指定したイベントリスナーを指定してください。
*
* @example
* ```ts
* const listener = (downstreamReplyCall: DownstreamReplyCall) => {
* ...
* }
*
* conn.addEventListener(Conn.EVENT.REPLY_CALL, listener)
*
* ...
*
* conn.removeEventListener(Conn.EVENT.REPLY_CALL, listener)
* ```
*/
removeEventListener(name: ConnEvent['REPLY_CALL'], listener: ReplyCallEventListener, options?: EventListenerOptions): void;
/**
* {@link Conn.EVENT}.DISCONNECTEDのイベントリスナーを削除します。
* {@link addEventListener}で指定したイベントリスナーを指定してください。
*
* @example
* ```ts
* const listener = (closedEvent: DisconnectedEvent) => {
* ...
* }
*
* conn.addEventListener(Conn.EVENT.DISCONNECTED, listener)
*
* ...
*
* conn.removeEventListener(Conn.EVENT.DISCONNECTED, listener)
* ```
*/
removeEventListener(name: ConnEvent['DISCONNECTED'], listener: DisconnectedEventListener): void;
/**
* {@link Conn.EVENT}.RECONNECTINGのイベントリスナーを削除します。
* {@link addEventListener}で指定したイベントリスナーを指定してください。
*
* @example
* ```ts
* const listener = () => {
* ...
* }
*
* conn.addEventListener(Conn.EVENT.RECONNECTING, listener)
*
* ...
*
* conn.removeEventListener(Conn.EVENT.RECONNECTING, listener)
* ```
*/
removeEventListener(name: ConnEvent['RECONNECTING'], listener: ReconnectingEventListener): void;
/**
* {@link Conn.EVENT}.RECONNECTEDのイベントリスナーを削除します。
* {@link addEventListener}で指定したイベントリスナーを指定してください。
*
* @example
* ```ts
* const listener = () => {
* ...
* }
*
* conn.addEventListener(Conn.EVENT.RECONNECTED, listener)
*
* ...
*
* conn.removeEventListener(Conn.EVENT.RECONNECTED, listener)
* ```
*/
removeEventListener(name: ConnEvent['RECONNECTED'], listener: ReconnectedEventListener): void;
}
export {};