API de consulta e manipulação do Inventário Steam.

Consulte Serviço de Inventário Steam para mais informações.

Funções de membro

Funções de membro de ISteamInventory são chamadas por meio da função de acesso global SteamInventory().

AddPromoItem

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.
itemDef	SteamItemDef_t	A definição de item a conceder ao jogador.

Concede um item promocional ao usuário atual.

Pode ser chamada em segurança a partir do cliente, porque os itens que podem ser dados podem ser bloqueados por meio de políticas nas definições de itens. Um dos cenários mais comuns desta chamada é conceder um item a usuários que também possuem um jogo específico. Útil se o jogo tiver uma interface de usuário para exibição de um item promocional específico ao usuário; para conceder múltiplos itens promocionais, use as funções AddPromoItems ou GrantPromoItems.

Quaisquer itens que podem ser concedidos DEVEM ter um atributo "promo" na definição de item. O item promocional lista um conjunto de AppIDs que o usuário deve possuir para receber o item. Esta versão concederá todos os itens com um atributo "promo" especificado associado nas definições de itens configuradas. Isso permite adicionar mais itens promocionais sem ter que atualizar o cliente do jogo. Por exemplo, o atributo a seguir permitirá que o item seja concedido se o usuário possuir TF2 ou SpaceWar.

promo: owns:440;owns:480

Retorna: bool
Esta função sempre retorna true quando chamada por um usuário comum, e sempre retorna false quando chamada por SteamGameServer.

Se bem-sucedida, o resultado do inventário incluirá os itens concedidos, se houver. Se nenhum item foi concedido porque o usuário não atende a nenhuma promoção, ainda assim a chamada é considerada bem-sucedida.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

AVISO: Você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

Exemplo:

AddPromoItems

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.
pArrayItemDefs	const SteamItemDef_t *	A lista de itens a conceder ao usuário.
unArrayLength	uint32	A quantidade de itens na lista pArrayItemDefs.

Conceder um item promocional ao usuário atual.

Pode ser chamada em segurança a partir do cliente, porque os itens que podem ser dados podem ser bloqueados por meio de políticas nas definições de itens. Um dos cenários mais comuns desta chamada é conceder um item a usuários que também possuem um jogo específico. Se quiser conceder um único item promocional, use a função AddPromoItem. Se quiser conceder todos os itens promocionais possíveis, use a função GrantPromoItems.

Quaisquer itens que podem ser concedidos DEVEM ter um atributo "promo" na definição de item. O item promocional lista um conjunto de AppIDs que o usuário deve possuir para receber o item. Esta versão concederá todos os itens com um atributo "promo" especificado associado nas definições de itens configuradas. Isso permite adicionar mais itens promocionais sem ter que atualizar o cliente do jogo. Por exemplo, o atributo a seguir permitirá que o item seja concedido se o usuário possuir TF2 ou SpaceWar.

promo: owns:440;owns:480

Retorna: bool
Esta função sempre retorna true quando chamada por um usuário comum, e sempre retorna false quando chamada por SteamGameServer.

Se bem-sucedida, o resultado do inventário incluirá os itens concedidos, se houver. Se nenhum item foi concedido porque o usuário não atende a nenhuma promoção, ainda assim a chamada é considerada bem-sucedida.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

AVISO: Você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

Exemplo:

CheckResultSteamID

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado do inventário cujo ID Steam verificar.
steamIDExpected	CSteamID	O ID Steam a verificar.

Verifica se o handle do resultado do inventário pertence ao ID Steam especificado.

É importante usá-la em conjunto com a função DeserializeResult para confirmar que um jogador remoto não está fingindo ter o inventário de outro usuário.

Retorna: bool
true se o resultado pertence ao ID Steam informado; false caso contrário.

ConsumeItem

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.
itemConsume	SteamItemInstanceID_t	O ID da instância do item a consumir.
unQuantity	uint32	A quantidade de exemplares da instância a consumir.

Consome itens do inventário de um usuário. Se a quantidade do item informado chegar a zero, este será removido permanentemente do inventário.

Não há como recuperar um item removido. Esta função deve ser usada com extrema cautela — caso o seu jogo implemente um recurso de remoção/exclusão de item, é altamente recomendado que haja uma interface de usuário explicativa e bem diagramada para o processo de confirmação.

Retorna: bool
Esta função sempre retorna true quando chamada por um usuário comum, e sempre retorna false quando chamada por SteamGameServer.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

AVISO: você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

Consulte também: ExchangeItems, TransferItemQuantity

Exemplo:

DeserializeResult

Nome	Tipo	Descrição
pOutResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.
pBuffer	const void *	O buffer a desserializar.
unBufferSize	uint32	O tamanho do buffer alocado para pBuffer.
bRESERVED_MUST_BE_FALSE	bool	Deve ser false!

