Steamworks 文献库
ISteamUtils 接口
访问一系列杂项工具函数的接口。

成员函数

ISteamUtils 的成员函数通过全局访问器函数 SteamUtils() 调用。

BOverlayNeedsPresent

bool BOverlayNeedsPresent();
检查界面是否需要显示。 仅在使用由事件驱动的渲染更新时需要。

通常,如果您的游戏有一个持续运行的帧循环来调用 D3D Presnet API,或者如多数游戏一样,每帧调用 OGL swapbuffer API,那么您不需要此调用。 然而,如果您的游戏仅仅在事件驱动下刷新屏幕,那么可能会破坏界面,因为它使用了 Present/SwapBuffers 调用来驱动其内部帧循环,而且只要出现通知,或用户在游戏中调出界面,它可能就会对屏幕使用 Present()。 可使用此 API 来询问界面当前是否需要显示,然后可周期性地检查(最好是大约 33hz),并确保您使用 Present 或 SwapBuffers 刷新屏幕,以使界面正常工作。

返回: bool
true, 表示界面需要您刷新屏幕,否则返回 false

CheckFileSignature

SteamAPICall_t CheckFileSignature( const char *szFileName );
名称类型描述
szFileNameconst char *.

已弃用。

返回: SteamAPICall_t,与 CheckFileSignature_t 调用结果一起使用。

GetAPICallFailureReason

ESteamAPICallFailure GetAPICallFailureReason( SteamAPICall_t hSteamAPICall );
名称类型描述
hSteamAPICallSteamAPICall_t用于检查失败原因的 Steam API 调用句柄。

用于获取调用结果的失败原因。

此函数主要用于调试。 失败的原因通常无法控制,且并不太重要。 只要继续重试您的 API 调用直至其正常工作即可。

返回: ESteamAPICallFailure
[type]ESteamAPICallFailure[/type]

另见: IsAPICallCompletedGetAPICallResult

