Telegramのボットを作成するという一般的な熱意を背景に、ToxインスタントメッセンジャーAPIについて説明し、簡単なエコーボットの例を使用して、簡単かつ迅速に独自のボットを作成する方法を示します。

はじめに

Toxカーネル（ githubのtoxcore ）は3つの部分で構成されています。

• 実際、 ToxCoreはコアそのものであり、連絡先、メッセージ、ファイル、アバター、ステータス、グループチャットを管理できます。
• ToxAV-音声およびビデオ通話のサブシステム。
• ToxDNS -DNSへのクエリを介して人間が読めるアドレス（電子メールまたはJabberIDの類似物）からToxIDを取得するためのサブシステム。

連絡先ユニットはToxID （API用語では「アドレス」）-長さ76文字の16進文字列で、エンコードは次のとおりです。

• 公開鍵（32バイトまたは64文字）。
• スパム "nospam"（4バイトまたは8文字）に対する保護-ランダムデータセット。その変更により、以前に許可された連絡先を引き続き維持できますが、新しい連絡先からの要求は無視できます。
• チェックサム（2バイトまたは4文字）-公開キーと値「nospam」のXOR操作は、ToxIDの正確性を迅速に確認するのに役立ちます。

Tox APIの一般的な作業サイクルは、次の形式で順番に表すことができます。

1. カーネルの初期化（ tox_new ）-ここで、プロトコル（IPv4 / IPv6、UDP / TCP）、プロキシ設定（HTTP / SOCKS5）、使用するポートの範囲を設定し、以前に保存した状態を連絡先のリストとともにダウンロードします。
2. イベント処理のためのコールバック関数の設定（ tox_callback_ * ）-イベントハンドラーはメインループ（4）から呼び出され、アプリケーションのメインロジックは通常それらに集中します。
3. 1つ以上のDHTノードへの接続（ tox_bootstrap ）。
4. メインデューティサイクル（ tox_iterate ）およびイベント処理。
5. tox_iteration_intervalを一時停止し、前の手順に戻ります。

なぜなら Tox APIの知識を得るための主な方法は、ソースコード（Cで記述）を読むことです。さらにプレゼンテーションを単純化するために、Python言語のラッパー（ githubのpytoxcore ）を使用します。 ソースからライブラリの自己アセンブリを行いたくない人のために、一般的なディストリビューション用の既製のバイナリパッケージへのリンクもあります。



Pythonラッパーを使用する場合、次の方法でライブラリのヘルプを取得できます。

$ python >>> from pytoxcore import ToxCore >>> help(ToxCore) class ToxCore(object) | ToxCore object ... | tox_add_tcp_relay(...) | tox_add_tcp_relay(address, port, public_key) | Adds additional host:port pair as TCP relay. | This function can be used to initiate TCP connections to different ports on the same bootstrap node, or to add TCP relays without using them as bootstrap nodes. | | tox_bootstrap(...) | tox_bootstrap(address, port, public_key) | Sends a "get nodes" request to the given bootstrap node with IP, port, and public key to setup connections. | This function will attempt to connect to the node using UDP. You must use this function even if Tox_Options.udp_enabled was set to false. ...
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

以下では、APIを操作する各ステップについてもう少し詳しく説明します。

カーネルの初期化

カーネルを初期化するために、 Tox_Options構造体がパラメーターとして使用されます。 Pythonでは、同じ名前のフィールドを持つ辞書にすることができます。 デフォルト値は、 tox_options_defaultメソッドを呼び出すことで取得できます。

 $ python >>> from pytoxcore import ToxCore >>> ToxCore.tox_options_default() {'start_port': 0L, 'proxy_host': None, 'tcp_port': 0L, 'end_port': 0L, 'udp_enabled': True, 'savedata_data': None, 'proxy_port': 0L, 'ipv6_enabled': True, 'proxy_type': 0L}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ここに：

• ipv6_enabled -IPv6の幸せな所有者かどうかに応じて、TrueまたはFalse。
• udp_enabled-プロキシを介して作業する場合を除き、Trueに設定することをお勧めします。 UDPはToxのネイティブプロトコルです。
• proxy_type-プロキシのタイプ、値を取ることができます：
  
  
  • TOX_PROXY_TYPE_NONE-プロキシを使用しません。
  • TOX_PROXY_TYPE_HTTP -HTTPプロキシ。
  • TOX_PROXY_TYPE_SOCKS5 -SOCKS5プロキシ（Torなど）。