Desserializa um conjunto de resultados e verifica os bytes de assinatura.

Esta chamada tem um possível modo de falha leve, onde o estado do handle é definido como k_EResultExpired. GetResultItems ainda será bem-sucedida neste modo. O resultado "expired" pode indicar que os dados estão desatualizados — não devido à validade por tempo (uma hora), mas também porque um dos itens no conjunto de resultado pode ter sido trocado ou consumido desde a geração do conjunto de resultados. É possível comparar o horário retornado pela função GetResultTimestamp com o horário retornado pela função ISteamUtils::GetServerRealTime para determinar a idade dos dados. É possível ignorar o código de resultado "expired" e continuar normalmente ou enviar uma requisição ao jogador com dados desatualizados para que envie um conjunto de resultados atualizado.

Após usá-la, passe o handle do resultado para CheckResultSteamID para confirmar que um jogador remoto não está fingindo ter o inventário de outro usuário.

AVISO: o parâmetro bRESERVED_MUST_BE_FALSE está reservado para uso futuro e nunca deve receber o valor true.

Retorna: bool
Sempre retorna true e então envia códigos de erro por meio da função GetResultStatus.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

AVISO: você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

DestroyResult

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado do inventário a destruir.

Destrói um handle de resultado e libera a memória associada.

ExchangeItems

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.
pArrayGenerate	const SteamItemDef_t *	A lista de itens que serão criados por esta chamada. Atualmente só pode conter 1 item!
punArrayGenerateQuantity	const uint32 *	A quantidade a gerar de cada item em pArrayGenerate. Atualmente só pode conter o valor 1!
unArrayGenerateLength	uint32	A quantidade de itens em pArrayGenerate e punArrayGenerateQuantity. Atualmente só pode conter o valor 1!
pArrayDestroy	const SteamItemInstanceID_t *	A lista de itens que serão destruídos por esta chamada.
punArrayDestroyQuantity	const uint32 *	A quantidade a destruir de cada item em pArrayDestroy.
unArrayDestroyLength	uint32	A quantidade de itens em pArrayDestroy e punArrayDestroyQuantity.

Concede um item em uma permuta por um conjunto de outros itens.

Pode ser usada para implementar receitas de fabricação ou transmutações, ou itens que são abertos para revelar outros itens (ex.: baú de tesouro).

O chamador desta API passa o item desejado juntamente de uma lista de itens e quantidades pelos quais permutar. A API aceita uma lista de itens para gerar, mas atualmente o tamanho dessa lista deve ser 1 e a quantidade do item novo deve ser 1.

Quaisquer itens que possam ser concedidos DEVEM ter um atributo "exchange" na definição de item. Esse atributo especifica um conjunto de receitas que são permutas válidas para este item. Receitas de permuta são avaliadas atomicamente pelo serviço de inventário; se os componentes informados não corresponderem à receita ou não tenham a quantidade suficiente, a permuta falhará.

Por exemplo:

Permitirá que o item seja permutado por 1 instância de 101 e 1 instância de 102, 5 instâncias de 103, ou 3 instâncias de 104 e 3 instâncias de 105. Consulte a documentação sobre Inventário Steam: Esquema para mais detalhes.

Retorna: bool
Esta função retorna true se bem-sucedida. Retorna false quando chamada por SteamGameServer ou quando unArrayGenerateLength ou punArrayGenerateQuantity não forem iguais a 1.

Permutas que não correspondam a uma receita ou não forneçam as quantidades exigidas falharão.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

AVISO: você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

Consulte também: ConsumeItem, TransferItemQuantity

Exemplo:

GenerateItems

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.
pArrayItemDefs	const SteamItemDef_t *	A lista de itens a conceder ao usuário.
punArrayQuantity	const uint32 *	A quantidade a conceder de cada item em pArrayItemDefs. Opcional; informar NULL significará 1 de cada item.
unArrayLength	uint32	A quantidade de itens na lista pArrayItemDefs.

Concede itens específicos ao usuário atual. Uso exclusivo para desenvolvimento.

Esta API é exclusiva para prototipagem e só pode ser usada por contas Steam que fazem parte do grupo da distribuidora do jogo.

É possível passar uma lista de itens, identificados pelo SteamItemDef_t, e opcionalmente uma segunda lista das respectivas quantidades de cada item. Essas listas DEVEM ter a mesma quantidade de elementos!

Retorna: bool
Esta função sempre retorna true quando chamada por um usuário comum, e sempre retorna false quando chamada por SteamGameServer.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

AVISO: você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

Exemplo:

GetAllItems

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.

Inicia a recuperação de itens do inventário do usuário atual.

