Steamworks Documentation
ISteamInventory Interface
Steam Inventory query and manipulation API.

See Steam Inventory Service for more information.

Member Functions

Member functions for ISteamInventory are called through the global accessor function SteamInventory().

AddPromoItem

bool AddPromoItem( SteamInventoryResult_t *pResultHandle, SteamItemDef_t itemDef );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.
itemDefSteamItemDef_tThe ItemDef to grant the player.

Grant a specific one-time promotional item 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. This can be useful if your game has custom UI for showing a specific promo item to the user otherwise if you want to grant multiple promotional items then use AddPromoItems or GrantPromoItems.

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

Returns: 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.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

Example:
void CInventory::GrantPromoItems() { SteamInventory()->AddPromoItem( &s_GenerateRequestResult, 110 ); }

AddPromoItems

bool AddPromoItems( SteamInventoryResult_t *pResultHandle, const SteamItemDef_t *pArrayItemDefs, uint32 unArrayLength );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.
pArrayItemDefsconst SteamItemDef_t *The list of items to grant the user.
unArrayLengthuint32The number of items in pArrayItemDefs.

Grant a specific one-time promotional item 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 a single promotional item then use AddPromoItem. If you want to grant all possible promo items then use GrantPromoItems.

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

Returns: 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.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

Example:
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 );
NameTypeDescription
resultHandleSteamInventoryResult_tThe inventory result handle to check the Steam ID on.
steamIDExpectedCSteamIDThe Steam ID to verify.

Checks whether an inventory result handle belongs to the specified Steam ID.

This is important when using DeserializeResult, to verify that a remote player is not pretending to have a different user's inventory.

Returns: bool
true if the result belongs to the target steam ID; otherwise, false.

ConsumeItem

bool ConsumeItem( SteamInventoryResult_t *pResultHandle, SteamItemInstanceID_t itemConsume, uint32 unQuantity );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.
itemConsumeSteamItemInstanceID_tThe item instance id to consume.
unQuantityuint32The number of items in that stack to consume.

Consumes items from a user's inventory. If the quantity of the given item goes to zero, it is permanently removed.

Once an item is removed it cannot be recovered. This is not for the faint of heart - if your game implements item removal at all, a high-friction UI confirmation process is highly recommended.

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.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

See Also: ExchangeItems, TransferItemQuantity

Example:
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 );
NameTypeDescription
pOutResultHandleSteamInventoryResult_t *Returns a new inventory result handle.
pBufferconst void *The buffer to deserialize.
unBufferSizeuint32The size of pBuffer.
bRESERVED_MUST_BE_FALSEboolThis must be false!

Deserializes a result set and verifies the signature bytes.

This call has a potential soft-failure mode where the handle status is set to k_EResultExpired. GetResultItems will still succeed in this mode. The "expired" result could indicate that the data may be out of date - not just due to timed expiration (one hour), but also because one of the items in the result set may have been traded or consumed since the result set was generated. You could compare the timestamp from GetResultTimestamp to ISteamUtils::GetServerRealTime to determine how old the data is. You could simply ignore the "expired" result code and continue as normal, or you could request the player with expired data to send an updated result set.

You should call CheckResultSteamID on the result handle when it completes to verify that a remote player is not pretending to have a different user's inventory.

NOTE: The bRESERVED_MUST_BE_FALSE parameter is reserved for future use and should never be set to true.

Returns: bool
Always returns true and then delivers error codes via GetResultStatus.

Returns a new result handle via pResultHandle.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

DestroyResult

void DestroyResult( SteamInventoryResult_t resultHandle );
NameTypeDescription
resultHandleSteamInventoryResult_tThe inventory result handle to destroy.

Destroys a result handle and frees all associated memory.

ExchangeItems