• proxy_host-プロキシサーバーのホストまたはIPアドレス。
• proxy_port-プロキシサーバーポート（TOX_PROXY_TYPE_NONEについては無視されます）。
• start_port-許可されたポート範囲の開始ポート。
• end_port-許可されたポートの範囲の終了ポート。 開始ポートと終了ポートが0の場合、範囲が使用されます[33445、33545]。 ポートの1つだけがゼロの場合、単一のゼロ以外のポートが使用されます。 start_port> end_portの場合、それらは交換されます。
• tcp_port -TCPサーバーを上げるためのポート（リレー）; 0に設定すると、サーバーは無効になります。 TCPリレーを使用すると、他のユーザーがインスタンスを中間ノードとして使用できます（スーパーノードの概念）。
• savedata_data-ロードするデータ。存在しない場合はNone。

ほとんどの場合、 savedata_dataを除くすべてのパラメーターはデフォルトで残すことができます。

 #!/usr/bin/env python # -*- coding: utf-8 -*- import os from pytoxcore import ToxCore class EchoBot(ToxCore): def __init__(self): tox_options = ToxCore.tox_options_default() if os.path.isfile("tox.save"): with open("tox.save", "rb") as f: tox_options["savedata_data"] = f.read() super(EchoBot, self).__init__(tox_options)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

最初の起動時に、カーネルは公開キーと秘密キーを生成し、必要に応じて保存できます。

 class EchoBot(ToxCore): ... def save_data(self): with open("tox.save", "wb") as f: f.write(self.tox_get_savedata())
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

データは常にメモリに格納されるため、偶発的な障害から保護するために、定期的にデータを一時ファイルに保存し、（成功した場合は、アトミックに）メインデータファイルに置き換えることをお勧めします。



ユーザーに送信するためのアドレスの現在の値、公開鍵と秘密鍵、および「nospam」の値は、次の呼び出しによって取得できます。

• tox_self_get_address-現在のアドレス（ToxID）。
• tox_self_get_public_keyは公開鍵です。
• tox_self_get_secret_key-秘密鍵。
• tox_self_get_nospam / tox_self_set_nospam- 「nospam」の値の取得と設定。

 $ python >>> from pytoxcore import ToxCore >>> core = ToxCore(ToxCore.tox_options_default()) >>> core.tox_self_get_address() '366EA3B25BA31E3ADC4C476098A8686E4EAE87B04E4E4A3A3A0B865CBB9725704189FEDAEB26' >>> core.tox_self_get_public_key() '366EA3B25BA31E3ADC4C476098A8686E4EAE87B04E4E4A3A3A0B865CBB972570' >>> core.tox_self_get_secret_key() '86003764B4C99395E164024A17DCD0ECB80363C5976FF43ECE11637FA0B683F9' >>> core.tox_self_get_nospam() '4189FEDA'
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

カーネルの初期化後、 tox_self_set_nameおよびtox_self_set_status_messageを呼び出すことにより、ボットにニックネームと署名をいつでも設定できます。 名前はTOX_MAX_NAME_LENGTHを超えてはならず、署名はTOX_MAX_STATUS_MESSAGE_LENGTH （バイト単位のサイズ）を超えてはなりません。 アバターのインストールについては、以下で説明します。 技術的には、連絡先にファイルを送信します。

コールバック関数を設定する

Pythonラッパーでは、サポートされているコールバック関数への接続が自動的に行われます。 ハンドラー自体はToxCoreの子孫のメソッドであり、サフィックス* _cbを持つことができます。

 class EchoBot(ToxCore): ... def tox_self_connection_status_cb(self, connection_status): if connection_status == ToxCore.TOX_CONNECTION_NONE: print("Disconnected from DHT") elif connection_status == ToxCore.TOX_CONNECTION_TCP: print("Connected to DHT via TCP") elif connection_status == ToxCore.TOX_CONNECTION_UDP: print("Connected to DHT via UDP") else: raise NotImplementedError("Unknown connection_status: {0}".format(connection_status))
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

特定のハンドラーとその引数については、以下で説明します。

DHTノードに接続する

DHTノードは、IPアドレス、ポート番号、および公開鍵によって決定されます。 DHTノードの初期リストは、プロジェクトwikiにあります 。