AVISO: chamadas a esta função estão sujeitas a limites de frequência e podem retornar resultados em cache se esse limite for ultrapassado. É aconselhável chamá-la apenas quando estiver prestes a exibir o inventário completo do usuário ou se espera que o inventário tenha alterações.

Retorna: bool
Esta função sempre retorna true quando chamada por um usuário comum, e sempre retorna false quando chamada por SteamGameServer.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

AVISO: você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

Exemplo:

GetEligiblePromoItemDefinitionIDs

Nome	Tipo	Descrição
steamID	CSteamID	O ID Steam do usuário associado. Deve ser o mesmo valor de SteamInventoryEligiblePromoItemDefIDs_t.m_steamID.
pItemDefIDs	SteamItemDef_t *	Retorna os IDs de definição de item copiando-os para este vetor.
punItemDefIDsArraySize	uint32 *	O tamanho do buffer alocado para pItemDefIDs, que deve ser igual a SteamInventoryEligiblePromoItemDefIDs_t.m_numEligiblePromoItemDefs.

Recupera a lista de IDs de definição de item que podem ser concedidos a um usuário.

Chame esta função ao tratar o resultado de chamada SteamInventoryEligiblePromoItemDefIDs_t para recuperar os IDs de definição de item.

Retorna: bool


Consulte também: AddPromoItem, AddPromoItems

GetItemDefinitionIDs

Nome	Tipo	Descrição
pItemDefIDs	SteamItemDef_t *	Retorna os IDs de definição de item copiando-os para este vetor.
punItemDefIDsArraySize	uint32 *	O tamanho do buffer alocado para pItemDefIDs. Se pItemDefIDs for NULL, então retornará a quantidade de elementos necessários no vetor.

Retorna o conjunto de todos os IDs de definição de item existentes no painel de administração de aplicativo no site do Steamworks.

Essas definições de itens não necessariamente serão números inteiros contínuos.

Deve ser chamada em resposta a um retorno de chamada SteamInventoryDefinitionUpdate_t. Não há motivo para chamar esta função se os IDs numéricos de definição são integrados ao jogo (ex.: mascara roxa = 20, arma azul = 55) e não permite a adição de novos tipos de item sem uma atualização do cliente.

Retorna: bool
Esta chamada retorna true se bem-sucedida. Só retorna false se as definições de itens não foram carregadas do servidor ou não houver definições de itens para o aplicativo atual.

Se a chamada for bem-sucedida, então punItemDefIDsArraySize conterá a quantidade de definições de itens disponíveis.

GetItemDefinitionProperty

Nome	Tipo	Descrição
iDefinition	SteamItemDef_t	A definição de item cujas propriedades recuperar.
pchPropertyName	const char *	O nome da propriedade cujo valor recuperar. Se NULL, então pchValueBuffer conterá uma lista de todos os nomes disponíveis, separados por vírgula.
pchValueBuffer	char *	Retorna o valor associado a pchPropertyName.
punValueBufferSizeOut	uint32 *	O tamanho do buffer alocado para pchValueBuffer, e retorna a quantidade de bytes necessários para armazenar o valor.

Recupera uma string de propriedade da definição de item especificada.
Recupera o valor de uma propriedade de uma definição de item específica.

Observe que algumas propriedades (como "name") podem ser localizadas e dependerão as configurações de idioma atuais do Steam (consulte ISteamApps::GetCurrentGameLanguage). Nomes de propriedade conterão caracteres ASCII alfanuméricos e o caractere de sublinhado (underscore).

Passe NULL no parâmetro pchPropertyName para recuperar uma lista dos nomes de todas as propriedades disponíveis, separadas por vírgula. Neste modo, punValueBufferSizeOut conterá o tamanho sugerido para o buffer. Caso contrário, conterá a quantidade de bytes copiados para pchValueBuffer.

Retorna: bool
Retorna true se bem-sucedida. false se as definições de itens não foram carregadas do servidor, não houver definições de itens para o aplicativo atual ou não foi encontrada propriedade com o nome informado na definição de itens.

O valor associado é retornado por meio do pchValueBuffer, e a quantidade total de bytes exigidos para armazenar o valor está disponível em punValueBufferSizeOut. É aconselhável chamar esta função duas vezes, a primeira com pchValueBuffer NULL e punValueBufferSizeOut 0 para recuperar o tamanho necessário para o buffer da chamada subsequente.

Exemplo de saída:
pchPropertyName NULL:
appid,itemdefid,Timestamp etc...
pchPropertyName com o valor "name":
SW_DECORATION_HAT

AVISO: Call LoadItemDefinitions first, to ensure that items are ready to be used before calling GetItemDefinitionProperty.

GetItemsByID

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.
pInstanceIDs	const SteamItemInstanceID_t *	A lista de IDs de instância de item cujos estados atualizar.
unCountInstanceIDs	uint32	A quantidade de itens em pInstanceIDs.