bool ExchangeItems( SteamInventoryResult_t *pResultHandle, const SteamItemDef_t *pArrayGenerate, const uint32 *punArrayGenerateQuantity, uint32 unArrayGenerateLength, const SteamItemInstanceID_t *pArrayDestroy, const uint32 *punArrayDestroyQuantity, uint32 unArrayDestroyLength );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.
pArrayGenerateconst SteamItemDef_t *The list of items that will be created by this call. Currently can only be 1 item!
punArrayGenerateQuantityconst uint32 *The quantity of each item in pArrayGenerate to create. Currently can only be 1 item and it must be set to 1!
unArrayGenerateLengthuint32The number of items in pArrayGenerate and punArrayGenerateQuantity. Currently must be 1!
pArrayDestroyconst SteamItemInstanceID_t *The list of items that will be destroyed by this call.
punArrayDestroyQuantityconst uint32 *The quantity of each item in pArrayDestroy to destroy.
unArrayDestroyLengthuint32The number of items in pArrayDestroy and punArrayDestroyQuantity.

Grant one item in exchange for a set of other items.

This can be used to implement crafting recipes or transmutations, or items which unpack themselves into other items (e.g., a chest).

The caller of this API passes in the requested item and an array of existing items and quantities to exchange for it. The API currently takes an array of items to generate but at this time the size of that array must be 1 and the quantity of the new item must be 1.

Any items that can be granted MUST have an exchange attribute in their itemdef. The exchange attribute specifies a set of recipes that are valid exchanges for this item. Exchange recipes are evaluated atomically by the Inventory Service; if the supplied components do not match the recipe, or do not contain sufficient quantity, the exchange will fail.

For example:
exchange: 101x1,102x1;103x5;104x3,105x3

Will allow the item to be exchanged for either one #101 and one #102, five #103s or three #104s and three #105s. See the Steam Inventory Schema documentation for more details.

Returns: bool
This function returns true indicating success, and returns false when called from SteamGameServer or when unArrayGenerateLength or punArrayGenerateQuantity is not set to 1.

Exchanges that do not match a recipe, or do not provide the required amounts, will fail.

Returns a new result handle via pResultHandle.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

See Also: ConsumeItem, TransferItemQuantity

Example:
// Find an item in the user's inventory with the given 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 );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.
pArrayItemDefsconst SteamItemDef_t *The list of items to grant the user.
punArrayQuantityconst uint32 *The quantity of each item in pArrayItemDefs to grant. This is optional, pass in NULL to specify 1 of each item.
unArrayLengthuint32The number of items in pArrayItemDefs.

Grants specific items to the current user, for developers only.

This API is only intended for prototyping - it is only usable by Steam accounts that belong to the publisher group for your game.

You can pass in an array of items, identified by their SteamItemDef_t and optionally a second array of corresponding quantities for each item. The length of these arrays MUST match!

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.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

Example:
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 );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.

Start retrieving all items in the current users inventory.

NOTE: Calls to this function are subject to rate limits and may return cached results if called too frequently. It is suggested that you call this function only when you are about to display the user's full inventory, or if you expect that the inventory may have changed.

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.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

Example:
void SpaceWarItem::LoadInventory( IGameEngine *pGameEngine ) { SteamInventory()->GetAllItems( &s_RequestResult ); }

GetEligiblePromoItemDefinitionIDs

bool GetEligiblePromoItemDefinitionIDs( CSteamID steamID, SteamItemDef_t *pItemDefIDs, uint32 *punItemDefIDsArraySize );
NameTypeDescription
steamIDCSteamIDThe Steam ID of the user who these items are for. This should be the same as SteamInventoryEligiblePromoItemDefIDs_t.m_steamID.
pItemDefIDsSteamItemDef_t *Returns the item definition ids by copying them into this array.
punItemDefIDsArraySizeuint32 *This should be the length of pItemDefIDs and the same as SteamInventoryEligiblePromoItemDefIDs_t.m_numEligiblePromoItemDefs.

Get the list of item definition ids that a user can be granted.

You should call this while handling a SteamInventoryEligiblePromoItemDefIDs_t call result to pull out the item definition ids.

Returns: bool


See Also: AddPromoItem, AddPromoItems

GetItemDefinitionIDs

