2.2 登录状态与会话票据
上一节认识了 SteamID 这个身份载体,这一节处理「怎么把身份交给别人验证」——会话票据(Auth Session Ticket)。多人在线场景里,服务器或对端需要一个可靠证据确认「你是 SteamID 7656119…… 的那个玩家」,而不是你随口报的。ISteamUser::GetAuthSessionTicket 出票,对端用 BeginAuthSession 验证,这就是票据交换的核心循环。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamuser.h、steamclientpublic.h。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「后台配置」;本节讲「游戏内把登录身份变成可验证票据的接口语义」。
- 卷一《平台机制与商店》讲账号机制;本节讲会话票据的生命周期——它是登录身份在会话层的载体。
- lab 用纯 C++ 复现票据签发/验证/取消生命周期,不依赖 Steam 客户端运行。
登录状态:BLoggedOn 与 GetSteamID
接入工程的第一步是问「登录了没有」。ISteamUser 提供两个基础读取点:
// isteamuser.h:ISteamUser 登录状态(SDK v1.65 头文件摘录,已删减)
virtual bool BLoggedOn() = 0;
virtual CSteamID GetSteamID() = 0;
工程语义:
BLoggedOn()是「已连接到 Steam 并登录」:返回 true 才谈得上取票、查好友、同步成就。登录前调用绝大多数账号相关接口要么失败要么无意义。GetSteamID()返回当前登录者的完整 SteamID:注意它返回的是CSteamID,不是裸uint64——拿回来先IsValid()再当身份用。它是你在所有对端面前宣称的身份,也是出票时的绑定主体。
出票:GetAuthSessionTicket
登录确认后,把身份交给对端靠出票。v1.65 的签名(及配套回调结构):
// isteamuser.h:GetAuthSessionTicket 与响应回调(SDK v1.65 头文件摘录,已删减)
virtual HAuthTicket GetAuthSessionTicket( void *pTicket, int cbMaxTicket, uint32 *pcbTicket, const SteamNetworkingIdentity *pSteamNetworkingIdentity ) = 0;
struct GetAuthSessionTicketResponse_t
{
enum { k_iCallback = k_iSteamUserCallbacks + 63 };
HAuthTicket m_hAuthTicket;
EResult m_eResult;
};
工程语义:
- 票是「写给对端的身份证明」:
pTicket是出票缓冲,pcbTicket返回实际长度,游戏把这段字节发给要验证你的人。缓冲不足时返回无效票据并把所需长度写进pcbTicket(先探测、再取票)。 - 票可以绑定对端:
pSteamNetworkingIdentity可传对端的 IP 或 SteamID——传了就限票只能用给那个实体;不传则票可被任何实体验证。头文件注释明确此票「not to be used for ISteamUserAuth\AuthenticateUserTicket」。 HAuthTicket是「本端句柄」,不是票据内容:句柄用于后续取消(CancelAuthTicket)与回调对账;发给对端的是pTicket的字节。二者别混。- 回调是异步确认:
GetAuthSessionTicketResponse_t带句柄与EResult,出票结果不是同步可用的——接入工程应等回调再对端发起验证,或至少在日志里对账。
验证:BeginAuthSession 的生命周期
对端(服务器)拿到票后,用 BeginAuthSession 验证。v1.65 的结果枚举把失败原因分类:
// steamclientpublic.h:EBeginAuthSessionResult(SDK v1.65 头文件摘录,已删减)
enum EBeginAuthSessionResult
{
k_EBeginAuthSessionResultOK = 0, // Ticket is valid for this game and this steamID.
k_EBeginAuthSessionResultInvalidTicket = 1, // Ticket is not valid.
k_EBeginAuthSessionResultDuplicateRequest = 2, // A ticket has already been submitted for this steamID
k_EBeginAuthSessionResultInvalidVersion = 3, // Ticket is from an incompatible interface version
k_EBeginAuthSessionResultGameMismatch = 4, // Ticket is not for this game
k_EBeginAuthSessionResultExpiredTicket = 5, // Ticket has expired
};
与出票侧对称,验证侧的生命周期管理同样关键:
DuplicateRequest对应「票被复用」:同一张票重复提交会被拒绝——这是防重放的核心机制。接入工程应在对端记录已消费的票。CancelAuthTicket(本端)与票据生命周期:玩家离开对端、不再游玩时,本端应取消票据;对端相应得到「已取消」的验证结果(EAuthSessionResponse里AuthTicketCanceled),从而清理会话。EndAuthSession结束一段验证关系:对端不再追踪该 SteamID 时调用,成对使用。- 过期语义:票有有效期,
ExpiredTicket意味着别再把旧票当新鲜身份——对端应引导重新取票。
把两端串起来看,票据是一个有生命周期的对象:签发(本端)→ 传递(网络)→ 验证(对端)→ 消费/取消/过期。接入工程要同时管好本端(出票、取消)和对端(验证、消费记录、结束会话)两端状态。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamuser.h | ISteamUser::BLoggedOn() | 登录门控 |
isteamuser.h | ISteamUser::GetSteamID() | 当前登录者 SteamID |
isteamuser.h | ISteamUser::GetAuthSessionTicket(...) | 出票给对端(可绑定对端身份) |
isteamuser.h | GetAuthSessionTicketResponse_t | 出票异步回调(句柄 + EResult) |
isteamuser.h | ISteamUser::CancelAuthTicket(HAuthTicket) | 取消本端票据 |
isteamuser.h | ISteamUser::BeginAuthSession(...) | 对端验证票 |
steamclientpublic.h | EBeginAuthSessionResult | 验证结果分类(复用/过期/错版等) |
数据口径与来源
- 接口签名、回调结构字段、
HAuthTicket类型(uint32)与k_HAuthTicketInvalid = 0:SDK v1.65public/steam/isteamuser.h、steamclientpublic.h可实证(本机镜像已核对)。 EBeginAuthSessionResult各分支语义:steamclientpublic.h注释明文。- 票据具体有效时长与重放窗口:登录后可见的官方文档口径,以官方当前为准。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「会话票据生命周期」的工程语义:BLoggedOn 门控、出票与长度探测、验证通过/身份不符/复用/取消/过期判定、EndAuthSession 清理、回调结构对账。它与 src/02-2-login-session-ticket.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:
// file: src/02-2-login-session-ticket.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/02-2-login-session-ticket.cpp -o bin/02-2-login-session-ticket && ./bin/02-2-login-session-ticket
//
// mock:复现登录状态与会话票据的生命周期——BLoggedOn 门控、
// GetAuthSessionTicket 出票、BeginAuthSession 验证、CancelAuthTicket 取消、
// 票据复用/过期判定,以及 GetAuthSessionTicketResponse_t 回调结构。
// 签名对照 SDK v1.65 isteamuser.h / steamclientpublic.h,非 Valve 实现。
#include "verify.h"
#include <cstdint>
#include <unordered_map>
#include <vector>
namespace steam_repro {
// EBeginAuthSessionResult 枚举值对照 steamclientpublic.h
enum MockBeginAuthResult {
kOK = 0,
kInvalidTicket = 1,
kDuplicateRequest = 2,
kInvalidVersion = 3,
kGameMismatch = 4,
kExpiredTicket = 5,
};
// GetAuthSessionTicketResponse_t 回调结构字段对照 isteamuser.h
struct MockTicketResponse {
uint32_t hAuthTicket;
int result;
};
class MockSessionTicket {
public:
struct TicketRec {
uint32_t id;
uint64_t steamId;
uint32_t issueSeq;
bool cancelled;
bool used;
};
static constexpr uint32_t kTicketBytes = 17;
// client 侧状态
bool loggedOn = false;
uint64_t localSteamId = 76561197960287930ull;
// server 侧状态:时间线(签发与验证共用)
uint32_t serverSeq = 0;
std::unordered_map<uint32_t, TicketRec> tickets_;
std::vector<uint64_t> activeSessions_;
MockTicketResponse lastResponse;
static void pack(uint32_t id, uint64_t steamId, uint32_t seq, void* out) {
uint8_t* p = static_cast<uint8_t*>(out);
for (int i = 0; i < 4; ++i) p[i] = (id >> (8 * i)) & 0xFF;
for (int i = 0; i < 8; ++i) p[4 + i] = (steamId >> (8 * i)) & 0xFF;
for (int i = 0; i < 4; ++i) p[12 + i] = (seq >> (8 * i)) & 0xFF;
p[16] = 0;
}
static TicketRec unpack(const void* in) {
const uint8_t* p = static_cast<const uint8_t*>(in);
uint32_t id = 0, seq = 0;
uint64_t sid = 0;
for (int i = 3; i >= 0; --i) id = (id << 8) | p[i];
for (int i = 7; i >= 0; --i) sid = (sid << 8) | p[4 + i];
for (int i = 3; i >= 0; --i) seq = (seq << 8) | p[12 + i];
return TicketRec{id, sid, seq, false, false};
}
// ISteamUser::GetAuthSessionTicket:未登录返回无效票据;
// 缓冲不足时 *pcbTicket 写入所需长度并返回无效票据。
uint32_t getAuthSessionTicket(void* pTicket, int cbMaxTicket, uint32_t* pcbTicket) {
if (!loggedOn) {
*pcbTicket = 0;
return 0; // k_HAuthTicketInvalid
}
if (pTicket == nullptr || cbMaxTicket < static_cast<int>(kTicketBytes)) {
*pcbTicket = kTicketBytes;
return 0;
}
uint32_t id = ++nextTicketId_;
uint32_t seq = ++serverSeq; // 签发时推进时间线,票即「当时」的服务器时间
TicketRec rec{id, localSteamId, seq, false, false};
tickets_[id] = rec;
pack(id, localSteamId, seq, pTicket);
*pcbTicket = kTicketBytes;
// 异步回调:票已生成,result 为 OK
lastResponse = MockTicketResponse{id, /* k_EResultOK */ 1};
return id;
}
// ISteamUser::CancelAuthTicket
void cancelAuthTicket(uint32_t hAuthTicket) {
auto it = tickets_.find(hAuthTicket);
if (it != tickets_.end()) it->second.cancelled = true;
}
// ISteamUser::BeginAuthSession:验证票并注册会话
MockBeginAuthResult beginAuthSession(const void* pAuthTicket, int cbAuthTicket,
uint64_t claimedSteamId) {
if (pAuthTicket == nullptr || cbAuthTicket != static_cast<int>(kTicketBytes))
return kInvalidTicket;
TicketRec parsed = unpack(pAuthTicket);
auto it = tickets_.find(parsed.id);
if (it == tickets_.end()) return kInvalidTicket;
if (it->second.cancelled) return kInvalidTicket;
if (it->second.steamId != claimedSteamId) return kInvalidTicket;
if (it->second.used) return kDuplicateRequest;
if (serverSeq - it->second.issueSeq > 5) return kExpiredTicket;
it->second.used = true;
activeSessions_.push_back(claimedSteamId);
return kOK;
}
// ISteamUser::EndAuthSession
void endAuthSession(uint64_t steamId) {
for (auto it = activeSessions_.begin(); it != activeSessions_.end();) {
it = (*it == steamId) ? activeSessions_.erase(it) : it + 1;
}
}
bool hasActiveSession(uint64_t steamId) const {
for (uint64_t s : activeSessions_) {
if (s == steamId) return true;
}
return false;
}
private:
uint32_t nextTicketId_ = 0;
};
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockSessionTicket s;
uint8_t buf[MockSessionTicket::kTicketBytes] = {0};
uint32_t pcb = 0;
// 1. 未登录时出票失败(无效票据 + 长度 0)
CHECK(s.getAuthSessionTicket(buf, MockSessionTicket::kTicketBytes, &pcb) == 0);
CHECK(pcb == 0);
// 2. 登录后出票成功:非零票据 + 长度写入 + 回调响应 OK
s.loggedOn = true;
uint32_t h1 = s.getAuthSessionTicket(buf, MockSessionTicket::kTicketBytes, &pcb);
CHECK(h1 != 0);
CHECK(pcb == MockSessionTicket::kTicketBytes);
CHECK(s.lastResponse.hAuthTicket == h1);
CHECK(s.lastResponse.result == 1);
// 3. 缓冲不足:返回无效票据,pcb 写所需长度
CHECK(s.getAuthSessionTicket(buf, 4, &pcb) == 0);
CHECK(pcb == MockSessionTicket::kTicketBytes);
// 4. 空缓冲(仅探测长度):返回无效票据,pcb 写所需长度
CHECK(s.getAuthSessionTicket(nullptr, 0, &pcb) == 0);
CHECK(pcb == MockSessionTicket::kTicketBytes);
// 5. 合法票验证通过,会话注册
uint8_t ticketBuf[MockSessionTicket::kTicketBytes] = {0};
uint32_t pcb2 = 0;
s.getAuthSessionTicket(ticketBuf, MockSessionTicket::kTicketBytes, &pcb2);
CHECK(s.beginAuthSession(ticketBuf, MockSessionTicket::kTicketBytes, s.localSteamId) == kOK);
CHECK(s.hasActiveSession(s.localSteamId));
// 6. 票与申明身份绑定:错误 SteamID 验证失败
CHECK(s.beginAuthSession(ticketBuf, MockSessionTicket::kTicketBytes,
s.localSteamId + 1) == kInvalidTicket);
// 7. 同一张票复用 → DuplicateRequest
CHECK(s.beginAuthSession(ticketBuf, MockSessionTicket::kTicketBytes, s.localSteamId) ==
kDuplicateRequest);
// 8. 取消后的票不可验证
uint8_t cBuf[MockSessionTicket::kTicketBytes] = {0};
uint32_t pcb3 = 0;
uint32_t h3 = s.getAuthSessionTicket(cBuf, MockSessionTicket::kTicketBytes, &pcb3);
s.cancelAuthTicket(h3);
CHECK(s.beginAuthSession(cBuf, MockSessionTicket::kTicketBytes, s.localSteamId) ==
kInvalidTicket);
// 9. 过期票 → ExpiredTicket
uint8_t eBuf[MockSessionTicket::kTicketBytes] = {0};
uint32_t pcb4 = 0;
s.getAuthSessionTicket(eBuf, MockSessionTicket::kTicketBytes, &pcb4);
s.serverSeq += 10; // 推进服务器时间线
CHECK(s.beginAuthSession(eBuf, MockSessionTicket::kTicketBytes, s.localSteamId) ==
kExpiredTicket);
// 10. EndAuthSession 清理会话
s.endAuthSession(s.localSteamId);
CHECK(!s.hasActiveSession(s.localSteamId));
return lab::report("02-2 登录状态与会话票据");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 17/17 通过。
小结
- 登录门控是
BLoggedOn;GetSteamID返回当前身份,先IsValid再使用。 GetAuthSessionTicket出票给对端,票可绑定对端身份;HAuthTicket是本端句柄,GetAuthSessionTicketResponse_t是异步确认。- 对端用
BeginAuthSession验证,EBeginAuthSessionResult把失败分类:复用(DuplicateRequest)、过期(ExpiredTicket)是接入工程必须处理的两种。 - 票据是有生命周期的对象:签发 → 传递 → 验证 → 消费/取消/过期;本端与对端都要管好状态。
阅读导航:上一节:2.1 SteamID 与账号身份 · 下一节:2.3 加密票据与身份边界 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。