Recupera o estado de um subconjunto do inventário do usuário atual.

O subconjunto é especificado por uma lista de IDs de instância de item.

Os resultados desta chamada podem ser serializados usando SerializeResult e passados a outros jogadores para "provar" que o usuário atual possui itens específicos sem expor todo o inventário do mesmo. Por exemplo, é possível chamar esta função com os IDs dos itens equipados pelo usuário, serializá-los em um buffer e então transmitir esse buffer aos outros jogadores ao conectar-se a uma partida.

Retorna: bool
Esta função sempre retorna true quando chamada por um usuário comum, e sempre retorna false quando chamada por SteamGameServer.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

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

GetItemPrice

Nome	Tipo	Descrição
iDefinition	SteamItemDef_t	O ID da definição de item cujo preço recuperar.
pPrice	uint64*	O ponteiro de preço a preencher. Preços são retornados na moeda local do usuário.

Após uma chamada bem-sucedida a RequestPrices, chame esta função para recuperar os preços de uma definição de item específica.

Retorna: bool
true se bem-sucedida, indicando que pPrice foi preenchido com o preço da definição de item informada.
false se os parâmetros forem inválidos ou se não houver preço associado à definição de item informada.

Consulte também: RequestPrices

GetItemsWithPrices

Nome	Tipo	Descrição
pArrayItemDefs	SteamItemDef_t *	O vetor de IDs de definição de itens a preencher.
pPrices	uint64*	O vetor de preços para cada definição de item no vetor pArrayItemDefs. Preços são retornados na moeda local do usuário.
unArrayLength	uint32	Deve ser o tamanho dos vetores pArrayItemDefs e pPrices, que deve ser o mesmo valor retornado por GetNumItemsWithPrices .

Após uma chamada bem-sucedida a RequestPrices, chame esta função para recuperar os preços de todas as definições de item aplicáveis. Use o resultado da chamada à API GetNumItemsWithPrices como o tamanho dos vetores passados.

Retorna: bool
true se bem-sucedida, indicando que os vetores pArrayItemDefs e pPrices foram preenchidos com os IDs de definição de item e preços dos itens à venda.
false se os parâmetros forem inválidos.

Consulte também: RequestPrices, GetItemPrice

GetNumItemsWithPrices

Após uma chamada bem-sucedida a RequestPrices, retornará a quantidade de definições de item com preços válidos.

Retorna: uint32

Consulte também: RequestPrices, GetItemsWithPrices

GetResultItemProperty

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado que contém o item cujas propriedades recuperar.
unItemIndex	uint32
pchPropertyName	const char *	O nome da propriedade cujo valor recuperar. Se NULL, então pchValueBuffer conterá uma lista de todos os nomes disponíveis, separados por vírgula.
pchValueBuffer	char *	Retorna o valor associado a pchPropertyName.
punValueBufferSizeOut	uint32 *	O tamanho do buffer alocado para pchValueBuffer, e retorna a quantidade de bytes necessários para armazenar o valor.

Recupera as propriedades dinâmicas de um item a partir de um conjunto de resultados de inventário.

Nomes de propriedade conterão caracteres ASCII alfanuméricos e o caractere de sublinhado (underscore).

Se os resultados não couberem no buffer informado, o resultado poderá ser copiado parcialmente.

Retorna: bool
true se bem-sucedida. false se o handle do resultado do inventário for inválido ou o índice informado não contiver um item.

GetResultItems

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado do inventário cujos itens recuperar.
pOutItemsArray	SteamItemDetails_t *	Os detalhes são retornados copiando-os para este vetor.
punOutItemsArraySize	uint32 *	O tamanho do buffer alocado para pOutItemsArray. Se pOutItemsArray for NULL, então retornará a quantidade de elementos necessários no vetor.

Recupera os itens associados ao handle do resultado do inventário.

Retorna: bool
true se bem-sucedida; false caso contrário.
Possíveis motivos de falha incluem:

• resultHandle inválido ou não pronto.
  
• pOutItemsArray pequeno demais para armazenar o vetor.
  
• Usuário sem itens.

Se a chamada for bem-sucedida, então punItemDefIDsArraySize conterá a quantidade de definições de itens disponíveis.

Exemplo:

GetResultStatus

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado do inventário cujo estado recuperar.

Descobre o estado de um handle do resultado do inventário assíncrono.

Seria o equivalente de polling a registrar uma função ao retorno de chamada SteamInventoryResultReady_t.

Retorna: EResult
Se a chamada foi bem-sucedida ou não.

Valores possíveis:

• k_EResultPending — Em andamento.
  
• k_EResultOK — Pronto, requisição concluída com sucesso e o resultado está pronto.
  