Tox Client Guidelinesによると、クライアントは5秒ごとに、カーネルが接続の成功を報告するまで少なくとも4つのランダムノードへの接続を試行する必要があります（ tox_self_connection_status_cbを参照）。 ステータスファイルからロードする場合、クライアントはtox_iterateの最初の呼び出し後10秒以内に接続を試みてはならず、接続がない場合は上記の積極的な接続戦略を繰り返します。



常に連絡を取り合うことを計画しているボットの場合、これらの推奨事項は少し複雑に見えます。 独自のローカルDHTノードを上げることにより、接続に必要なDHTノードの数を減らすことができます。 ローカルノードを持つことの追加のプラスは、ローカルノードとの継続的な通信に加えて、Toxネットワーク自体の「強化」です。



ローカルノードを上げるには、 tox-bootstrapdデーモンをインストールして設定する必要があります。 toxcoreライブラリと一緒にアセンブルでき、開発者リポジトリからバイナリ形式で取得できます 。



デーモンの構成は/etc/tox-bootstrapd.confファイルで指定されており、 十分に文書化されています 。 デーモンの起動に関する追加情報は、対応するREADMEで入手できます。tox.pkgプロジェクトの deb-distributionsの場合、 tox-bootstrapdパッケージのインストールは十分です。 ローカルDHTノードの公開鍵は、デーモンの起動後にシステムログで確認できます。



したがって、DHTノードとデューティサイクルとの接続の簡略バージョンは、次のように表すことができます。

 class EchoBot(ToxCore): ... def run(self): checked = False self.tox_bootstrap("127.0.0.1", 33445, "366EA...72570") while True: status = self.tox_self_get_connection_status() if not checked and status != ToxCore.TOX_CONNECTION_NONE: checked = True if checked and status == ToxCore.TOX_CONNECTION_NONE: self.tox_bootstrap("127.0.0.1", 33445, "366EA...72570") checked = False self.tox_iterate() interval = self.tox_iteration_interval() time.sleep(interval / 1000.0)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

場合によっては、クライアントはtox_bootstrapをまったく呼び出さずに動作できます。このため、ネットワークの同じブロードキャストドメイン内で別のクライアントまたはDHTノードを起動する必要があります。 この機能により、少なくとも1人のクライアントがネットワークにアクセスし、リレーである場合、インターネットにアクセスしたり、外の世界と通信したりすることなく、ローカルネットワーク内で通信できます。

イベント処理

前に書いたように、Pythonでイベントハンドラーを接続するには、後継クラスに必要な引数を使用して必要なメソッドを追加するだけで十分です。例は、ボットがDHTネットワークに接続および切断されるときに呼び出される接続状態ハンドラーtox_self_connection_status_cbでした 。

連絡先を操作する

ボットが他のネットワーク参加者と対話するには、ボットの連絡先リストに追加する必要があります。 APIの用語では、連絡先は「友人」と呼ばれ、ToxCoreインスタンスの存続期間を通じて一意の整数（「 friend_number 」）で示されます。



別のクライアントがボットを連絡先リストに追加する要求を行うと、 tox_friend_request_cb（public_key、message）ハンドラーがボット側で呼び出されます 。ここで、

• public_keyは友人の公開鍵です。
• メッセージ - 「こんにちは、これはアバトです！」などの友人からのメッセージ 友達として私を追加しますか？」

ハンドラー内では、 tox_friend_add_norequestを呼び出して友達に人を追加するか、単にリクエストを無視することができます。 それ以降のすべてのイベントハンドラーは、フレンドIDとしてfriend_numberを使用します。これは、 tox_friend_by_public_keyを呼び出すことで公開キーから取得できます。



友人に連絡先を追加すると、ボット側で次のイベントが発生する場合があります。

• tox_friend_connection_status_cb（friend_number、connection_status） -友人の接続状態を変更します。connection_statusは値を取ることができます：
  
  
  • TOX_CONNECTION_NONEはオフラインの友達です。
  • TOX_CONNECTION_TCPはオンラインの友人であり、TCPで接続されています。
  • TOX_CONNECTION_UDPはオンラインの友人であり、UDPで接続されています。
• tox_friend_name_cb（friend_number、name） -友人のニックネームを変更します。
• tox_friend_status_message_cb（friend_number、message） -署名を変更します。
• tox_friend_status_cb（friend_number、status） -状態の変更。statusは値を取ることができます：
  
  
  • TOX_USER_STATUS_NONE-利用可能（「オンライン」）。
  • TOX_USER_STATUS_AWAY-出発しました。
  • TOX_USER_STATUS_BUSY-ビジー。