示例:
void CHTMLSurface::OnBrowserReady( HTML_BrowserReady_t *pBrowserReady, bool bIOFailure ) { if ( bIOFailure ) { SteamUtils()->GetAPICallFailureReason( handle ); // handle must be stored separately. return; } }

GetAPICallResult

bool GetAPICallResult( SteamAPICall_t hSteamAPICall, void *pCallback, int cubCallback, int iCallbackExpected, bool *pbFailed );
名称类型描述
hSteamAPICallSteamAPICall_tAPI 调用的句柄。
pCallbackvoid *返回回调至预先分配的内存。
cubCallbackint您正传入的 pCallback 的大小。
iCallbackExpectedint与回调关联的 k_iCallback 数。
pbFailedbool *API 调用失败时返回。

获取完整 API 调用的内容。 为 CallResult 包装器的后端提供。

通常不建议您手动使用此方法。

返回: bool
true, 表示 API 调用有效且完整,否则返回 false

如果调用成功,复制回调至 pCallback,并在 pbFailed 中返回失败。

另见: IsAPICallCompletedGetAPICallFailureReason

GetAppID

uint32 GetAppID();
获取当前进程的 App ID。

返回: uint32
返回 AppId。

GetConnectedUniverse

EUniverse GetConnectedUniverse();
获取当前客户端连接至的 Steam 系统。 (仅限 Valve 使用。)

返回: EUniverse
[type]EUniverse[/type]

GetCSERIPPort

bool GetCSERIPPort( uint32 *unIP, uint16 *usPort );
名称类型描述
unIPuint32 *返回客户端连接至的 IP。
usPortuint16 *返回客户端连接至的端口。

为 Valve 获取报告服务器的 IP,目前只在 Source 引擎游戏中使用。

返回: bool
如果用户当前已连接,返回 true,否则返回 false

GetCurrentBatteryPower

uint8 GetCurrentBatteryPower();
获取电脑上的当前电池电量。

返回: uint8
当前电池电量范围 [0..100]%。 用户使用 AC 电源时,返回 255。

GetEnteredGamepadTextInput

bool GetEnteredGamepadTextInput( char *pchText, uint32 cchText );
名称类型描述
pchTextchar *文本输入字符串要复制入的预分配缓冲区。
cchTextuint32pchText 缓冲区大小。

从大屏幕界面获取游戏手柄文本输入。

此函数必须在 GamepadTextInputDismissed_t 回调中调用,且仅在 GamepadTextInputDismissed_t.m_bSubmitted 为 true 时调用。

以 UTF-8 格式提供文本输入。

[b]返回:[/b] bool
true, 表示有要接收的文本,且 cchText 与 GamepadTextInputDismissed_t.m_unSubmittedText; 的大小相同;否则,返回 false

另见: ShowGamepadTextInputGetEnteredGamepadTextLength

示例:
void OnGamepadTextInputDismissed_t( GamepadTextInputDismissed_t* pCallback ) { // 用户已取消, if ( !pCallback.m_bSubmitted ) return; // 使用我们传入 ShowGamepadTextInput 的最大输入长度,并为空字符多留一个位置用作终止符。 const uint32 MAX_INPUT_LENGTH = 64 + 1; uint32 length = SteamUtils()->GetEnteredGamepadTextLength(); char* szTextInput[MAX_INPUT_LENGTH]; bool success = SteamUtils()->GetEnteredGamepadTextInput( szTextInput, length ); if ( !success ) { // 记录一个错误。 应只发生在长度 > MaxInputLength 时 return; } // 显示更新的字符串 }

GetEnteredGamepadTextLength

uint32 GetEnteredGamepadTextLength();
从大屏幕界面获取游戏手柄文本输入长度。

此函数必须在 GamepadTextInputDismissed_t 回调中调用,且仅在 GamepadTextInputDismissed_t.m_bSubmitted 为 true 时调用。

返回: uint32


另见: ShowGamepadTextInputGetEnteredGamepadTextInput

示例:
void OnGamepadTextInputDismissed_t( GamepadTextInputDismissed_t* pCallback ) { // 用户已取消, if ( !pCallback.m_bSubmitted ) return; // 使用我们传入 ShowGamepadTextInput 的最大输入长度,并为空字符多留一个位置用作终止符。 const uint32 MAX_INPUT_LENGTH = 64 + 1; uint32 length = SteamUtils()->GetEnteredGamepadTextLength(); const char* szTextInput[MAX_INPUT_LENGTH]; bool success = SteamUtils()->GetEnteredGamepadTextInput( szTextInput, length ); if ( !success ) { // 记录一个错误。 应只发生在长度 > MaxInputLength 时 return; } // 显示更新的字符串 }

GetImageRGBA

bool GetImageRGBA( int iImage, uint8 *pubDest, int nDestBufferSize );
名称类型描述
iImageint要获得的图像的句柄。
pubDestuint8 *要填充的缓冲区。
nDestBufferSizeintpubDest 缓冲区的总大小。

从图像句柄中获取图像字节。

调用此函数前必须通过调用 GetImageSize 得到图像大小,这样您可以创建合适大小的缓冲区。 然后您可以以“宽度*高度*4”来分配缓冲区。 图像采用 RGBA 格式。 由于从压缩类型(JPG、PNG、TGA)转换而来,并且不提供所返回的缓冲区的内部缓存,此调用可能耗费稍大,因此我们强烈建议只在每个图像句柄上调用一次,并缓存结果。 此功能仅用于 Steam 头像及成就图像,以及预计不会在游戏中途改变的图像。

返回: bool
true, 表示图像句柄有效且缓冲区全部被填充,否则返回 false

另见: ISteamFriends::GetSmallFriendAvatarISteamFriends::GetMediumFriendAvatarISteamFriends::GetLargeFriendAvatarISteamUserStats::GetAchievementIcon

示例:
HGAMETEXTURE GetSteamImageAsTexture( int iImage ) { HGAMETEXTURE hTexture = 0; // 您应首先检查是否已经使用字典/地图之类的东西缓存了这张图片 // 以 iImage 为键,返回与之关联的纹理句柄(如果存在) // 如果不存在,则继续,并在函数结束时返回地图前,对地图添加纹理 // 如果我们需要查看图像的大小 uint32 uAvatarWidth, uAvatarHeight; bool success = SteamUtils()->GetImageSize( iImage, &uAvatarWidth, &uAvatarHeight ); if ( !success ) { // 记录一条警告消息 return hTexture; } // 从 Steam 获取实际的原始 RGBA 数据并在我们的游戏引擎中将其转化为纹理 const int uImageSizeInBytes = uAvatarWidth * uAvatarHeight * 4; uint8 *pAvatarRGBA = new uint8[uImageSizeInBytes]; success = SteamUtils()->GetImageRGBA( iImage, pAvatarRGBA, uImageSizeInBytes ); if( !success ) { // 将 RGBA 纹理转换为您的内部纹理格式以供显示 // hTexture = m_pGameEngine->HCreateTexture( pAvatarRGBA, uAvatarWidth, uAvatarHeight ); // 并将纹理添加到缓存 } // 不要忘记释放内存! delete[] pAvatarRGBA; return hTexture; }

GetImageSize

bool GetImageSize( int iImage, uint32 *pnWidth, uint32 *pnHeight );
名称类型描述
iImageint要获取大小的图像句柄。
pnWidthuint32 *返回图像宽度。
pnHeightuint32 *返回图像高度。

获取 Steam 图像句柄的大小。

此函数必须在调用 GetImageRGBA 前调用,以创建大小合适的缓冲区,此缓冲区将由原始图像数据填充。

返回: bool
true, 表示图像句柄有效且大小已被填充,否则返回 false

另见: ISteamFriends::GetSmallFriendAvatarISteamFriends::GetMediumFriendAvatarISteamFriends::GetLargeFriendAvatarISteamUserStats::GetAchievementIcon

GetIPCCallCount

uint32 GetIPCCallCount();
返回自上次调用此函数后所做的 IPC 调用的数量。

用于进行性能调试,这样您就可以确定每帧中您的游戏所调用的 IPC(进程间通信)的数量。
就算不是进程切换,每个 IPC 调用也至少是一个线程上下文切换,因此您需要控制使用频率。

返回: uint32

GetIPCountry

const char * GetIPCountry();
返回客户端正在运行的 2 位 ISO 3166-1-alpha-2 格式的国家代码。
如“US”或“UK”。

通过 IP 地址位置数据库来查找。

返回: const char *

GetSecondsSinceAppActive

uint32 GetSecondsSinceAppActive();
返回自应用程序激活起的秒数。

返回: uint32

GetSecondsSinceComputerActive

uint32 GetSecondsSinceComputerActive();
返回自上次用户移动鼠标起的秒数。

返回: uint32

GetServerRealTime

uint32 GetServerRealTime();
以 Unix 时间戳格式返回 Steam 服务器时间。 (自 1970 年 1 月 1 日起的秒数)。

返回: uint32

GetSteamUILanguage

const char * GetSteamUILanguage();
返回 Steam 客户端正在运行的语言。

此函数仅在少数特殊情况下使用。您也许需要转为调用 ISteamApps::GetCurrentGameLanguage

参见支持的语言,查看完整语言列表。

返回: const char *


另见: ISteamApps::GetCurrentGameLanguageISteamApps::GetAvailableGameLanguages

IsAPICallCompleted

bool IsAPICallCompleted( SteamAPICall_t hSteamAPICall, bool *pbFailed );
名称类型描述
hSteamAPICallSteamAPICall_t要检查的 API 调用句柄。
pbFailedbool *返回 API 调用是失败了(true),还是没失败(false)。

检查 API 调用是否已完成。 提供 CallResult 包装器后端。

我们通常不建议您自己使用此方法。

返回: bool
true, 表示 API 调用有效且完整,否则返回 false

另见: GetAPICallResultGetAPICallFailureReason

IsOverlayEnabled

bool IsOverlayEnabled();
检查 Steam 界面是否正在运行并可供用户访问。

界面进程可能需要几秒钟的时间来启动并与游戏进程挂钩,因此当界面在加载时,此函数最初将返回 false。

返回: bool

IsSteamChinaLauncher

bool IsSteamChinaLauncher();
返回当前启动器是否为蒸汽平台启动器。 您可以在运行 Steam 时在命令行中添加 -dev -steamchina,使客户端模拟蒸汽平台启动器。

InitFilterText

bool InitFilterText();
初始化文字过滤,为游戏运行的语言加载字典。

用户可以在其 Steam 帐户偏好中自定义文字过滤行为。

返回: bool
true, 表示初始化成功;如果过滤对于游戏的语言不可用,则返回 false,在这种情况下,FilterText() 将作为直通函数运行。

另见: FilterText

FilterText

int FilterText( ETextFilteringContext eContext, CSteamID sourceSteamID, const char *pchInputMessage, char *pchOutFilteredText, uint32 nByteSizeOutFilteredText );
名称类型描述
eContextETextFilteringContext输入字符串中的内容类型
sourceSteamIDCSteamID作为输入字符串的源的 Steam ID(比如,使用该名称的玩家,或发送该聊天文本的人)。
pchInputTextconst char*应该过滤掉的输入字符串,可以是 ASCII 或 UTF-8 格式。
pchOutFilteredTextchar*输出将被取代(即便没有进行过滤)的位置。
nByteSizeOutFilteredText uint32pchOutFilteredText 的大小(以字节计),应至少为 strlen(pchInputText)+1。
过滤提供的输入消息并将过滤后的结果放入 pchOutFilteredText。 法律要求的过滤条件将始终开启。 根据上下文和用户设置,可能会有额外的过滤。

返回: int
返回过滤掉的字数/字母数(而非字节数)。

另见: InitFilterText

IsSteamInBigPictureMode

bool IsSteamInBigPictureMode();
检查 Steam 及 Steam 界面是否在大屏幕模式下运行。

游戏必须通过 Steam 客户端启动,以启用大屏幕界面。
在开发过程中,可以将一款游戏作为非 Steam 游戏添加到开发者库中以测试此功能。

返回: bool
true, 表示大屏幕界面可用;否则返回 false
如果您的应用不是“游戏”应用程序类型,将总是返回 false

IsSteamRunningInVR

bool IsSteamRunningInVR();
检查 Steam 是否在 VR 模式下运行。

返回: bool
true, 表示 Steam 自身在 VR 模式下运行,否则返回 false

IsVRHeadsetStreamingEnabled

bool IsVRHeadsetStreamingEnabled();
检查 HMD 视图是否通过 Steam 远程畅玩流式传输。

返回: bool
true, 表示启用 VR 且当前在流式传输头戴式显示器视图;否则,返回 false

另见: SetVRHeadsetStreamingEnabled

IsSteamRunningOnSteamDeck

bool IsSteamRunningOnSteamDeck();
检查 Steam 是否在 Steam Deck 设备上运行。

返回: bool
true, 表示 Steam 本身在 Steam Deck 设备上运行,否则返回 false

SetOverlayNotificationInset

void SetOverlayNotificationInset( int nHorizontalInset, int nVerticalInset );
名称类型描述
nHorizontalInsetint从角落起的水平像素(左右)距离。
nVerticalInsetint从角落起的垂直像素(上下)距离。

设置界面通知的嵌入窗口相对于 SetOverlayNotificationPosition 指定角落的位置。

一个 (0,0) 值将位置重置于角落。

此位置为按游戏进行的设置,每次启动都将重置。

SetOverlayNotificationPosition

void SetOverlayNotificationPosition( ENotificationPosition eNotificationPosition );
名称类型描述
eNotificationPositionENotificationPosition

设置 Steam 界面通知弹出项应该显示哪个角落中。

您也可以使用 SetOverlayNotificationInset ,设置离指定角落的距离。

此位置为按游戏进行的设置,每次启动都将重置。

SetVRHeadsetStreamingEnabled

void SetVRHeadsetStreamingEnabled( bool bEnabled );
名称类型描述
bEnabledbool开启(true)或关闭(false)VR 头显流式传输。

设置头戴式显示器内容是否通过 Steam 远程畅玩进行流式传输。

如果启用这一功能,那么 HMD 头戴设备内的场景将被流式传输,且不允许远程输入。 反之,若禁用此功能,那么应用程序窗口将被流式传输,且允许远程输入。 VR 游戏默认为启用,除非“VRHeadsetStreaming”“0”包括在游戏的扩展 appinfo 中。

这对于有非对称多人玩法的游戏非常有用。

另见: IsVRHeadsetStreamingEnabled

SetWarningMessageHook

void SetWarningMessageHook( SteamAPIWarningMessageHook_t pFunction );
名称类型描述
pFunctionSteamAPIWarningMessageHook_t指向回调函数的函数指针。

设置一个警告消息挂钩,以在回调函数中接收 SteamAPI 警告及信息消息。

函数原型必须与在 SteamAPIWarningMessageHook_t 中的定义一致。 包括外部“C”链接及 __cdecl 调用约定。

“int nSeverity”为严重级别,0 为消息,1 为警告。 如果您在调试器中运行,只会发出警告。 如在命令行添加 -debug_steamapi,则信息消息也会发送。
“const char * pchDebugText”为消息文字。
生成警告或消息的 API 函数被调用后会直接产生回调。

传入 NULL 可解除挂钩。

示例:
extern "C" void __cdecl SteamAPIDebugTextHook( int nSeverity, const char *pchDebugText ) { ::OutputDebugString( pchDebugText ); if ( nSeverity >= 1 ) { //在这里设置断点以捕获 API 错误 int x = 3; x = x; } } void EnableWarningMessageHook() { SteamUtils()->SetWarningMessageHook( &SteamAPIDebugTextHook ); }

ShowGamepadTextInput

bool ShowGamepadTextInput( EGamepadTextInputMode eInputMode, EGamepadTextInputLineMode eLineInputMode, const char *pchDescription, uint32 unCharMax, const char *pchExistingText );
名称类型描述
eInputModeEGamepadTextInputMode选择要使用的输入模式,不论是正常或密码(隐藏文本)。
eLineInputModeEGamepadTextInputLineMode控制是否使用单行或多行输入。
pchDescriptionconst char *设置应告知用户输入对话框用途的描述。
unCharMaxuint32用户可以输入的最大字符数。
pchExistingTextconst char *设置用户可以编辑的既有文本。

激活仅支持游戏手柄输入的大屏幕文本输入对话框。

返回: bool
true, 表示大屏幕界面正在运行;否则返回 false

另见: GetEnteredGamepadTextLengthGetEnteredGamepadTextInput

ShowFloatingGamepadTextInput

bool ShowFloatingGamepadTextInput( EFloatingGamepadTextInputMode eKeyboardMode, int nTextFieldXPosition, int nTextFieldYPosition, int nTextFieldWidth, int nTextFieldHeight );
名称类型描述
eKeyboardModeEFloatingGamepadTextInputMode选择要使用的键盘类型。
nTextFieldXPositionint不应被浮动键盘遮挡的文本字段的 X 坐标。
nTextFieldYPositionint不应被浮动键盘遮挡的文本字段的 Y 坐标。
nTextFieldWidthint不应被浮动键盘遮挡的文本字段的宽度。
nTextFieldHeight int不应被浮动键盘遮挡的文本字段的高度。

在游戏内容上打开一个浮动键盘并将操作系统键盘键直接发送到游戏。
文本字段位置以相对于游戏窗口原点的像素距离为单位指定,用于以不覆盖文本字段的方式定位浮动键盘。

返回: bool
true, 表示已显示浮动键盘,否则返回 false

另见: FloatingGamepadTextInputDismissed_t

StartVRDashboard

void StartVRDashboard();
要求 Steam 创建并渲染 OpenVR 主面板。

SetGameLauncherMode

void SetGameLauncherMode( bool bLauncherMode);
名称类型描述
bLauncherModebool启动器是否在使用中。
您可以在没有控制器支持的游戏启动器中调用此函数,让 Steam 输入将控制器输入转换为鼠标/键盘,以操控启动器。

Callbacks

以下是可以通过调用 SteamAPI_RunCallbacks 触发的回调。 其中许多将响应 ISteamUtils 的成员函数直接触发。

CheckFileSignature_t

CheckFileSignature 的调用结果。

名称类型描述
m_eCheckFileSignatureECheckFileSignature包含文件签名检查的结果。
k_ECheckFileSignatureNoSignaturesFoundForThisApp - 该应用尚未在合作伙伴站点的签名选项卡上进行配置以启用此功能。
k_ECheckFileSignatureNoSignaturesFoundForThisFile - 此文件未在合作伙伴站点的签名选项卡上列出。
k_ECheckFileSignatureFileNotFound - 此文件未存在于磁盘上。
k_ECheckFileSignatureInvalidSignature - 此文件存在,且已设置了签名选项卡,但该文件要么未签名,要么签名不匹配。
k_ECheckFileSignatureValidSignature - 文件已签署且签名有效。

关联函数: CheckFileSignature

GamepadTextInputDismissed_t

在大屏幕游戏手柄文本输入关闭的情况下调用。

名称类型描述
m_bSubmittedbool如果用户已输入并接受文本(调用 GetEnteredGamepadTextInput 以接收文本),为 true;如果输入取消,则为 false
m_unSubmittedTextuint32如果提交了文本,则包含字节长度。

FloatingGamepadTextInputDismissed_t

当从 ShowFloatingGamepadTextInput 调用的浮动键盘关闭时调用。

IPCountry_t

当用户的国家改变时调用。 应调用 GetIPCountry 更新国家。

此回调无字段。

LowBatteryPower_t

在笔记本电脑上运行且电池电量不足 10 分钟时调用,之后每分钟内都会触发。

名称类型描述
m_nMinutesBatteryLeftuint8预计的剩余电量可用的分钟数。

SteamAPICallCompleted_t

当 SteamAPICall_t 完成(或失败)时调用。

名称类型描述
m_hAsyncCallSteamAPICall_t已完成的 Steam API 调用的句柄。
m_iCallbackint这是 k_iCallback 常量,它可以对已完成的回调进行唯一标识。
m_cubParamuint32已完成回调的字节大小。

AppResumingFromSuspend_t

在设备从休眠/暂挂模式中恢复时发送。

此回调无字段。

SteamShutdown_t

当 Steam 想要关闭时调用。

此回调无字段。

枚举

以下是定义来与 ISteamUtils 一起使用的枚举。

ECheckFileSignature

调用 CheckFileSignature 的结果。

名称描述
k_ECheckFileSignatureInvalidSignature0
k_ECheckFileSignatureValidSignature1
k_ECheckFileSignatureFileNotFound2
k_ECheckFileSignatureNoSignaturesFoundForThisApp3
k_ECheckFileSignatureNoSignaturesFoundForThisFile4

EGamepadTextInputLineMode

控制大屏幕游戏手柄文本输入允许的行数。

名称描述
k_EGamepadTextInputLineModeSingleLine0
k_EGamepadTextInputLineModeMultipleLines1

EGamepadTextInputMode

大屏幕游戏手柄文本条目的输入模式。

名称描述
k_EGamepadTextInputModeNormal0
k_EGamepadTextInputModePassword1

EFloatingGamepadTextInputMode

控制悬浮键盘的模式。

名称描述
k_EFloatingGamepadTextInputModeModeSingleLine0按下 Enter 键即关闭键盘。
k_EFloatingGamepadTextInputModeModeMultipleLines1用户需要明确关闭键盘。
k_EFloatingGamepadTextInputModeModeEmail2以特殊模式显示键盘,输入电子邮件更为容易。
k_EFloatingGamepadTextInputModeModeNumeric3已显示数字键盘。

ESteamAPICallFailure

GetAPICallFailureReason 返回的 Steam API 调用失败结果。

名称描述
k_ESteamAPICallFailureNone-1无失败。
k_ESteamAPICallFailureSteamGone0本地 Steam 进程已停止响应,有可能已被强行关闭或冻结。
k_ESteamAPICallFailureNetworkFailure1Steam 服务器的网络连接已丢失,或已被破坏。
SteamServersDisconnected_t 回调将在同一时间发出,当客户端能够再次与 Steam 服务器通信时,将发送 SteamServersConnected_t 回调。
k_ESteamAPICallFailureInvalidHandle2传入的 SteamAPICall_t 句柄不再存在。
k_ESteamAPICallFailureMismatchedCallback3调用 GetAPICallResult 时使用了此 API 调用的错误回调类型。

常量

以下是定义来与 ISteamUtils 一起使用的常量。

名称类型描述
STEAMUTILS_INTERFACE_VERSIONconst char *"SteamUtils009"