Интерфейс управления инвентарём Steam.
Дополнительная информация доступна в разделе «
Служба инвентаря Steam».
Функции-члены
Функции-члены
ISteamInventory
вызываются с помощью глобальной функции доступа
SteamInventory()
.
AddPromoItem
bool AddPromoItem( SteamInventoryResult_t *pResultHandle, SteamItemDef_t itemDef );
Название | Тип | Описание |
pResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
itemDef | SteamItemDef_t | Определение предмета (ItemDef), который требуется передать игроку. |
Выдаёт конкретный одноразовый промо-предмет текущему пользователю.
Этот вызов может быть отправлен из клиента, поскольку предметы, которые он может вызвать, может быть заблокирован с помощью правил определений предметов. Одним из основных сценариев для этого вызова является выдача предмета пользователям, которые владеют конкретной другой игрой. Это можно использовать, если в вашей игре есть особый интерфейс для показа конкретного промо-предмета пользователю, в противном случае, если вы хотите выдать несколько промо-предметов, используйте
AddPromoItems или
GrantPromoItems.
Все предметы, которые могут быть выданы, ОБЯЗАНЫ иметь атрибут "promo" в определении предмета. В нём должен быть список номеров приложений, которыми должен владеть пользователь для выдачи ему данного предмета. Эта версия выдаст все предметы, у которых есть атрибуты promo, указанные для них в определениях предметов. Это позволяет добавить дополнительные предметы без необходимости обновлять игровой клиент. К примеру, следующий код выдаст предмет, если пользователь владеет TF2 или SpaceWar.
promo: owns:440;owns:480
Возвращает: bool
Эта функция всегда возвращает
true если вызывается обычным пользователем, и
false если вызывается SteamGameServer.
При успехе результат действий с инвентарём будет включать предметы, которые были выданы (если они выданы). Если предметы не выданы, поскольку пользователь не удовлетворяет требованиям, это всё равно считается успешным вызовом.
Возвращает дескриптор нового результата с помощью
pResultHandle
.
ВНИМАНИЕ: обязательно вызвать
DestroyResult в отношении полученного результата, когда вы закончили действия с ним.
Пример:void CInventory::GrantPromoItems()
{
SteamInventory()->AddPromoItem( &s_GenerateRequestResult, 110 );
}
AddPromoItems
bool AddPromoItems( SteamInventoryResult_t *pResultHandle, const SteamItemDef_t *pArrayItemDefs, uint32 unArrayLength );
Название | Тип | Описание |
pResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
pArrayItemDefs | const SteamItemDef_t * | Список предметов, выдаваемых пользователю. |
unArrayLength | uint32 | Число предметов в pArrayItemDefs . |
Grant a specific one-time promotional item to the current user.
Этот вызов может быть отправлен из клиента, поскольку предметы, которые он может вызвать, может быть заблокирован с помощью правил определений предметов. Одним из основных сценариев для этого вызова является выдача предмета пользователям, которые владеют конкретной другой игрой. Если вы хотите выдать один промо-предмет, используйте
AddPromoItem. Если вы хотите выдать все возможные промо-предметы, используйте
GrantPromoItems.
Все предметы, которые могут быть выданы, ОБЯЗАНЫ иметь атрибут "promo" в определении предмета. В нём должен быть список номеров приложений, которыми должен владеть пользователь для выдачи ему данного предмета. Эта версия выдаст все предметы, у которых есть атрибуты promo, указанные для них в определениях предметов. Это позволяет добавить дополнительные предметы без необходимости обновлять игровой клиент. К примеру, следующий код выдаст предмет, если пользователь владеет TF2 или SpaceWar.
promo: owns:440;owns:480
Возвращает: bool
Эта функция всегда возвращает
true если вызывается обычным пользователем, и
false если вызывается SteamGameServer.
При успехе результат действий с инвентарём будет включать предметы, которые были выданы (если они выданы). Если предметы не выданы, поскольку пользователь не удовлетворяет требованиям, это всё равно считается успешным вызовом.
Возвращает дескриптор нового результата с помощью
pResultHandle
.
ВНИМАНИЕ: обязательно вызвать
DestroyResult в отношении полученного результата, когда вы закончили действия с ним.
Пример:void CInventory::GrantPromoItems()
{
SteamItemDef_t newItems[2];
newItems[0] = 110;
newItems[1] = 111;
SteamInventory()->AddPromoItems( &s_GenerateRequestResult, newItems, 2 );
}
CheckResultSteamID
bool CheckResultSteamID( SteamInventoryResult_t resultHandle, CSteamID steamIDExpected );
Название | Тип | Описание |
resultHandle | SteamInventoryResult_t | Дескриптор результата действий с инвентарём, для которого проверяется SteamID. |
steamIDExpected | CSteamID | Проверяемый SteamID. |
Проверяет, принадлежит ли дескриптор результата действий с инвентарём указанному SteamID.
Это важно при использовании
DeserializeResult, поскольку позволяет удостовериться, что удалённый игрок не делает вид, что он владеет инвентарём другого пользователя.
Возвращаемые значения: bool
true, если результат принадлежит указанному SteamID, в противном случае
false.
ConsumeItem
bool ConsumeItem( SteamInventoryResult_t *pResultHandle, SteamItemInstanceID_t itemConsume, uint32 unQuantity );
Название | Тип | Описание |
pResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
itemConsume | SteamItemInstanceID_t | ID экземпляра потребляемого предмета. |
unQuantity | uint32 | Число потребляемых предметов в этом стеке. |
Потребляет предметы из инвентаря пользователя. Если число данных предметов после этого действия будет равно нулю, предмет удаляется из инвентаря.
Как только предмет удалён, он не может быть восстановлен. Это не для слабонервных — если в вашей игре реализовано полное удаление предметов, рекомендуется иметь интерфейс подтверждения этого процесса.
Возвращает: bool
Эта функция всегда возвращает
true если вызывается обычным пользователем, и
false если вызывается SteamGameServer.
Возвращает дескриптор нового результата с помощью
pResultHandle
.
ВНИМАНИЕ: обязательно вызвать
DestroyResult в отношении полученного результата, когда вы закончили действия с ним.
См. также: ExchangeItems,
TransferItemQuantityПример:void CInventory::DrinkOnePotion( SteamItemInstanceID_t itemID )
{
SteamInventory()->ConsumeItem( &s_ConsumeRequestResult, itemID, 1 );
}
DeserializeResult
bool DeserializeResult( SteamInventoryResult_t *pOutResultHandle, const void *pBuffer, uint32 unBufferSize, bool bRESERVED_MUST_BE_FALSE = false );
Название | Тип | Описание |
pOutResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
pBuffer | const void * | Буфер, который требуется десериализовать. |
unBufferSize | uint32 | Размер pBuffer . |
bRESERVED_MUST_BE_FALSE | bool | Обязательно равняться false! |
Десериализует набор результатов и подтверждает байты подписи.
У этого вызова есть режим потенциального мягкого сбоя, при котором состояние дескриптора задаётся как
k_EResultExpired. В этом режиме
GetResultItems будет успешным вызовом. Результат "expired" может означать, что данные могли устареть: не только по времени (1 час), но и потому, что один из предметов в наборе результатов мог быть обменян или потреблен с того времени, как был сгенерирован набор результатов. Вы можете сравнить временную метку из
GetResultTimestamp с
ISteamUtils::GetServerRealTime, чтобы определить, насколько устарели данные. Вы можете просто проигнорировать код результата "expired" и продолжить как обычно, либо запросить у игрока с устаревшими данными новый набор результатов.
Чтобы удостовериться, что удалённый игрок не делает вид, что он владеет инвентарём другого пользователя, вы должны вызвать
CheckResultSteamID с дескриптором результата после его завершения.
ВНИМАНИЕ: параметр
bRESERVED_MUST_BE_FALSE
зарезервирован на будущее, его запрещено приравнивать к true.
Возвращает: bool
Всегда возвращает
true после чего предоставляет коды ошибок в
GetResultStatus.
Возвращает дескриптор нового результата с помощью
pResultHandle
.
ВНИМАНИЕ: обязательно вызвать
DestroyResult в отношении полученного результата, когда вы закончили действия с ним.
DestroyResult
void DestroyResult( SteamInventoryResult_t resultHandle );
Название | Тип | Описание |
resultHandle | SteamInventoryResult_t | Уничтожаемый дескриптор результата действий с инвентарём. |
Уничтожает дескриптор результата и освобождает всю связанную память.
ExchangeItems
bool ExchangeItems( SteamInventoryResult_t *pResultHandle, const SteamItemDef_t *pArrayGenerate, const uint32 *punArrayGenerateQuantity, uint32 unArrayGenerateLength, const SteamItemInstanceID_t *pArrayDestroy, const uint32 *punArrayDestroyQuantity, uint32 unArrayDestroyLength );
Название | Тип | Описание |
pResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
pArrayGenerate | const SteamItemDef_t * | Список предметов, которые будут созданы этим вызовом. На данный момент может быть только один предмет! |
punArrayGenerateQuantity | const uint32 * | Количество предметов, создаваемых в pArrayGenerate . На данный момент может быть только один предмет, должно быть приравнено к 1! |
unArrayGenerateLength | uint32 | Число предметов в pArrayGenerate и punArrayGenerateQuantity . На данный момент должно быть приравнено к 1! |
pArrayDestroy | const SteamItemInstanceID_t * | Список предметов, которые будут уничтожены этим вызовом. |
punArrayDestroyQuantity | const uint32 * | Количество предметов, уничтожаемых в pArrayDestroy . |
unArrayDestroyLength | uint32 | Число предметов в pArrayDestroy и punArrayDestroyQuantity . |
Выдаёт один предмет в обмен на набор других предметов.
Используется, чтобы реализовать ковку предметов или превращения, либо предметы, при распаковке которых получаются другие предметы (к примеру, ящики).
Сторона, вызывающая этот API, передаёт зарегистрированный предмет и массив существующих предметов для обмена и их количества. API принимает массив генерируемых предметов, но пока что как размер этого массива, так и количество новых предметов должны быть равны единице.
Все предметы, которые могут быть выданы, ОБЯЗАНЫ иметь атрибут exchange в определении предмета. Атрибут exchange определяет те наборы параметров, которые являются разрешёнными рецептами обмена для этого предмета. Рецепты обмена автоматически оцениваются службой инвентаря. Если предоставленные компоненты не соответствуют рецепту, или их не хватает, обмен не состоится.
Пример:
exchange: 101x1,102x1;103x5;104x3,105x3
Этот код позволит предмету быть обменянным на один предмет №101 и один №102, либо на пять предметов №105, либо на три предмета №104 и три №105. Дополнительная информация доступна в разделе «
Схема инвентаря Steam».
Возвращает: bool
Эта функция возвращает
true, что означает успешное выполнение, либо
false если она была вызвана SteamGameServer или если
unArrayGenerateLength
или
punArrayGenerateQuantity
не приравнены к единице
1.
Если обмен не соответствует рецепту, либо компонентов недостаточно, он не будет выполнен.
Возвращает дескриптор нового результата с помощью
pResultHandle
.
ВНИМАНИЕ: обязательно вызвать
DestroyResult в отношении полученного результата, когда вы закончили действия с ним.
См. также: ConsumeItem,
TransferItemQuantityПример:// Найдём предмет с данным itemdef в инвентаре пользователя
SteamItemInstanceID_t CInventory::GetItemIdFromInventory( SteamItemDef_t itemDefId );
void CInventory::Exchange()
{
SteamItemInstanceID_t inputItems[2];
uint32 inputQuantities[2];
inputItems[0] = GetItemIdFromInventory( 103 );
inputQuantities[0] = 3;
inputItems[1] = GetItemIdFromInventory( 104 );
inputQuantities[1] = 3;
SteamItemDef_t outputItems[1];
outputItems[0] = 100;
uint32 outputQuantity[1];
outputQuantity[0] = 1;
SteamInventory()->ExchangeItems( &s_ExchangeRequestResult, outputItems, outputQuantity, 1, inputItems, inputQuantities, 2 );
}
GenerateItems
bool GenerateItems( SteamInventoryResult_t *pResultHandle, const SteamItemDef_t *pArrayItemDefs, const uint32 *punArrayQuantity, uint32 unArrayLength );
Название | Тип | Описание |
pResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
pArrayItemDefs | const SteamItemDef_t * | Список предметов, выдаваемых пользователю. |
punArrayQuantity | const uint32 * | Количество каждого выдаваемого предмета в pArrayItemDefs . Этот параметр необязателен, укажите NULL, чтобы передать единицу каждого предмета. |
unArrayLength | uint32 | Число предметов в pArrayItemDefs . |
Выдаёт конкретные предметы текущему пользователю, только для разработчиков.
Этот интерфейс предназначен только для прототипирования: его могут использовать только те аккаунты Steam, которые входят в издательскую группы вашей игры.
Вы можете передать массив предметов, идентифицированных с помощью
SteamItemDef_t, а также, при желании, второй массив с количеством для каждого предмета. Длина массивов должна совпадать.
Возвращает: bool
Эта функция всегда возвращает
true если вызывается обычным пользователем, и
false если вызывается SteamGameServer.
Возвращает дескриптор нового результата с помощью
pResultHandle
.
ВНИМАНИЕ: обязательно вызвать
DestroyResult в отношении полученного результата, когда вы закончили действия с ним.
Пример:void CInventory::GrantTestItems()
{
SteamItemDef_t newItems[2];
uint32 quantities[2];
newItems[0] = 110;
newItems[1] = 111;
quantities[0] = 1;
quantities[1] = 1;
SteamInventory()->GenerateItems( &s_GenerateRequestResult, newItems, quantities, 2 );
}
GetAllItems
bool GetAllItems( SteamInventoryResult_t *pResultHandle );
Название | Тип | Описание |
pResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
Начинает получение всех предметов в инвентаре текущего пользователя.
ВНИМАНИЕ: число вызовов данной функции может быть ограничено. Если она будет вызываться слишком часто, она может возвращать кэшированные результаты. Рекомендуется вызывать эту функцию, только если вы хотите показать весь инвентарь пользователя, либо если вы считаете, что инвентарь изменился.
Возвращает: bool
Эта функция всегда возвращает
true если вызывается обычным пользователем, и
false если вызывается SteamGameServer.
Возвращает дескриптор нового результата с помощью
pResultHandle
.
ВНИМАНИЕ: обязательно вызвать
DestroyResult в отношении полученного результата, когда вы закончили действия с ним.
К примеру:void SpaceWarItem::LoadInventory( IGameEngine *pGameEngine )
{
SteamInventory()->GetAllItems( &s_RequestResult );
}
GetEligiblePromoItemDefinitionIDs
bool GetEligiblePromoItemDefinitionIDs( CSteamID steamID, SteamItemDef_t *pItemDefIDs, uint32 *punItemDefIDsArraySize );
Название | Тип | Описание |
steamID | CSteamID | SteamID пользователя, для которого предназначены эти предметы. Должно совпадать с SteamInventoryEligiblePromoItemDefIDs_t.m_steamID . |
pItemDefIDs | SteamItemDef_t * | Возвращает номера определений предметов, копируя их в этот массив. |
punItemDefIDsArraySize | uint32 * | Должно быть той же длины, что и pItemDefIDs , и совпадать с SteamInventoryEligiblePromoItemDefIDs_t.m_numEligiblePromoItemDefs . |
Получает список предметов, которые могут быть выданы пользователю.
Для получения номеров определений вы должны выполнить этот вызов при обработке результата вызова
SteamInventoryEligiblePromoItemDefIDs_t.
Возвращает: bool
См. также: AddPromoItem,
AddPromoItemsGetItemDefinitionIDs
bool GetItemDefinitionIDs( SteamItemDef_t *pItemDefIDs, uint32 *punItemDefIDsArraySize );
Название | Тип | Описание |
pItemDefIDs | SteamItemDef_t * | Возвращает определения предметов, копируя их в этот массив. |
punItemDefIDsArraySize | uint32 * | Должно быть приравнено к длине pItemDefIDs . Если pItemDefIDs будет равно NULL, вернёт число элементов, которое должно содержаться в массиве. |
Возвращает набор всех номеров определений предметов, которые определены на панели управления партнёрского сайта.
Эти номера не обязательно являются последовательными.
Этот вызов выполняется в ответ на обратный вызов
SteamInventoryDefinitionUpdate_t. Нет необходимости выполнять этот вызов, если номера определений жёстко закодированы в игре (к примеру, фиолетовая маска = 20, синяя модификация оружия = 55), и она не позволяет добавлять новые типы предметов без обновлений клиента.
Возвращает: bool
Возвращает
true, если вызов успешен. Возвращает
false, только если определения предметов не были загружены с сервера, либо для текущего приложения нет определений предметов.
Если вызов успешен,
punItemDefIDsArraySize
будет содержать число доступных определений предметов.
GetItemDefinitionProperty
bool GetItemDefinitionProperty( SteamItemDef_t iDefinition, const char *pchPropertyName, char *pchValueBuffer, uint32 *punValueBufferSizeOut );
Название | Тип | Описание |
iDefinition | SteamItemDef_t | Определение предмета, для которого требуется получить свойства. |
pchPropertyName | const char * | Название свойства, для которого требуется получить значение. Если передать NULL, pchValueBuffer будет содержать список всех доступных названий свойств (разделитель — запятая). |
pchValueBuffer | char * | Возвращает значение, связанное с pchPropertyName . |
punValueBufferSizeOut | uint32 * | Это должно быть приравнено к размеру pchValueBuffer . Возвращает число байтов, необходимое для хранения значения. |
Получает строковое свойство из указанного определения предмета.
Получает значение свойства для указанного определения предмета.
Обратите внимание, что некоторые свойства (к примеру, "name") могут быть локализованы, и зависят от текущих языковых настроек (см.
ISteamApps::GetCurrentGameLanguage). Названия свойств всегда буквенно-цифровые (могут содержать знак _) и возвращаются в формате ASCII.
Передайте
NULL в
pchPropertyName
, чтобы получить список всех доступных названий свойств (разделитель — запятая). В этом случае
punValueBufferSizeOut
будет содержать предлагаемый размер буфера. В противном случае он будет равен числу байтов, скопированных в
pchValueBuffer
.
Возвращает: bool
Возвращает
true, если вызов успешен. В противном случае
false, что означает, что определения предметов не были загружены с сервера, либо для текущего приложения нет определений предметов, либо название свойства не найдено в определении предмета.
Связанное значение возвращается с помощью
pchValueBuffer
, а общее число байтов, необходимых для хранения значения доступно в
punValueBufferSizeOut
. Рекомендуется вызывать эту функцию дважды, первый раз с
pchValueBuffer
, приравненным к
NULL и
punValueBufferSizeOut
равным нулю, чтобы получить требуемый для буфера размер для последующего вызова.
Вывод будет выглядеть примерно так:
pchPropertyName
приравнено к
NULL:
appid,itemdefid,Timestamp
и т. д.
pchPropertyName
приравнено к
"name":
SW_DECORATION_HAT
ВНИМАНИЕ: Call
LoadItemDefinitions first, to ensure that items are ready to be used before calling GetItemDefinitionProperty.
GetItemsByID
bool GetItemsByID( SteamInventoryResult_t *pResultHandle, const SteamItemInstanceID_t *pInstanceIDs, uint32 unCountInstanceIDs );
Название | Тип | Описание |
pResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
pInstanceIDs | const SteamItemInstanceID_t * | Список номеров экземпляров предметов, состояние которых требует обновить. |
unCountInstanceIDs | uint32 | Число предметов в pInstanceIDs . |
Gets the state of a subset of the current user's inventory.
The subset is specified by an array of item instance IDs.
The results from this call can be serialized using
SerializeResult and passed to other players to "prove" that the current user owns specific items, without exposing the user's entire inventory. For example, you could call this with the IDs of the user's currently equipped items and serialize this to a buffer, and then transmit this buffer to other players upon joining a game.
Возвращает: bool
This function always returns
true when called by a regular user, and always returns
false when called from SteamGameServer.
Returns a new result handle via
pResultHandle
.
ВНИМАНИЕ: You must call
DestroyResult on the provided inventory result when you are done with it.
GetItemPrice
bool GetItemPrice( SteamItemDef_t iDefinition, uint64 *pPrice );
Название | Тип | Описание |
iDefinition | SteamItemDef_t | ID определения предмета, для которого необходимо получить цену |
pPrice | uint64* | Указатель цены для заполнения. Цены указаны в местной валюте пользователя. |
After a successful call to
RequestPrices, you can call this method to get the pricing for a specific item definition.
Возвращает: bool
true upon success, indicating that
pPrice
has been successfully filled with the price for the given item definition id.
false, if the parameters are invalid or if there is no price for the given item definition id.
См. также: RequestPricesGetItemsWithPrices
bool GetItemsWithPrices( SteamItemDef_t *pArrayItemDefs, uint64 *pPrices, uint32 unArrayLength );
Название | Тип | Описание |
pArrayItemDefs | SteamItemDef_t * | Массив номеров определений предмета для заполнения |
pPrices | uint64* | Массив цен для каждого соответствующего номера определений предметов в pArrayItemDefs. Цены указаны в местной валюте пользователя. |
unArrayLength | uint32 | Должно быть той же длины, что и массивы pArrayItemDefs и pPrices , полученных в результате вызова GetNumItemsWithPrices . |
After a successful call to
RequestPrices, you can call this method to get all the pricing for applicable item definitions. Use the result of
GetNumItemsWithPrices as the the size of the arrays that you pass in.
Возвращаемые значения: bool
true upon success, indicating that
pArrayItemDefs
and
pPrices
have been successfully filled with the item definition ids and prices of items that are for sale.
false if the parameters are invalid
См. также: RequestPrices,
GetItemPriceGetNumItemsWithPrices
uint32 GetNumItemsWithPrices();
After a successful call to
RequestPrices, this will return the number of item definitions with valid pricing.
Returns: uint32См. также: RequestPrices,
GetItemsWithPricesGetResultItemProperty
bool GetResultItemProperty( SteamInventoryResult_t resultHandle, uint32 unItemIndex, const char *pchPropertyName, char *pchValueBuffer, uint32 *punValueBufferSizeOut );
Название | Тип | Описание |
resultHandle | SteamInventoryResult_t | Дескриптор результата, содержащий предмет, для которого требуется получить свойства. |
unItemIndex | uint32 | |
pchPropertyName | const char * | Название свойства, для которого требуется получить значение. Если передать NULL, pchValueBuffer будет содержать список всех доступных названий свойств (разделитель — запятая). |
pchValueBuffer | char * | Возвращает значение, связанное с pchPropertyName . |
punValueBufferSizeOut | uint32 * | Это должно быть приравнено к размеру pchValueBuffer . Возвращает число байтов, необходимое для хранения значения. |
Gets the dynamic properties from an item in an inventory result set.
Property names are always composed of ASCII letters, numbers, and/or underscores.
If the results do not fit in the given buffer, partial results may be copied.
Возвращаемые значения: bool
This returns
true upon success; otherwise,
false indicating that the inventory result handle was invalid or the provided index does not contain an item.
GetResultItems
bool GetResultItems( SteamInventoryResult_t resultHandle, SteamItemDetails_t *pOutItemsArray, uint32 *punOutItemsArraySize );
Название | Тип | Описание |
resultHandle | SteamInventoryResult_t | Дескриптор результата действий с инвентарём, для которого требуется получить предметы. |
pOutItemsArray | SteamItemDetails_t * | Информация копируется в этот массив. |
punOutItemsArraySize | uint32 * | Должно быть приравнено к длине pOutItemsArray . Если pOutItemsArray будет равно NULL, вернёт число элементов, которое должно содержаться в массиве. |
Get the items associated with an inventory result handle.
Returns: bool
true, if the call was successful, otherwise
false.
Potential failure reasons include:
-
resultHandle
оказался недействительным, либо дескриптор результата действий с инвентарём оказался не готов.
- Массив не уместился в
pOutItemsArray
.
- У пользователя нет предметов.
If the call is successful then
punItemDefIDsArraySize
will contain the number of item definitions available.
К примеру:bool bGotResult = false;
std::vector<SteamItemDetails_t> vecDetails;
uint32 count = 0;
if ( SteamInventory()->GetResultItems( callback->m_handle, NULL, &count ) )
{
vecDetails.resize( count );
bGotResult = SteamInventory()->GetResultItems( callback->m_handle, vecDetails.data(), &count );
}
GetResultStatus
EResult GetResultStatus( SteamInventoryResult_t resultHandle );
Название | Тип | Описание |
resultHandle | SteamInventoryResult_t | Дескриптор результата действий с инвентарём, для которого требуется получить состояние. |
Find out the status of an asynchronous inventory result handle.
This is a polling equivalent to registering a callback function for
SteamInventoryResultReady_t.
Returns: EResultWhether the call was successful or not.
Possible values:
Example:void SpaceWarItem::CheckInventory( IGameEngine *pGameEngine )
{
if ( s_RequestResult != 0 )
{
EResult result = SteamInventory()->GetResultStatus( s_RequestResult );
if ( result == k_EResultOK )
{
// Делаем что-то здесь
}
}
}
GetResultTimestamp
uint32 GetResultTimestamp( SteamInventoryResult_t resultHandle );
Название | Тип | Описание |
resultHandle | SteamInventoryResult_t | Дескриптор результата действий с инвентарём, для которого требуется получить метку времени. |
Gets the server time at which the result was generated.
Возвращаемые значения: uint32The timestamp is provided as Unix epoch time (Time since Jan 1st, 1970)
You can compare this value against
ISteamUtils::GetServerRealTime to determine the age of the result.
GrantPromoItems
bool GrantPromoItems( SteamInventoryResult_t *pResultHandle );
Название | Тип | Описание |
pResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
Grant all potential one-time promotional items to the current user.
This can be safely called from the client because the items it can grant can be locked down via policies in the itemdefs. One of the primary scenarios for this call is to grant an item to users who also own a specific other game. If you want to grant specific promotional items rather than all of them see:
AddPromoItem and
AddPromoItems.
Any items that can be granted MUST have a "promo" attribute in their itemdef. That promo item list a set of APPIDs that the user must own to be granted this given item. This version will grant all items that have promo attributes specified for them in the configured item definitions. This allows adding additional promotional items without having to update the game client. For example the following will allow the item to be granted if the user owns either TF2 or SpaceWar.
promo: owns:440;owns:480
Возвращает: bool
This function always returns
true when called by a regular user, and always returns
false when called from SteamGameServer.
On success, the inventory result will include items which were granted, if any. If no items were granted because the user isn't eligible for any promotions, this is still considered a success.
Returns a new result handle via
pResultHandle
.
ВНИМАНИЕ: You must call
DestroyResult on the provided inventory result when you are done with it.
Пример:void CInventory::GrantPromoItems()
{
SteamInventory()->GrantPromoItems( &s_GenerateRequestResult );
}
LoadItemDefinitions
bool LoadItemDefinitions();
Triggers an asynchronous load and refresh of item definitions.
Item definitions are a mapping of "definition IDs" (integers between 1 and 999999999) to a set of string properties. Some of these properties are required to display items on the Steam community web site. Other properties can be defined by applications. There is no reason to call this function if your game hardcoded the numeric definition IDs (e.g. purple face mask = 20, blue weapon mod = 55) and does not allow for adding new item types without a client patch.
Возвращает: bool
Triggers a
SteamInventoryDefinitionUpdate_t callback.
This call will always return
true.
RequestEligiblePromoItemDefinitionsIDs
SteamAPICall_t RequestEligiblePromoItemDefinitionsIDs( CSteamID steamID );
Название | Тип | Описание |
steamID | CSteamID | SteamID пользователя, для которого запрашиваются доступные промо-предметы. |
Request the list of "eligible" promo items that can be manually granted to the given user.
These are promo items of type "manual" that won't be granted automatically. An example usage of this is an item that becomes available every week.
After calling this function you need to call
GetEligiblePromoItemDefinitionIDs to get the actual item definition ids.
Возвращает: SteamAPICall_t to be used with a
SteamInventoryEligiblePromoItemDefIDs_t call result.
Returns
k_uAPICallInvalid if the
steamID
is not a valid individual account.
RequestPrices
SteamAPICall_t RequestPrices();
Request prices for all item definitions that can be purchased in the user's local currency. A
SteamInventoryRequestPricesResult_t call result will be returned with the user's local currency code. After that, you can call
GetNumItemsWithPrices and
GetItemsWithPrices to get prices for all the known item definitions, or
GetItemPrice for a specific item definition.
Возвращает: SteamAPICall_t to be used with a
SteamInventoryRequestPricesResult_t call result.
Returns
k_uAPICallInvalid if there was an internal problem.
См. также: GetNumItemsWithPrices,
GetItemsWithPrices,
GetItemPriceSendItemDropHeartbeat
void SendItemDropHeartbeat();
Deprecated.
SerializeResult
bool SerializeResult( SteamInventoryResult_t resultHandle, void *pOutBuffer, uint32 *punOutBufferSize );
Название | Тип | Описание |
resultHandle | SteamInventoryResult_t | Сериализуемый дескриптор результата действий с инвентарём. |
pOutBuffer | void * | Буфер, в который копируется сериализуемый результат. |
punOutBufferSize | uint32 * | Должно быть того же размера, что и pOutBuffer . Если pOutBuffer равно NULL, вернёт размер, необходимый для хранения массива. |
Serialized result sets contain a short signature which can't be forged or replayed across different game sessions.
A result set can be serialized on the local client, transmitted to other players via your game networking, and deserialized by the remote players. This is a secure way of preventing hackers from lying about posessing rare/high-value items. Serializes a result set with signature bytes to an output buffer. The size of a serialized result depends on the number items which are being serialized. When securely transmitting items to other players, it is recommended to use
GetItemsByID first to create a minimal result set.
Results have a built-in timestamp which will be considered "expired" after an hour has elapsed. See
DeserializeResult for expiration handling.
If this is set
pOutBuffer
to
NULL then
punOutBufferSize
will be set to the buffer size required. So you can make the buffer and then call this again to fill it with the data.
Возвращает: bool
true upon success, indicating that
punOutBufferSize
has been successfully filled with the size of the buffer, and if
pOutBuffer
points to a buffer of sufficient size then it is filled out as well.
false under the following conditions:
- Эта функция вызвана не обычным пользователем. Этот вызов не поддерживается на игровых серверах.
-
resultHandle
оказался недействительным, либо дескриптор результата действий с инвентарём оказался не готов.
- Значение, переданное
punOutBufferSize
было ниже, чем ожидаемое, а pOutBuffer
не равнялся NULL.
StartPurchase
SteamAPICall_t StartPurchase( const SteamItemDef_t *pArrayItemDefs, const uint32 *punArrayQuantity, uint32 unArrayLength );
Название | Тип | Описание |
pArrayItemDefs | SteamItemDef_t * | Массив номеров определений предмета, которые желает приобрести пользователь. |
punArrayQuantity | uint32 * | Массив количеств каждого определения предмета, которые желает приобрести пользователь. |
unArrayLength | uint32 | Должно быть той же длины, что и массивы pArrayItemDefs и punArrayQuantity . |
Starts the purchase process for the user, given a "shopping cart" of item definitions that the user would like to buy. The user will be prompted in the Steam Overlay to complete the purchase in their local currency, funding their Steam Wallet if necessary, etc.
If the purchase process was started successfully, then
m_ulOrderID
and
m_ulTransID
will be valid in the
SteamInventoryStartPurchaseResult_t call result.
If the user authorizes the transaction and completes the purchase, then the callback
SteamInventoryResultReady_t will be triggered and you can then retrieve what new items the user has acquired.
NOTE: You must call
DestroyResult on the inventory result for when you are done with it.
Возвращаемые значения: SteamAPICall_t to be used with a
SteamInventoryStartPurchaseResult_t call result.
Returns
k_uAPICallInvalid if the input was invalid.
Тестирование во время разработки: при тестировании StartPurchase до выпуска приложения все операции, совершённые участниками разработки или издателями, в системе будут проводиться через API микротранзакций экспериментальной среды (sandbox). Это означает, что с вас не будут списаны средства за покупки, совершённые до выпуска приложения, если вы являетесь издателем Steamworks.
TransferItemQuantity
bool TransferItemQuantity( SteamInventoryResult_t *pResultHandle, SteamItemInstanceID_t itemIdSource, uint32 unQuantity, SteamItemInstanceID_t itemIdDest );
Transfer items between stacks within a user's inventory.
This can be used to stack, split, and moving items. The source and destination items must have the same itemdef id. To move items onto a destination stack specify the source, the quantity to move, and the destination item id. To split an existing stack, pass
k_SteamItemInstanceIDInvalid into
itemIdDest
. A new item stack will be generated with the requested quantity.
NOTE: Tradability/marketability restrictions are copied along with transferred items. The destination stack receives the latest tradability/marketability date of any item in its composition.
Возвращаемые значения: bool
This function always returns
true when called by a regular user, and always returns
false when called from SteamGameServer.
Returns a new result handle via
pResultHandle
.
NOTE: You must call
DestroyResult on the provided inventory result when you are done with it.
См. также: ConsumeItem,
ExchangeItemsExample:void CInventory::CombineItems()
{
SteamInventoryResult_t transferResult;
// отделяем 2 предмета из текущего стека
SteamItemInstanceID_t bigStack = GetItemIdFromInventory( ... );
SteamInventory()->TransferItemQuantity( &transferResult, bigStack, 1, k_SteamItemInstanceIDInvalid );
// перемещаем 2 предмета из стека A в стек B
SteamItemInstanceID_t originStack = GetItemIdFromInventory( ... );
SteamItemInstanceID_t destStack = GetItemIdFromInventory( ... );
SteamInventory()->TransferItemQuantity( &transferResult, originStack, 2, destStack );
}
TriggerItemDrop
bool TriggerItemDrop( SteamInventoryResult_t *pResultHandle, SteamItemDef_t dropListDefinition );
Название | Тип | Описание |
pResultHandle | SteamInventoryResult_t * | Возвращает дескриптор нового результата действий с инвентарём. |
dropListDefinition | SteamItemDef_t | Этот параметр должен отсылать к предмету типа "playtimegenerator". Дополнительная информация доступна в разделе «Схема инвентаря Steam». |
Trigger an item drop if the user has played a long enough period of time.
This period can be customized in two places:
- На уровне приложения в службе инвентаря: выдача предметов за время в игре. Эта настройка автоматически применяется ко всем предметам типа "playtimegenerator", для которых не указаны другие, более приоритетные значения.
- На уровне конкретного определения "playtimegenerator". Эта настройка будет иметь приоритет над значением, заданном на уровне приложения.
Only item definitions which are marked as "playtime item generators" can be spawned.
Typically this function should be called at the end of a game or level or match or any point of significance in the game in which an item drop could occur. The granularity of the playtime generator settings is in minutes, so calling it more frequently than minutes is not useful and will be rate limited in the Steam client. The Steam servers will perform playtime accounting to prevent too-frequent drops. The servers will also manage adding the item to the players inventory.
Returns: bool
This function always returns
true when called by a regular user, and always returns
false when called from SteamGameServer.
Returns a new result handle via
pResultHandle
.
ВНИМАНИЕ: You must call
DestroyResult on the provided inventory result when you are done with it.
The inventory result returned by this function will be the new item granted if the player is eligible. If the user is not eligible then it will return an empty result ('[]').
Пример:void CInventory::FinishGame()
{
SteamInventory()->TriggerItemDrop( &s_PlaytimeRequestResult, 10 );
}
StartUpdateProperties
SteamInventoryUpdateHandle_t StartUpdateProperties();
Starts a transaction request to update
dynamic properties on items for the current user. This call is rate-limited by user, so property modifications should be batched as much as possible (e.g. at the end of a map or game session). After calling
SetProperty or
RemoveProperty for all the items that you want to modify, you will need to call
SubmitUpdateProperties to send the request to the Steam servers. A
SteamInventoryResultReady_t callback will be fired with the results of the operation.
Example:void CInventory::FinishLevel()
{
SteamInventoryUpdateHandle_t updateHandle = SteamInventory()->StartUpdateProperties();
for ( SteamItemInstanceID_t itemid : m_vecItemIDs )
{
SteamInventory()->SetProperty( updateHandle, itemid, "string_value", "blah" );
SteamInventory()->SetProperty( updateHandle, itemid, "bool_value", true );
SteamInventory()->SetProperty( updateHandle, itemid, "int64_value", (int64)55 );
SteamInventory()->SetProperty( updateHandle, itemid, "float_value", 123.456f );
}
SteamInventoryResult_t resultHandle;
SteamInventory()->SubmitUpdateProperties( updateHandle, &resultHandle );
}
NOTE: You must call
DestroyResult on the provided inventory result for
SubmitUpdateProperties when you are done with it.
Returns: SteamInventoryUpdateHandle_tСм. также: SetProperty,
RemoveProperty,
SubmitUpdatePropertiesSubmitUpdateProperties
bool SubmitUpdateProperties( SteamInventoryUpdateHandle_t handle, SteamInventoryResult_t * pResultHandle );
Submits the transaction request to modify
dynamic properties on items for the current user. See
StartUpdateProperties.
NOTE: You must call
DestroyResult on the provided inventory result for when you are done with it.
Возвращает: bool
See Also: StartUpdateProperties,
SetProperty,
RemovePropertyRemoveProperty
bool RemoveProperty( SteamInventoryUpdateHandle_t handle, SteamItemInstanceID_t nItemID, const char *pchPropertyName );
Removes a
dynamic property for the given item.
Возвращает: bool
См. также: StartUpdateProperties,
SetProperty,
SubmitUpdatePropertiesSetProperty
bool SetProperty( SteamInventoryUpdateHandle_t handle, SteamItemInstanceID_t nItemID, const char *pchPropertyName, const char *pchPropertyValue );
bool SetProperty( SteamInventoryUpdateHandle_t handle, SteamItemInstanceID_t nItemID, const char *pchPropertyName, bool bValue );
bool SetProperty( SteamInventoryUpdateHandle_t handle, SteamItemInstanceID_t nItemID, const char *pchPropertyName, int64 nValue );
bool SetProperty( SteamInventoryUpdateHandle_t handle, SteamItemInstanceID_t nItemID, const char *pchPropertyName, float flValue );
Название | Тип | Описание |
handle | SteamInventoryUpdateHandle_t | Дескриптор обновления, относящийся к запросу транзакции, возвращённому StartUpdateProperties. |
nItemID | SteamItemInstanceID_t | Изменяет номер предмета. |
pchPropertyName | const char* | Добавляет или обновляет динамическое свойство предмета. |
pchPropertyValue | const char* | Задаёт значение строки. |
bValue | bool | Задаёт булево значение. |
nValue | int64 | Задаёт значение 64-битного целого числа. |
flValue | float | Задаёт значение числа с плавающей точкой. |
Sets a
dynamic property for the given item. Supported value types are strings, boolean, 64 bit integers, and 32 bit floats.
Returns: bool
See Also: StartUpdateProperties,
RemoveProperty,
SubmitUpdatePropertiesОбратные вызовы
These are callbacks which can be fired by calling
SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of
ISteamInventory
.
SteamInventoryDefinitionUpdate_t
This callback is triggered whenever item definitions have been updated, which could be in response to
LoadItemDefinitions or any time new item definitions are available (eg, from the dynamic addition of new item types while players are still in-game).
This callback has no fields.
Связанные функции: LoadItemDefinitionsSteamInventoryEligiblePromoItemDefIDs_t
Returned when you have requested the list of "eligible" promo items that can be manually granted to the given user. These are promo items of type "manual" that won't be granted automatically. An example usage of this is an item that becomes available every week.
Название | Тип | Описание |
m_result | EResult | k_EResultOK при успехе. Любое другое значение означает сбой. |
m_steamID | CSteamID | SteamID пользователя, для которого предназначены эти предметы. |
m_numEligiblePromoItemDefs | int | Число доступных промо-предметов, которые могут быть выданы этому пользователю. Вы должны создать буфер SteamItemDef_t, и использовать его в GetEligiblePromoItemDefinitionIDs для получения определений предметов. |
m_bCachedData | bool | Означает, что данные получены из кэша, а не с сервера. Это происходит, если пользователь не залогинен, либо не удаётся соединиться с серверами Steam по какой-то другой причине. |
Связанные функции: RequestEligiblePromoItemDefinitionsIDsSteamInventoryFullUpdate_t
Triggered when GetAllItems successfully returns a result which is newer / fresher than the last known result. (It will not trigger if the inventory hasn't changed, or if results from two overlapping calls are reversed in flight and the earlier result is already known to be stale/out-of-date.)
The regular
SteamInventoryResultReady_t callback will still be triggered immediately afterwards; this is an additional notification for your convenience.
SteamInventoryResultReady_t
This is fired whenever an inventory result transitions from
k_EResultPending to any other completed state, see
GetResultStatus for the complete list of states. There will always be exactly one callback per handle.
SteamInventoryStartPurchaseResult_t
Returned after
StartPurchase is called.
Название | Тип | Описание |
m_result | EResult | k_EResultOK при успехе. Любое другое значение означает сбой. |
m_ulOrderID | uint64 | Номер автоматически сгенерированного заказа для активированной покупки. |
m_ulTransID | uint64 | Номер автоматически сгенерированной транзакции для активированной покупки. |
SteamInventoryRequestPricesResult_t
Returned after
RequestPrices is called.
Название | Тип | Описание |
m_result | EResult | k_EResultOK при успехе. Любое другое значение означает сбой. |
m_rgchCurrency | char | Строка указывает код местной валюты пользователя. |
Структуры
These are structs which functions in ISteamInventory may return and/or interact with.
SteamItemDetails_t
Перечисления
These are enums which are defined for use with ISteamInventory.
ESteamItemFlags
These are bitflags that are set in
SteamItemDetails_t.
Название | Значение | Описание |
k_ESteamItemNoTrade | 1 << 0 | Этот предмет заблокирован на этом аккаунте и не может быть обменян или отдан. Это флаг состояния предмета, который навсегда прикреплён к конкретному экземпляру предмета. |
k_ESteamItemRemoved | 1 << 8 | Предмет уничтожен, обменян, устарел или иным образом стал недействительным. Этот флаг подтверждения действия, который устанавливается однажды, как часть результата. |
k_ESteamItemConsumed | 1 << 9 | Количество экземпляров предмета уменьшено на 1 с помощью вызова ConsumeItem. Этот флаг подтверждения действия, который устанавливается однажды, как часть результата. |
Typedefs
These are typedefs which are defined for use with ISteamInventory.
Название | Базовый тип | Описание |
SteamInventoryResult_t | int32 | Дескриптор асинхронного результата действий с инвентарём. |
SteamItemDef_t | int32 | Типы предметов в игре идентифицируются 32-битным номером определения предмета. Номера определений могут располагаться в диапазоне между 1 и 999999999. Номера, равные или меньшие, чем ноль, являются недействительными. Номера, равные или превышающие миллиард (1x10^9), зарезервированы для внутреннего употребления в Steam. |
SteamItemInstanceID_t | uint64 | У каждого экземпляра предмета есть глобальный уникальный ID экземпляра. Этот ID уникален как комбинация идентификаторов игрока и экземпляра конкретного предмета, он не переносится другим игрокам и не используется для других предметов. |
SteamInventoryUpdateHandle_t | uint64 | Возвращается в результате вызова функции StartUpdateProperties, которая инициирует запрос транзакции для изменения динамических свойств предметов для текущего пользователя. |
Константы
These are constants which are defined for use with ISteamInventory.
Название | Тип | Значение | Описание |
k_SteamInventoryResultInvalid | SteamInventoryResult_t | -1 | Недействительный дескриптор результата действий с инвентарём. |
k_SteamItemInstanceIDInvalid | SteamItemInstanceID_t | (SteamItemInstanceID_t)~0 | Недействительный ID экземпляра предмета. Обычно возвращается, когда при выполнении операции произошёл сбой. Рекомендуется инициализировать все новые экземпляры предметов с этим значением. |
STEAMINVENTORY_INTERFACE_VERSION | const char * | "STEAMINVENTORY_INTERFACE_V002" | |