• tox_friend_message_cb（friend_number、message） -友人からのメッセージ。
• tox_friend_read_receipt_cb（friend_number、message_id） -tox_friend_send_messageによって送信された別のメッセージの受信（以下を参照）。

友人からメッセージを受信する際のエコーボットの場合は、返信するだけです。

 class EchoBot(ToxCore): ... def tox_friend_request_cb(self, public_key, message): self.tox_friend_add_norequest(public_key) def tox_friend_message_cb(self, friend_number, message): message_id = self.tox_friend_send_message(friend_number, ToxCore.TOX_MESSAGE_TYPE_NORMAL, message)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

友人へのメッセージの送信は、 tox_friend_send_messageメソッドを呼び出すことによって行われます。このメソッドは、メッセージ識別子message_idを返します。これは、各友人に固有の単調に増加する番号です。 パラメータとして、このメソッドは友人の識別子、メッセージのタイプ、およびメッセージ自体のテキストを受け入れます。 メッセージテキストには次の制限が課せられます。

• メッセージを空にすることはできません。
• メッセージはTOX_MAX_MESSAGE_LENGTH （バイト）より大きくすることはできません。長いメッセージは部分に分割する必要があります。

友人からのメッセージの処理に時間がかかる場合は、「メッセージセット」イベント（ tox_self_set_typing ）をランダムに送信することにより、ボットの動作を多様化できます。



友人のfriend_number値により、いつでも彼に関する次の情報を取得できます。

• tox_friend_get_connection_status-友人の現在のネットワークステータス（ tox_friend_connection_status_cbの最後の値）。
• tox_friend_get_name-友人の現在のニックネーム（ tox_friend_name_cbの最後の値）。
• tox_friend_get_status_message-友人の現在の署名（最後の値はtox_friend_status_message_cbです ）。
• tox_friend_get_status-友人の現在のステータス（ tox_friend_status_cbの最後の値）。
• tox_friend_get_last_online-オンラインで最後に表示された日付（unixtime）。

友達との追加操作：

• tox_self_get_friend_list_size-友達の数を取得します。
• tox_self_get_friend_list - friend_number人の友人のリストを取得します。
• tox_friend_delete-連絡先リストから友人を削除します。

ここではすべてがシンプルで直感的に見えます。 さらに、もう少し難しくなります。

ファイルを操作する

ファイル受信

友人がボットにファイルを送信すると、 tox_file_recv_cbイベントが発生します（friend_number、file_number、kind、file_size、filename） 。ここで、

• friend_number-友人の番号（「連絡先の操作」を参照）。
• file_number-ファイル番号。この友人から受信および送信されたファイルの現在のリスト内の一意の番号。
• kind-ファイルタイプ：
  
  
  • TOX_FILE_KIND_DATA-転送されるファイルは単純なファイルです。
  • TOX_FILE_KIND_AVATAR-転送されたファイルは友人のアバターです。
• file_size-ファイルサイズ。 TOX_FILE_KIND_AVATARの場合 、ファイルサイズが0の場合、友人にはアバターが設定されていません。 UINT64_MAXに等しいファイルサイズは、不明なファイルサイズ（ストリーミング）を示します。
• filenameはファイルの名前です。

ここでは、 ファイル名パラメータに特に注意を払う必要があります。 仕様ではすべてのデータをUTF-8に転送する必要があり、実際にはファイル名にパスの一部を含めることはできませんが、実際には、改行やゼロを含む読み取り不能なバイナリデータに飛ぶことがあります。



このイベントが発生すると、次のボットアクションは制御メソッドtox_file_control（friend_number、file_number、control）の呼び出しになります。ここで、

• friend_number-友人の番号。
• file_number-ファイル番号。
• control-ファイル管理コマンド：
  
  
  • TOX_FILE_CONTROL_CANCEL-ファイルの受信をキャンセルします。
  • TOX_FILE_CONTROL_PAUSE-ファイル転送を一時停止します（すべてのクライアントでサポートされているわけではありません）。
  • TOX_FILE_CONTROL_RESUME-ファイル転送を続行します。

エコーボットの場合、ファイルの受信は必要ないため、操作をいつでもキャンセルできます。

 class EchoBot(ToxCore): ... def tox_file_recv_cb(self, friend_number, file_number, kind, file_size, filename): self.tox_file_control(friend_number, file_number, ToxCore.TOX_FILE_CONTROL_CANCEL)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