• k_EResultExpired — Pronto, resultado pronto, talvez desatualizado (consultar DeserializeResult).
  
• k_EResultInvalidParam — ERRO: parâmetros da chamada à API inválidos.
  
• k_EResultServiceUnavailable — ERRO: serviço fora do ar temporariamente, tente novamente mais tarde.
  
• k_EResultLimitExceeded — ERRO: a operação ultrapassaria o limite de acessos por inventário de usuário.
  
• k_EResultFail — ERRO: erro genérico.

Exemplo:

GetResultTimestamp

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado do inventário cujo horário recuperar.

Recupera o horário do servidor no qual o resultado foi gerado.

Retorna: uint32
O horário é especificado no formato de Era Unix (segundos a partir de 1º de janeiro de 1970).

É possível comparar este horário com o retornado pela função ISteamUtils::GetServerRealTime para determinar a idade do resultado.

GrantPromoItems

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.

Concede todos os possíveis itens promocionais únicos ao usuário atual.

Pode ser chamada em segurança a partir do cliente, porque os itens que podem ser dados podem ser bloqueados por meio de políticas nas definições de itens. Um dos cenários mais comuns desta chamada é conceder um item a usuários que também possuem um jogo específico. Se desejar conceder itens promocionais específicos e não todos, consulte: AddPromoItem e AddPromoItems.

Quaisquer itens que podem ser concedidos DEVEM ter um atributo "promo" na definição de item. O item promocional lista um conjunto de AppIDs que o usuário deve possuir para receber o item. Esta versão concederá todos os itens com um atributo "promo" especificado associado nas definições de itens configuradas. Isso permite adicionar mais itens promocionais sem ter que atualizar o cliente do jogo. Por exemplo, o atributo a seguir permitirá que o item seja concedido se o usuário possuir TF2 ou SpaceWar.

promo: owns:440;owns:480

Retorna: bool
Esta função sempre retorna true quando chamada por um usuário comum, e sempre retorna false quando chamada por SteamGameServer.

Se bem-sucedida, o resultado do inventário incluirá os itens concedidos, se houver. Se nenhum item foi concedido porque o usuário não atende a nenhuma promoção, ainda assim a chamada é considerada bem-sucedida.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

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

Exemplo:

LoadItemDefinitions

Dispara um carregamento e atualização assíncronos das definições de itens.

Definições de itens são um mapeamento de "IDs de definição" (inteiros entre 1 e 999999999) a um conjunto de strings que definem propriedades. Algumas dessas propriedades são obrigatórias para a exibição de itens no site da Comunidade Steam. Outras propriedades podem ser definidas por aplicativos. Não há motivo para chamar esta função se os IDs numéricos de definição são integrados ao jogo (ex.: mascara roxa = 20, arma azul = 55) e não permite a adição de novos tipos de item sem uma atualização do cliente.

Retorna: bool
Dispara um retorno de chamada SteamInventoryDefinitionUpdate_t.
Sempre retorna true.

RequestEligiblePromoItemDefinitionsIDs

Nome	Tipo	Descrição
steamID	CSteamID	O ID Steam do usuário que se deseja verificar itens promocionais disponíveis para concessão.

Recupera a lista de itens promocionais "disponíveis" para concessão manual ao usuário.

Esses são itens promocionais de tipo "manual" que não serão concedidos automaticamente. Um exemplo de uso é um item que é disponibilizado toda semana.

Após chamar esta função, é necessário chamar a função GetEligiblePromoItemDefinitionIDs para recuperar os IDs de definição de item.

Retorna: SteamAPICall_t, a ser usado com o resultado de chamada SteamInventoryEligiblePromoItemDefIDs_t.
Retorna k_uAPICallInvalid se steamID não for uma conta individual válida.

RequestPrices

Recupera os preços de todas as definições de item à venda na moeda local do usuário. Um resultado de chamada SteamInventoryRequestPricesResult_t será retornado com o código da moeda local do usuário. Depois, chame as funções GetNumItemsWithPrices e GetItemsWithPrices para recuperar os preços de todas as definições de item conhecidas, ou GetItemPrice para uma definição de item específica.

Retorna: SteamAPICall_t, a ser usado com o resultado de chamada SteamInventoryRequestPricesResult_t.
Retorna k_uAPICallInvalid se houve um problema interno.

Consulte também: GetNumItemsWithPrices, GetItemsWithPrices, GetItemPrice

SendItemDropHeartbeat

Em desuso.

SerializeResult

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado do inventário a serializar.
pOutBuffer	void *	O buffer para o qual o resultado serializado será copiado.
punOutBufferSize	uint32 *	O tamanho do buffer alocado para pOutBuffer. Se pOutBuffer for NULL, então retornará o tamanho necessário para armazenar o resultado.

