waapi_rs/
lib.rs

1//! waapi-rs: A Rust client for the Wwise Authoring API (WAAPI).
2//!
3//! Based on WAMP over WebSocket, supporting both async and sync usage.
4//! Main entry points are the async client [WaapiClient] and the sync client [WaapiClientSync].
5//!
6//! ---
7//!
8//! waapi-rs：Wwise Authoring API (WAAPI) 的 Rust 客户端。
9//!
10//! 基于 WAMP over WebSocket，支持异步与同步两种用法。主要入口为异步客户端
11//! [WaapiClient] 与同步客户端 [WaapiClientSync]。
12//!
13//! # Features
14//!
15//! - **Connect**: `WaapiClient::connect()` / `connect_with_url(url)`; sync client [WaapiClientSync] provides the same
16//! - **RPC**: `call(uri, args, options)`
17//! - **Subscribe**: `subscribe(topic, options, callback)` binds a callback for receiving events
18//! - **Cleanup**: connections and subscriptions auto-clean on Drop; explicit `disconnect` / `SubscriptionHandle::unsubscribe()` also available
19//!
20//! ---
21//!
22//! # 功能概览
23//!
24//! - **连接**：`WaapiClient::connect()` / `connect_with_url(url)`；同步客户端 [WaapiClientSync] 同样提供 `connect()` 与 `connect_with_url(url)`
25//! - **RPC 调用**：`call(uri, args, options)`
26//! - **订阅**：`subscribe(topic, options, callback)` 绑定回调接收事件
27//! - **资源**：连接与订阅在 Drop 时自动清理，也可显式 `disconnect` / `SubscriptionHandle::unsubscribe()`
28//!
29//! # Examples / 示例
30//!
31//! Async client — connect and call a WAAPI method (e.g. get Wwise version):
32//!
33//! 异步客户端 - 连接后调用 WAAPI 方法（如获取 Wwise 版本）：
34//!
35//! ```rust,no_run
36//! use waapi_rs::{ak, WaapiClient};
37//!
38//! #[tokio::main]
39//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
40//!     let client = WaapiClient::connect().await?;
41//!     let result = client.call(ak::wwise::core::GET_INFO, None, None).await?;
42//!     if let Some(info) = result {
43//!         let version = info.get("version")
44//!             .and_then(|v| v.get("displayName"))
45//!             .and_then(|v| v.as_str())
46//!             .unwrap_or("Unknown");
47//!         println!("Wwise Version: {}", version);
48//!     }
49//!     client.disconnect().await;
50//!     Ok(())
51//! }
52//! ```
53//!
54//! RPC call with `json!` args and options (e.g. WAQL query):
55//!
56//! 使用 `json!` 构造参数与选项进行 RPC 调用（如 WAQL 查询）：
57//!
58//! ```rust,no_run
59//! use serde_json::json;
60//! use waapi_rs::{ak, WaapiClient};
61//!
62//! #[tokio::main]
63//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
64//!     let client = WaapiClient::connect().await?;
65//!     let result = client
66//!         .call(
67//!             ak::wwise::core::OBJECT_GET,
68//!             Some(json!({ "waql": "$ from type Event" })),
69//!             Some(json!({ "return": ["id", "name", "type"] })),
70//!         )
71//!         .await?;
72//!     if let Some(obj) = result {
73//!         println!("Objects: {:?}", obj);
74//!     }
75//!     client.disconnect().await;
76//!     Ok(())
77//! }
78//! ```
79//!
80//! Subscribe to a topic with a callback:
81//!
82//! 订阅主题并用回调接收事件：
83//!
84//! ```rust,no_run
85//! use waapi_rs::{ak, WaapiClient};
86//!
87//! #[tokio::main]
88//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
89//!     let client = WaapiClient::connect().await?;
90//!     let handle = client
91//!         .subscribe(ak::wwise::ui::SELECTION_CHANGED, None, |kwargs| {
92//!             println!("Selection changed: {:?}", kwargs);
93//!         })
94//!         .await?;
95//!     handle.unsubscribe().await?;
96//!     client.disconnect().await;
97//!     Ok(())
98//! }
99//! ```
100//!
101//! Sync client (for non-async code or scripts):
102//!
103//! 同步客户端（适用于非 async 代码或脚本）：
104//!
105//! ```rust,no_run
106//! use waapi_rs::{ak, WaapiClientSync};
107//!
108//! fn main() -> Result<(), Box<dyn std::error::Error>> {
109//!     let client = WaapiClientSync::connect()?;
110//!     let result = client.call(ak::wwise::core::GET_INFO, None, None)?;
111//!     if let Some(info) = result {
112//!         println!("Info: {:?}", info);
113//!     }
114//!     client.disconnect();
115//!     Ok(())
116//! }
117//! ```
118//!
119//! # `call` types
120//!
121//! `call` returns `Option<serde_json::Value>`: the WAAPI response as JSON.
122//! `args` / `options` are `Option<serde_json::Value>` (e.g. `Some(json!({...}))` or `None`).
123//!
124//! ---
125//!
126//! # call 类型
127//!
128//! `call` 返回 `Option<serde_json::Value>`：WAAPI 响应的 JSON 值。
129//! `args` / `options` 为 `Option<serde_json::Value>`（如 `Some(json!({...}))` 或 `None`）。
130
131mod client;
132mod uris;
133mod wamp;
134pub use uris::ak;
135
136pub use client::{
137    SubscriptionHandle, SubscriptionHandleSync, WaapiClient, WaapiClientSync, WaapiError,
138};
waapi_rs/lib.rs

waapi_rs/
lib.rs