bool GetItemDefinitionIDs( SteamItemDef_t *pItemDefIDs, uint32 *punItemDefIDsArraySize );
NameTypeDescription
pItemDefIDsSteamItemDef_t *Returns the item definitions by copying them into this array.
punItemDefIDsArraySizeuint32 *This should be set to the length of pItemDefIDs. If pItemDefIDs is NULL then this will return the number of elements the array needs to hold.

Returns the set of all item definition IDs which are defined in the App Admin panel of the Steamworks website.

These item definitions may not necessarily be contiguous integers.

This should be called in response to a SteamInventoryDefinitionUpdate_t callback. There is no reason to call this function if your game hardcodes the numeric definition IDs (eg, purple face mask = 20, blue weapon mod = 55) and does not allow for adding new item types without a client patch.

Returns: bool
This call returns true upon success. It only returns false if item definitions have not been loaded from the server, or no item defintions exist for the current application.

If the call is successful then punItemDefIDsArraySize will contain the number of item definitions available.

GetItemDefinitionProperty

bool GetItemDefinitionProperty( SteamItemDef_t iDefinition, const char *pchPropertyName, char *pchValueBuffer, uint32 *punValueBufferSizeOut );
NameTypeDescription
iDefinitionSteamItemDef_tThe item definition to get the properties for.
pchPropertyNameconst char *The property name to get the value for. If you pass in NULL then pchValueBuffer will contain a comma-separated list of all the available names.
pchValueBufferchar *Returns the value associated with pchPropertyName.
punValueBufferSizeOutuint32 *This should be set to the size of pchValueBuffer, and returns the number of bytes required to hold the value.

Gets a string property from the specified item definition.
Gets a property value for a specific item definition.

Note that some properties (for example, "name") may be localized and will depend on the current Steam language settings (see ISteamApps::GetCurrentGameLanguage). Property names are always ASCII alphanumeric and underscores.

Pass in NULL for pchPropertyName to get a comma-separated list of available property names. In this mode, punValueBufferSizeOut will contain the suggested buffer size. Otherwise it will be the number of bytes actually copied to pchValueBuffer.

Returns: bool
This returns true upon success; otherwise, false indicating that the item definitions have not been loaded from the server, or no item definitions exist for the current application, or the property name was not found in the item definition.

The associated value is returned via pchValueBuffer, and the total number of bytes required to hold the value is available from punValueBufferSizeOut. It's recommended to call this function twice, the first time with pchValueBuffer set to NULL and punValueBufferSizeOut set to zero to get the size required for the buffer for the subsequent call.

The output looks something like this:
pchPropertyName set to NULL:
appid,itemdefid,Timestamp etc...
pchPropertyName set to "name":
SW_DECORATION_HAT

NOTE: 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 );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.
pInstanceIDsconst SteamItemInstanceID_t *A list of the item instance ids to update the state of.
unCountInstanceIDsuint32The number of items in 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.

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.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

GetItemPrice

bool GetItemPrice( SteamItemDef_t iDefinition, uint64 *pPrice );
NameTypeDescription
iDefinitionSteamItemDef_tThe item definition id to retrieve the price for
pPriceuint64*The price pointer to populate. Prices are rendered in the user's local currency.

After a successful call to RequestPrices, you can call this method to get the pricing for a specific item definition.

Returns: 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.

See Also: RequestPrices

GetItemsWithPrices

bool GetItemsWithPrices( SteamItemDef_t *pArrayItemDefs, uint64 *pPrices, uint32 unArrayLength );
NameTypeDescription
pArrayItemDefsSteamItemDef_t *The array of item definition ids to populate
pPricesuint64*The array of prices for each corresponding item definition id in pArrayItemDefs. Prices are rendered in the user's local currency.
unArrayLengthuint32This should be the length of pArrayItemDefs and pPrices arrays, which are derived from the result of calling 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.

Returns: 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

See Also: RequestPrices, GetItemPrice

GetNumItemsWithPrices

uint32 GetNumItemsWithPrices();
After a successful call to RequestPrices, this will return the number of item definitions with valid pricing.