Conjuntos de resultados serializados contêm uma assinatura curta, que não pode ser forjada ou replicada em sessões diferentes.

Um conjunto de resultados pode ser serializado no cliente local, transmitido a outros jogadores pelo sistema de rede do jogo e desserializado pelos jogadores remotos. Esta é uma forma segura de impedir que hackers mintam sobre a posse de itens raros ou de alto valor. Serializa um conjunto de resultados com bytes de assinatura e o copia em um buffer de saída. O tamanho de um resultado serializado depende da quantidade de itens a serem serializados. Ao transmitir itens de forma segura a outros jogadores, é recomendado primeiro usar a função GetItemsByID para criar um conjunto de resultados mínimo.

Resultados conterão um horário, que será considerado "expirado" depois de uma hora. Consulte DeserializeResult para tratamento de dados expirados.

Se pOutBuffer for NULL, então punOutBufferSize será o tamanho necessário para armazenar a serialização. É aconselhável chamar esta função duas vezes, a primeira com pOutBuffer NULL para recuperar o tamanho necessário para o buffer da chamada subsequente.

Retorna: bool
true se bem-sucedida, indicando que punOutBufferSize foi preenchido com o tamanho do buffer e, se pOutBuffer apontar para um buffer de tamanho suficiente, este também estará preenchido.
false sob as seguintes condições:

• A função não foi chamada por um usuário comum. Esta chamada não é permitida em GameServers.
  
• resultHandle inválido ou não pronto.
  
• O valor passado como argumento punOutBufferSize era menor que o esperado e pOutBuffer não era NULL.

StartPurchase

Nome	Tipo	Descrição
pArrayItemDefs	SteamItemDef_t *	O vetor de IDs de definições de item que o usuário deseja comprar.
punArrayQuantity	uint32 *	O vetor com as quantidades de cada definição de item que o usuário deseja comprar.
unArrayLength	uint32	A quantidade de itens em pArrayItemDefs e punArrayQuantity.

Inicia o processo de compra para o usuário, dado um "carrinho de compras" de definições de item que o usuário deseja comprar. The user will be prompted in the Steam Overlay to complete the purchase in their local currency, funding their Steam Wallet if necessary, etc.

Se o processo de compra foi iniciado com sucesso, então m_ulOrderID e m_ulTransID
terão valores válidos no resultado de chamada SteamInventoryStartPurchaseResult_t.

Se o usuário autorizar a transação e concluir a compra, então o resultado de chamada SteamInventoryResultReady_t será ativado e será possível recuperar os novos itens adquiridos. AVISO: você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

Retorna: SteamAPICall_t, a ser usado com o resultado de chamada SteamInventoryStartPurchaseResult_t.
Retorna k_uAPICallInvalid se a entrada for inválida.

TransferItemQuantity

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.
itemIdSource	SteamItemInstanceID_t	O item original do qual a quantidade será transferida.
unQuantity	uint32	A quantidade do item que será transferida de itemIdSource a itemIdDest.
itemIdDest	SteamItemInstanceID_t	O item de destino. É possível passar o valor k_SteamItemInstanceIDInvalid para dividir o agrupamento-fonte em um novo agrupamento de itens com a quantidade informada.

Transfere itens entre agrupamentos do inventário de um usuário.

Pode ser usada para agrupar, dividir e mover itens. Os itens original e de destino devem ter o mesmo ID de definição de item. Para mover itens para um agrupamento existente, especifique o item original, a quantidade a mover e o ID do item de destino. Para dividir um um agrupamento existente, passe k_SteamItemInstanceIDInvalid como o argumento itemIdDest. Um novo agrupamento de itens será gerado com a quantidade informada.

AVISO: restrições de troca e Mercado são copiados juntamente com os itens transferidos. A restrição de troca e Mercado do agrupamento será igual à restrição mais distante dentre os itens que o compõem.

Retorna: bool
Esta função sempre retorna true quando chamada por um usuário comum, e sempre retorna false quando chamada por SteamGameServer.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

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

Consulte também: ConsumeItem, ExchangeItems

Exemplo:

TriggerItemDrop

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.
dropListDefinition	SteamItemDef_t	Referência a um ID de definição de item do tipo "playtimegenerator". Consulte a documentação sobre esquema do inventário para mais detalhes.

Dispara uma distribuição de item se o usuário tiver jogado por tempo suficiente.

O período pode ser personalizado em dois locais:

• Para todo o aplicativo, na seção de serviço de inventário > Distribuição de itens por tempo. Esse valor será aplicado a todos os itens do tipo "playtimegenerator" que não especificam qualquer valor internamente.
  
• Na definição de um item do tipo "playtimegenerator&quot. O valor assim definido terá precedência sobre qualquer valor definido para todo o aplicativo.

