《Steam 游戏平台:开发与商业化》2.2 登录状态与会话票据

BLoggedOn 是登录门控,GetAuthSessionTicket 出一张绑定 SteamID 的会话票据交给对端,对端用 BeginAuthSession 验证。本节讲登录状态与会话票据的生命周期:出票、验证、复用判定、取消与过期,lab 用 C++ mock 票的签发/验证/取消全流程。

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;

工程语义:

  1. BLoggedOn() 是「已连接到 Steam 并登录」:返回 true 才谈得上取票、查好友、同步成就。登录前调用绝大多数账号相关接口要么失败要么无意义。
  2. 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;
};

工程语义:

  1. 票是「写给对端的身份证明」:pTicket 是出票缓冲,pcbTicket 返回实际长度,游戏把这段字节发给要验证你的人。缓冲不足时返回无效票据并把所需长度写进 pcbTicket(先探测、再取票)。
  2. 票可以绑定对端:pSteamNetworkingIdentity 可传对端的 IP 或 SteamID——传了就限票只能用给那个实体;不传则票可被任何实体验证。头文件注释明确此票「not to be used for ISteamUserAuth\AuthenticateUserTicket」。
  3. HAuthTicket 是「本端句柄」,不是票据内容:句柄用于后续取消(CancelAuthTicket)与回调对账;发给对端的是 pTicket 的字节。二者别混。
  4. 回调是异步确认: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
};

与出票侧对称,验证侧的生命周期管理同样关键:

  1. DuplicateRequest 对应「票被复用」:同一张票重复提交会被拒绝——这是防重放的核心机制。接入工程应在对端记录已消费的票。
  2. CancelAuthTicket(本端)与票据生命周期:玩家离开对端、不再游玩时,本端应取消票据;对端相应得到「已取消」的验证结果(EAuthSessionResponse 里 AuthTicketCanceled),从而清理会话。
  3. EndAuthSession 结束一段验证关系:对端不再追踪该 SteamID 时调用,成对使用。
  4. 过期语义:票有有效期,ExpiredTicket 意味着别再把旧票当新鲜身份——对端应引导重新取票。

把两端串起来看,票据是一个有生命周期的对象:签发(本端)→ 传递(网络)→ 验证(对端)→ 消费/取消/过期。接入工程要同时管好本端(出票、取消)和对端(验证、消费记录、结束会话)两端状态。

接口签名对照

头文件条目语义
isteamuser.hISteamUser::BLoggedOn()登录门控
isteamuser.hISteamUser::GetSteamID()当前登录者 SteamID
isteamuser.hISteamUser::GetAuthSessionTicket(...)出票给对端(可绑定对端身份)
isteamuser.hGetAuthSessionTicketResponse_t出票异步回调(句柄 + EResult)
isteamuser.hISteamUser::CancelAuthTicket(HAuthTicket)取消本端票据
isteamuser.hISteamUser::BeginAuthSession(...)对端验证票
steamclientpublic.hEBeginAuthSessionResult验证结果分类(复用/过期/错版等)

数据口径与来源

  • 接口签名、回调结构字段、HAuthTicket 类型(uint32)与 k_HAuthTicketInvalid = 0:SDK v1.65 public/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 加密票据与身份边界 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图