Returns: uint32

See Also: RequestPrices, GetItemsWithPrices

GetResultItemProperty

bool GetResultItemProperty( SteamInventoryResult_t resultHandle, uint32 unItemIndex, const char *pchPropertyName, char *pchValueBuffer, uint32 *punValueBufferSizeOut );
NameTypeDescription
resultHandleSteamInventoryResult_tThe result handle containing the item to get the properties of.
unItemIndexuint32
pchPropertyNameconst char *The property name to get the value for. If you pass in NULL then pchValueBuffer will contain a comma-separated list of all the available names.
pchValueBufferchar *Returns the value associated with pchPropertyName.
punValueBufferSizeOutuint32 *This should be set to the size of pchValueBuffer, and returns the number of bytes required to hold the value.

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.

Returns: 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 );
NameTypeDescription
resultHandleSteamInventoryResult_tThe inventory result handle to get the items for.
pOutItemsArraySteamItemDetails_t *The details are returned by copying them into this array.
punOutItemsArraySizeuint32 *This should be set to the length of pOutItemsArray. If pOutItemsArray is NULL then this will return the number of elements the array needs to hold.

Get the items associated with an inventory result handle.

Returns: bool
true if the call was successful, otherwise false.
Potential failure reasons include:
  • resultHandle is invalid or the inventory result handle is not ready.
  • pOutItemsArray is not large enough to hold the array.
  • The user has no items.

If the call is successful then punItemDefIDsArraySize will contain the number of item definitions available.

Example:
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 );
NameTypeDescription
resultHandleSteamInventoryResult_tThe inventory result handle to get the status for.

Find out the status of an asynchronous inventory result handle.

This is a polling equivalent to registering a callback function for SteamInventoryResultReady_t.

Returns: EResult
Whether 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 ) { // Do something here } } }

GetResultTimestamp

uint32 GetResultTimestamp( SteamInventoryResult_t resultHandle );
NameTypeDescription
resultHandleSteamInventoryResult_tThe inventory result handle to get the timestamp for.

Gets the server time at which the result was generated.

Returns: uint32
The 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 );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.

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

Returns: 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.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

Example:
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.

Returns: bool
Triggers a SteamInventoryDefinitionUpdate_t callback.
This call will always return true.

RequestEligiblePromoItemDefinitionsIDs

SteamAPICall_t RequestEligiblePromoItemDefinitionsIDs( CSteamID steamID );
NameTypeDescription
steamIDCSteamIDThe Steam ID of the user to request the eligible promo items for.

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.

Returns: 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.

Returns: SteamAPICall_t to be used with a SteamInventoryRequestPricesResult_t call result.
Returns k_uAPICallInvalid if there was an internal problem.

See Also: GetNumItemsWithPrices, GetItemsWithPrices, GetItemPrice

SendItemDropHeartbeat

void SendItemDropHeartbeat();
Deprecated.

SerializeResult

bool SerializeResult( SteamInventoryResult_t resultHandle, void *pOutBuffer, uint32 *punOutBufferSize );
NameTypeDescription
resultHandleSteamInventoryResult_tThe inventory result handle to serialize.
pOutBuffervoid *The buffer that the serialized result will be copied into.
punOutBufferSizeuint32 *This should be set to the size of pOutBuffer. If pOutBuffer is NULL then this will return the size required to hold the buffer.

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.

Returns: 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:
  • The function was not called by a regular user. This call is not supported on GameServers.
  • resultHandle is invalid or the inventory result handle is not ready.
  • The value passed into punOutBufferSize was smaller then expected and pOutBuffer was not NULL.

StartPurchase

SteamAPICall_t StartPurchase( const SteamItemDef_t *pArrayItemDefs, const uint32 *punArrayQuantity, uint32 unArrayLength );
NameTypeDescription
pArrayItemDefsSteamItemDef_t *The array of item definition ids that the user wants to purchase.
punArrayQuantityuint32 *The array of quantities of each item definition that the user wants to purchase.
unArrayLengthuint32This should be the length of pArrayItemDefs and punArrayQuantity arrays.

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.