Apenas definições de itens marcados como "playtime item generators" (geradores de item por tempo) podem ser geradas.

Tipicamente essa função é chamada no fim de uma partida, nível, rodada ou momento significativo do jogo no qual pode ocorrer uma distribuição de item. O gerador de item por tempo é configurado em minutos, então chamar esta função mais de uma vez por minuto não é útil e será bloqueada pelo cliente Steam. Os servidores Steam farão o cálculo de tempo de jogo para impedir distribuições frequentes demais. Os servidores também cuidarão de adicionar o item ao inventário do jogador.

Retorna: bool
Esta função sempre retorna true quando chamada por um usuário comum, e sempre retorna false quando chamada por SteamGameServer.

Retorna o handle do novo resultado por meio do argumento pResultHandle.

AVISO: Você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

O resultado do inventário retornado por esta função será o novo item distribuído ou, se não houve distribuição, um resultado vazio ("[]").

Exemplo:

StartUpdateProperties

Inicia uma requisição de transação para atualizar as propriedades dinâmicas de itens do usuário atual. Esta chamada tem limitação de frequência por usuário, então modificações de propriedades devem ser agrupadas sempre que possível (ex.: no fim de um mapa ou sessão). Após chamar as funções SetProperty ou RemoveProperty nos itens que deseja alterar, chame a função SubmitUpdateProperties para enviar a requisição aos servidores Steam. Um retorno de chamada SteamInventoryResultReady_t será disparado com os resultados da operação.

Exemplo:

AVISO: você deve chamar a função DestroyResult no resultado do inventário fornecido por SubmitUpdateProperties quando terminar de usá-lo.

Retorna: SteamInventoryUpdateHandle_t

Consulte também: SetProperty, RemoveProperty, SubmitUpdateProperties

SubmitUpdateProperties

Nome	Tipo	Descrição
handle	SteamInventoryUpdateHandle_t	O handle de atualização associado à solicitação de transação retornado pela função StartUpdateProperties.
pResultHandle	SteamInventoryResult_t *	Retorna um novo handle do resultado do inventário.

Envia a requisição de transação para alterar as propriedades dinâmicas de itens do usuário atual. See StartUpdateProperties.

AVISO: você deve chamar a função DestroyResult no resultado do inventário fornecido quando terminar de usá-lo.

Retorna: bool

Consulte também: StartUpdateProperties, SetProperty, RemoveProperty

RemoveProperty

Nome	Tipo	Descrição
handle	SteamInventoryUpdateHandle_t	O handle de atualização associado à requisição de transação retornado pela função StartUpdateProperties.
nItemID	SteamItemInstanceID_t	ID do item a ser alterado.
pchPropertyName	const char*	O nome da propriedade a ser removida.

Remove uma propriedade dinâmica do item informado.

Retorna: bool

Consulte também: StartUpdateProperties, SetProperty, SubmitUpdateProperties

SetProperty

Nome	Tipo	Descrição
handle	SteamInventoryUpdateHandle_t	O handle de atualização associado à solicitação de transação retornado pela função StartUpdateProperties.
nItemID	SteamItemInstanceID_t	ID do item a ser alterado.
pchPropertyName	const char*	O nome da propriedade a ser adicionada ou atualizada.
pchPropertyValue	const char*	A string a ser definida.
bValue	bool	O valor booleano a ser definido.
nValue	int64	O inteiro de 64 bits a ser definido.
flValue	float	O número de ponto flutuante a ser definido.

Define uma propriedade dinâmica do item informado. Supported value types are strings, boolean, 64 bit integers, and 32 bit floats.

Retorna: bool

Consulte também: StartUpdateProperties, RemoveProperty, SubmitUpdateProperties

Retornos de chamada

Estes são os retornos de chamada (callbacks) que podem ser disparados ao chamar SteamAPI_RunCallbacks. Muitos podem ser disparados diretamente em resposta às funções de membro de ISteamInventory.

SteamInventoryDefinitionUpdate_t

Disparado sempre que as definições de itens são atualizadas, o que pode ser em resposta a LoadItemDefinitions ou sempre que novas definições de itens estiverem disponíveis (como pela adição dinâmica de novos tipos de itens com os jogadores em jogo).

Este retorno de chamada não possui campos.

Funções associadas: LoadItemDefinitions

SteamInventoryEligiblePromoItemDefIDs_t

Disparado ao requisitar a lista de itens promocionais "disponíveis" para concessão manual ao usuário. Esses são itens promocionais de tipo "manual" que não serão concedidos automaticamente. Um exemplo de uso é um item que é disponibilizado toda semana.