TOX_FILE_CONTROL_RESUMEを介して制御を転送する場合、 tox_file_recv_chunk_cb（friend_number、file_number、position、data）イベントが開始します 。ここで、

• friend_number-友人の番号。
• file_number-ファイル番号。
• position-ファイル内の現在の位置。
• data-転送を終了するデータチャンクまたはNone。

ここでは、 位置が単調に増加する必要がないという事実に注意を払う必要があります。一般に、チャンクは任意の順序で任意の長さになります。

ファイル転送

ファイル転送手順を開始するには、 tox_file_sendメソッド（friend_number、kind、file_size、file_id、filename）を呼び出す必要があります 。ここで、

• friend_number-友人の番号。
• kind -value TOX_FILE_KIND_DATAまたはTOX_FILE_KIND_AVATAR
• file_size-ファイルサイズ（特別な値0およびUINT64_MAXは上記で説明されています）。
• file_id-長さTOX_FILE_ID_LENGTHのファイルの一意の識別子。これにより、カーネルの再起動後も転送を続行できます。自動生成の場合はNoneです。
• filenameはファイルの名前です。

ここでの特別なパラメーターはfile_idです。 自動生成の場合は、その後tox_file_get_file_idを呼び出すことで取得できますが、アバターを転送するときは、アバターファイルのデータからtox_hashを呼び出した結果に値を設定することをお勧めします。これにより、受信者は以前にロードしたアバターの転送をキャンセルしてトラフィックを節約できます。



また、ファイル転送は、ネットワークに接続している友人にのみ可能であることに注意する必要があります。 友人をネットワークから切断すると、ファイル転送が停止します。



tox_file_sendを呼び出した後、カーネルはホストからの決定を待ちます。 ソリューションは、 tox_file_recv_control_cb（friend_number、file_number、control）イベントによって処理されます。ここで、

• friend_number-友人の番号。
• file_number-ファイル番号。
• control-ファイル管理コマンド（ 前述のTOX_FILE_CONTROL_CANCEL 、 TOX_FILE_CONTROL_PAUSEまたはTOX_FILE_CONTROL_RESUME ）。

このイベントを処理すると、クライアントがファイルの受け入れを拒否した場合にリソースを解放できます。



エコーボットはアバターを送信するだけです。 アバターの転送は、友人がネットワークに現れるたびに行うことをお勧めします。 友人のtoxクライアントが、指定されたfile_idでアバターを以前にアップロードした場合、アバターの再送信をキャンセルできます。

 class EchoBot(ToxCore): ... def __init__(self): ... self.avatar_name = "avatar.png" self.avatar_size = os.path.getsize(avatar_name) self.avatar_fd = open(avatar_name, "rb") data = self.avatar_fd.read() self.avatar_id = ToxCore.tox_hash(data) def tox_friend_connection_status_cb(self, friend_number, connection_status): if connection_status != ToxCore.TOX_CONNECTION_NONE: send_avatar(friend_number) def send_avatar(self, friend_number): file_number = self.tox_file_send(friend_number, ToxCore.TOX_FILE_KIND_AVATAR, self.avatar_size, self.avatar_id, self.avatar_name) def tox_file_recv_control_cb(self, friend_number, file_number, control): pass def tox_file_chunk_request_cb(self, friend_number, file_number, position, length): if length == 0: return self.avatar_fd.seek(position, 0) data = self.avatar_fd.read(length) self.tox_file_send_chunk(friend_number, file_number, position, data)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

メッセージとファイルの送受信に加えて、カーネルはパケットを転送する機能を実装しています（損失の有無にかかわらず）。 これを行うには、tox_friend_send_lossy_packetおよびtox_friend_send_lossless_packetメソッド 、およびtox_friend_lossy_packet_cbおよびtox_friend_lossless_packet_cbイベントを使用します 。

参照資料

• tox.chat- （tox.imではなく）Toxプロジェクトの現在の公式サイト。
• githubのtoxcoreカーネルプロジェクト 。
• githubのPytoxcore pythonラッパープロジェクト 。
• githubでtox.pkgクライアントとライブラリのバイナリバージョンを構築するプロジェクト。
• githubの「公式」pythonラッパーPyToxのプロジェクト（執筆時点では、「古い」apiを使用しているため、ライブラリはコンパイルされませんでした）。