Returns: SteamAPICall_t to be used with a SteamInventoryStartPurchaseResult_t call result.
Returns k_uAPICallInvalid if the input was invalid.
Testing while in Development: When testing StartPurchase before your app is released, all transactions made by members of the development / publishing team will be made through the Sandbox micro-transaction API internally. This means you will not be charged for the purchases made before the app is released if you are part of the Steamworks publisher.

TransferItemQuantity

bool TransferItemQuantity( SteamInventoryResult_t *pResultHandle, SteamItemInstanceID_t itemIdSource, uint32 unQuantity, SteamItemInstanceID_t itemIdDest );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.
itemIdSourceSteamItemInstanceID_tThe source item to transfer.
unQuantityuint32The quantity of the item that will be transfered from itemIdSource to itemIdDest.
itemIdDestSteamItemInstanceID_tThe destination item. You can pass k_SteamItemInstanceIDInvalid to split the source stack into a new item stack with the requested quantity.

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.

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.

NOTE: You must call DestroyResult on the provided inventory result when you are done with it.

See Also: ConsumeItem, ExchangeItems

Example:
void CInventory::CombineItems() { SteamInventoryResult_t transferResult; // split 2 items from an existing stack SteamItemInstanceID_t bigStack = GetItemIdFromInventory( ... ); SteamInventory()->TransferItemQuantity( &transferResult, bigStack, 1, k_SteamItemInstanceIDInvalid ); // move 2 from stack A to stack B SteamItemInstanceID_t originStack = GetItemIdFromInventory( ... ); SteamItemInstanceID_t destStack = GetItemIdFromInventory( ... ); SteamInventory()->TransferItemQuantity( &transferResult, originStack, 2, destStack ); }

TriggerItemDrop

bool TriggerItemDrop( SteamInventoryResult_t *pResultHandle, SteamItemDef_t dropListDefinition );
NameTypeDescription
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.
dropListDefinitionSteamItemDef_tThis must refer to an itemdefid of the type "playtimegenerator". See the inventory schema for more details.

Trigger an item drop if the user has played a long enough period of time.

This period can be customized in two places:
  • At the application level within Inventory Service: Playtime Item Grants. This will automatically apply to all "playtimegenerator" items that do not specify any overrides.
  • In an individual "playtimegenerator" item definition. The settings would take precedence over any application-level settings.

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.

NOTE: 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 ('[]').

Example:
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

See Also: SetProperty, RemoveProperty, SubmitUpdateProperties

SubmitUpdateProperties

bool SubmitUpdateProperties( SteamInventoryUpdateHandle_t handle, SteamInventoryResult_t * pResultHandle );
NameTypeDescription
handleSteamInventoryUpdateHandle_tThe update handle corresponding to the transaction request, returned from StartUpdateProperties.
pResultHandleSteamInventoryResult_t *Returns a new inventory result handle.

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.

Returns: bool

See Also: StartUpdateProperties, SetProperty, RemoveProperty

RemoveProperty

bool RemoveProperty( SteamInventoryUpdateHandle_t handle, SteamItemInstanceID_t nItemID, const char *pchPropertyName );
NameTypeDescription
handleSteamInventoryUpdateHandle_tThe update handle corresponding to the transaction request, returned from StartUpdateProperties.
nItemIDSteamItemInstanceID_tID of the item being modified.
pchPropertyNameconst char*The dynamic property being removed.

Removes a dynamic property for the given item.

Returns: bool

See Also: StartUpdateProperties, SetProperty, SubmitUpdateProperties

SetProperty

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 );
NameTypeDescription
handleSteamInventoryUpdateHandle_tThe update handle corresponding to the transaction request, returned from StartUpdateProperties.
nItemIDSteamItemInstanceID_tID of the item being modified.
pchPropertyNameconst char*The dynamic property being added or updated.
pchPropertyValueconst char*The string value being set.
bValueboolThe boolean value being set.
nValueint64The 64 bit integer value being set.
flValuefloatThe floating point number value being set.

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