Nome	Tipo	Descrição
m_result	EResult	k_EResultOK se bem-sucedida. Qualquer outro valor indica falha.
m_steamID	CSteamID	O ID Steam do usuário associado.
m_numEligiblePromoItemDefs	int	A quantidade de itens promocionais disponíveis para o usuário. Use este valor para criar um buffer SteamItemDef_t para recuperar as definições de itens por meio da função GetEligiblePromoItemDefinitionIDs.
m_bCachedData	bool	Indica que os dados foram recuperados do cache e não do servidor. Isso ocorre quando o usuário não tiver iniciado a sessão ou está impossibilitado de se conectar aos servidores Steam.

Funções associadas: 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.

Nome	Tipo	Descrição
m_handle	SteamInventoryResult_t	O handle do novo resultado do inventário.

SteamInventoryResultReady_t

Disparado sempre que um resultado do inventário passar do estado k_EResultPending a qualquer outro estado de conclusão; consulte GetResultStatus para ver a lista completa de estados. Sempre haverá exatamente um retorno de chamada por handle.

Nome	Tipo	Descrição
m_handle	SteamInventoryResult_t	O resultado do inventário que está pronto.
m_result	EResult	O novo estado do handle. Equivalente a uma chamada à função GetResultStatus.

SteamInventoryStartPurchaseResult_t

Disparado ao chamar a função StartPurchase.

Nome	Tipo	Descrição
m_result	EResult	k_EResultOK se bem-sucedida. Qualquer outro valor indica falha.
m_ulOrderID	uint64	O ID (gerado automaticamente) do pedido associado à compra iniciada.
m_ulTransID	uint64	O ID (gerado automaticamente) da transação associada à compra iniciada.

SteamInventoryRequestPricesResult_t

Disparado ao chamar a função RequestPrices.

Nome	Tipo	Descrição
m_result	EResult	k_EResultOK se bem-sucedida. Qualquer outro valor indica falha.
m_rgchCurrency	char	A string que representa o código da moeda local do usuário.

Structs

Estas são as structs com as quais funções da interface ISteamInventory podem retornar e/ou interagir.

SteamItemDetails_t

Nome	Tipo	Descrição
m_itemId	SteamItemInstanceID_t	O handle globalmente único da instância do item.
m_iDefinition	SteamItemDef_t	O ID da definição de item para esta instância.
m_unQuantity	uint16	A quantidade atual do item.
m_unFlags	uint16	Uma máscara de bits que representa valores da enumeração ESteamItemFlags.

Enumerações

Estas são as enumerações definidas para uso com ISteamInventory.

ESteamItemFlags

Bit-indicadores definidos em SteamItemDetails_t.

Nome	Valor	Descrição
k_ESteamItemNoTrade	1 << 0	Item atrelado à conta, não podendo ser trocado ou presenteado. Esse indicador é anexado permanentemente a instâncias de item específicas.
k_ESteamItemRemoved	1 << 8	Item destruído, trocado, expirado ou de outra forma invalidado. Esse é um indicador de confirmação de ação que é definido apenas uma vez, como parte de um conjunto de resultados.
k_ESteamItemConsumed	1 << 9	A quantidade do item foi reduzida em um por meio da API ConsumeItem. Esse é um indicador de confirmação de ação que é definido apenas uma vez, como parte de um conjunto de resultados.

Tipos definidos

Estes são os tipos definidos por typedefs para uso com ISteamInventory.

Nome	Tipo base	Descrição
SteamInventoryResult_t	int32	Um handle para um resultado do inventário assíncrono.
SteamItemDef_t	int32	Tipos de itens do jogo, identificados por um "ID de definição de item" de 32 bits. IDs de definição de item vão de 1 a 999999999; números iguais ou menores que zero são inválidos e números maiores ou iguais a um bilhão (1x10^9) são reservados para uso interno do Steam.
SteamItemInstanceID_t	uint64	Cada instância individual de um item possui um ID de instância globalmente único. Esse ID é único para a combinação de jogador e instância específica de item, não sendo transferido para outro jogador ou reciclado para uso em outro item.
SteamInventoryUpdateHandle_t	uint64	Retornado pela função StartUpdateProperties, que inicia uma requisição de transação para alterar propriedades dinâmicas em itens do usuário atual.

Constantes

Estas são as constantes definidas para uso com ISteamInventory.

Nome	Tipo	Valor	Descrição
k_SteamInventoryResultInvalid	SteamInventoryResult_t	-1	Um handle do resultado do inventário inválido.
k_SteamItemInstanceIDInvalid	SteamItemInstanceID_t	(SteamItemInstanceID_t)~0	Um ID de instância de item inválido. Costuma ser retornado quando uma operação falha. É aconselhável inicializar todas as instâncias de item com este valor.
STEAMINVENTORY_INTERFACE_VERSION	const char *	"STEAMINVENTORY_INTERFACE_V002"