Callbacks

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.

Associated Functions: LoadItemDefinitions

SteamInventoryEligiblePromoItemDefIDs_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.

NameTypeDescription
m_resultEResultk_EResultOK upon success, any other value indicates failure.
m_steamIDCSteamIDThe Steam ID of the user who these items are for.
m_numEligiblePromoItemDefsintThe number of eligible promo items available for this user. You should use this to create a SteamItemDef_t buffer to use with GetEligiblePromoItemDefinitionIDs to get the actual ItemDefs.
m_bCachedDataboolIndicates that the data was retrieved from the cache and not the server. This happens if the user is not logged on or can not otherwise connect to the Steam servers.

Associated Functions: RequestEligiblePromoItemDefinitionsIDs

SteamInventoryFullUpdate_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.

NameTypeDescription
m_handleSteamInventoryResult_tA new inventory result handle.

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.

NameTypeDescription
m_handleSteamInventoryResult_tThe inventory result which is now ready.
m_resultEResultThe new status of the handle. This is equivalent to calling GetResultStatus.

SteamInventoryStartPurchaseResult_t

Returned after StartPurchase is called.

NameTypeDescription
m_resultEResultk_EResultOK upon success, any other value indicates failure.
m_ulOrderIDuint64The auto-generated order id for the initiated purchase.
m_ulTransIDuint64The auto-generated transaction id for the initiated purchase.

SteamInventoryRequestPricesResult_t

Returned after RequestPrices is called.

NameTypeDescription
m_resultEResultk_EResultOK upon success, any other value indicates failure.
m_rgchCurrencycharThe string representing the user's local currency code.

Structs

These are structs which functions in ISteamInventory may return and/or interact with.

SteamItemDetails_t



NameTypeDescription
m_itemIdSteamItemInstanceID_tThe globally unique item instance handle.
m_iDefinitionSteamItemDef_tThe item definition number for this item.
m_unQuantityuint16The current quantity of the item.
m_unFlagsuint16This is a bitmasked collection of ESteamItemFlags.

Enums

These are enums which are defined for use with ISteamInventory.

ESteamItemFlags

These are bitflags that are set in SteamItemDetails_t.

NameValueDescription
k_ESteamItemNoTrade1 << 0This item is account-locked and cannot be traded or given away. This is an item status flag which is permanently attached to specific item instances.
k_ESteamItemRemoved1 << 8The item has been destroyed, traded away, expired, or otherwise invalidated. This is an action confirmation flag which is only set one time, as part of a result set.
k_ESteamItemConsumed1 << 9The item quantity has been decreased by 1 via ConsumeItem API. This is an action confirmation flag which is only set one time, as part of a result set.

Typedefs

These are typedefs which are defined for use with ISteamInventory.

NameBase typeDescription
SteamInventoryResult_tint32A handle to an asyncronous inventory result.
SteamItemDef_tint32Types of items in your game are identified by a 32-bit "item definition number".
Valid definition numbers are between 1 and 999999999; numbers less than or equal to zero are invalid, and numbers greater than or equal to one billion (1x10^9) are reserved for internal Steam use.
SteamItemInstanceID_tuint64Every individual instance of an item has a globally-unique instance ID.
This ID is unique to the combination of a player and specific item instance, and will not be transferred to another player or re-used for another item.
SteamInventoryUpdateHandle_tuint64Returned from the call StartUpdateProperties, which starts a transaction request to modify dynamic properties on items for the current user.

Constants

These are constants which are defined for use with ISteamInventory.

NameTypeValueDescription
k_SteamInventoryResultInvalidSteamInventoryResult_t-1An invalid Steam inventory result handle.
k_SteamItemInstanceIDInvalidSteamItemInstanceID_t(SteamItemInstanceID_t)~0An invalid item instance id. This is usually returned when an operation has failed. It's recommended that you initialize all new item instances with this value.
STEAMINVENTORY_INTERFACE_VERSIONconst char *"STEAMINVENTORY_INTERFACE_V002"