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 através da função de acesso global SteamInventory().

AddPromoItem

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

Concede um único item promocional específico ao utilizador atual.

Esta função pode ser chamada em segurança a partir da aplicação Steam, porque os itens que pode conceder podem ser bloqueados mediante políticas nas ItemDefs. Um dos principais cenários desta chamada é conceder um item a utilizadores que também têm um jogo específico. É particularmente útil se o seu jogo tiver uma interface dedicada à apresentação de um item promocional específico ao utilizador. Caso contrário, use as funções AddPromoItems ou GrantPromoItems se pretender conceder vários itens promocionais.

Qualquer item que possa ser concedido TEM de conter o atributo "promo" na respetiva ItemDef. O item promocional lista os AppIDs que o utilizador deve possuir para que possa receber o item. Esta versão irá conceder todos os itens com um atributo "promo" especificado nas definições de itens configuradas. Desta forma, é possível adicionar mais itens promocionais sem ser necessário atualizar a aplicação do jogo. Por exemplo, o seguinte atributo irá permitir que o item seja concedido se o utilizador tiver o jogo TF2 ou Spacewar.

promo: owns:440;owns:480

Retorna: bool
Esta função retorna sempre true quando é chamada por um utilizador comum e retorna sempre false quando é chamada a partir de SteamGameServer.

Em caso de sucesso, o resultado do inventário irá incluir os itens que foram concedidos, se algum existe. Se nenhum item foi concedido porque o utilizador não é elegível para nenhuma promoção, a chamada é mesmo assim considerada um sucesso.

Retorna um handle de resultado novo via pResultHandle.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

Exemplo:

AddPromoItems

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um handle de resultado novo do inventário.
pArrayItemDefs	const SteamItemDef_t *	A lista de itens a conceder ao utilizador.
unArrayLength	uint32	O número de itens em pArrayItemDefs.

Concede um único item promocional específico ao utilizador atual.

Esta função pode ser chamada em segurança a partir da aplicação Steam, porque os itens que pode conceder podem ser bloqueados mediante políticas nas ItemDefs. Um dos principais cenários desta chamada é conceder um item a utilizadores que também têm um jogo específico. Se quiser conceder um único item promocional, use AddPromoItem. Se quiser conceder todos os itens promocionais possíveis, use GrantPromoItems.

Qualquer item que possa ser concedido TEM de conter o atributo "promo" na respetiva ItemDef. O item promocional lista os AppIDs que o utilizador deve possuir para que possa receber o item. Esta versão irá conceder todos os itens com um atributo "promo" especificado nas definições de itens configuradas. Desta forma, é possível adicionar mais itens promocionais sem ser necessário atualizar a aplicação do jogo. Por exemplo, o seguinte atributo irá permitir que o item seja concedido se o utilizador tiver o jogo TF2 ou Spacewar.

promo: owns:440;owns:480

Retorna: bool
Esta função retorna sempre true quando é chamada por um utilizador comum e retorna sempre false quando é chamada a partir de SteamGameServer.

Em caso de sucesso, o resultado do inventário irá incluir os itens que foram concedidos, se algum existe. Se nenhum item foi concedido porque o utilizador não é elegível para nenhuma promoção, a chamada é mesmo assim considerada um sucesso.

Retorna um handle de resultado novo via pResultHandle.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

Exemplo:

CheckResultSteamID

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado do inventário cujo SteamID verificar.
steamIDExpected	CSteamID	O SteamID que se pretende verificar.

Verifica se o handle de um resultado do inventário pertence ao SteamID especificado.

Esta função é importante ao usar DeserializeResult para confirmar que um jogador remoto não está a fingir ter o inventário de outro utilizador.

Retorna: bool
true se o resultado pertence ao SteamID especificado. Caso contrário, irá retornar false.

ConsumeItem

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um handle de resultado novo do inventário.
itemConsume	SteamItemInstanceID_t	O ID da instância do item que se pretende consumir.
unQuantity	uint32	O número de itens na pilha que se pretende consumir.

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

Uma vez removido um item, não será possível recuperá-lo. Use esta função com prudência: se implementou uma funcionalidade de eliminação de itens no seu jogo, recomendamos que inclua um processo de confirmação com uma interface explicativa e detalhada.

Retorna: bool
Esta função retorna sempre true quando é chamada por um utilizador comum e retorna sempre false quando é chamada a partir de SteamGameServer.

Retorna um handle de resultado novo via pResultHandle.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

Consulte também: ExchangeItems, TransferItemQuantity

Exemplo:

DeserializeResult

Nome	Tipo	Descrição
pOutResultHandle	SteamInventoryResult_t *	Retorna um handle de resultado novo do inventário.
pBuffer	const void *	O buffer que se pretende desserializar.
unBufferSize	uint32	O tamanho de 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 continuará a ter sucesso neste modo. O resultado "expired" pode indicar que os dados estão desatualizados, não devido ao tempo de validade (uma hora), mas também porque um dos itens no conjunto de resultados pode ter sido trocado ou consumido depois de o conjunto de resultados ter sido gerado. É possível comparar a data e a hora retornadas pela função GetResultTimestamp com as retornadas por ISteamUtils::GetServerRealTime para determinar a idade dos dados. Pode ignorar o código de resultado "expired" e continuar normalmente ou pode pedir ao jogador com dados expirados que envie um conjunto de resultados atualizado.

Deve chamar a função CheckResultSteamID com o handle do resultado após a conclusão para confirmar que um jogador remoto não está a fingir ter o inventário de outro utilizador.

ATENÇÃO: o parâmetro bRESERVED_MUST_BE_FALSE está reservado para utilização futura e nunca deve ser definido como true.

Retorna: bool
Retorna sempre true e depois envia códigos de erro através da função GetResultStatus.

Retorna um handle de resultado novo via pResultHandle.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

DestroyResult

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

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

ExchangeItems

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

Concede um item como resultado da conversão de um conjunto de outros itens.

Esta função pode ser usada para implementar receitas, transmutações ou itens que são abertos para conceder outros itens (por exemplo, uma arca de tesouro).

Ao chamar esta API, é passado um item específico, uma lista de itens existentes e as quantidades usadas na conversão. Atualmente, API aceita um array de itens para gerar, mas o tamanho dessa lista deve ser 1 e a quantidade do item novo deve ser 1.

Qualquer item que possa ser concedido TEM de conter o atributo "exchange" na respetiva ItemDef. O atributo "exchange" especifica um conjunto de receitas que são conversões válidas para este item. Receitas de conversão são avaliadas de uma só vez pelo serviço de inventário; se os componentes fornecidos não corresponderem à receita ou não contiverem a quantidade suficiente, a conversão irá falhar.

Por exemplo:

Isto permitirá que o item seja convertido num item 101 + um item 102; em cinco itens 103; ou em três itens 104 + três itens 105. Consulte o artigo Inventário Steam - Esquema para mais detalhes.

Retorna: bool
Esta função retorna true em caso de sucesso. Retorna false quando chamada por SteamGameServer ou se unArrayGenerateLength ou punArrayGenerateQuantity não forem 1.

Conversões que não corresponderem a uma receita ou que não concederem as quantidades requeridas irão falhar.

Retorna um handle de resultado novo via pResultHandle.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

Consulte também: ConsumeItem, TransferItemQuantity

Exemplo:

GenerateItems

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um handle de resultado novo do inventário.
pArrayItemDefs	const SteamItemDef_t *	A lista de itens a conceder ao utilizador.
punArrayQuantity	const uint32 *	A quantidade de cada item em pArrayItemDefs que se pretende conceder (opcional, passar NULL irá especificar 1 de cada item).
unArrayLength	uint32	O número de itens em pArrayItemDefs.

Concede itens específicos ao utilizador atual (API usada apenas por developers).

Esta API foi concebida exclusivamente para fins de prototipagem e só pode ser usada por contas Steam que fazem parte do grupo de editora do seu jogo.

Pode passar um array com itens, identificados pelo SteamItemDef_t, e um segundo array opcional com as quantidades correspondentes de cada item. Estes arrays devem conter o mesmo número de elementos!

Retorna: bool
Esta função retorna sempre true quando é chamada por um utilizador comum e retorna sempre false quando é chamada a partir de SteamGameServer.

Retorna um handle de resultado novo via pResultHandle.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

Exemplo:

GetAllItems

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

Começa a obter todos os itens do inventário do utilizador atual.

ATENÇÃO: as chamadas a esta função estão sujeitas a limites de frequência e podem retornar resultados em cache se a função for chamada com demasiada frequência. Recomendamos que chame esta função apenas quando estiver prestes a apresentar o inventário completo do utilizador ou se estiver à espera que o inventário tenha sido alterado.

Retorna: bool
Esta função retorna sempre true quando é chamada por um utilizador comum e retorna sempre false quando é chamada a partir de SteamGameServer.

Retorna um handle de resultado novo via pResultHandle.

NOTA: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

Exemplo:

GetEligiblePromoItemDefinitionIDs

Nome	Tipo	Descrição
steamID	CSteamID	O SteamID do utilizador destinatário destes itens. Este valor deve ser igual ao de SteamInventoryEligiblePromoItemDefIDs_t.m_steamID.
pItemDefIDs	SteamItemDef_t *	Retorna os IDs de definição de item ao copiá-los para este array.
punItemDefIDsArraySize	uint32 *	O tamanho de pItemDefIDs, que deve ser igual a SteamInventoryEligiblePromoItemDefIDs_t.m_numEligiblePromoItemDefs.

Obtém a lista de IDs de definição de item que podem ser concedidos a um utilizador.

Deve chamar esta função ao processar o resultado de chamada SteamInventoryEligiblePromoItemDefIDs_t para obter os IDs de definição de item.

Retorna: bool


Consulte também: AddPromoItem, AddPromoItems

GetItemDefinitionIDs

Nome	Tipo	Descrição
pItemDefIDs	SteamItemDef_t *	Retorna as definições de itens ao copiá-los para este array.
punItemDefIDsArraySize	uint32 *	Deve ser do mesmo tamanho que pItemDefIDs. Se pItemDefIDs for NULL, será retornado o número de elementos necessários no array.

Retorna o conjunto de todos os IDs de definição de item configurados no painel de administração da aplicação no site do Steamworks.

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

Apenas deve ser chamada como resposta a um callback SteamInventoryDefinitionUpdate_t. Não há motivo para chamar esta função se os IDs de definição numéricos forem fixos no jogo (por exemplo, máscara roxa = 20, modificação de arma azul = 55) e não permite que novos tipos de item sejam adicionados sem uma atualização da aplicação.

Retorna: bool
Esta chamada retorna true em caso de sucesso. Apenas retorna false se as definições de itens não foram carregadas do servidor ou se não existirem definições de itens para a aplicação atual.

Se a chamada for bem-sucedida, punItemDefIDsArraySize irá conter o número de definições de itens disponíveis.

GetItemDefinitionProperty

Nome	Tipo	Descrição
iDefinition	SteamItemDef_t	A definição de item cujas propriedades se pretende obter.
pchPropertyName	const char *	O nome da propriedade cujo valor se pretende obter. Se passar NULL, então pchValueBuffer irá conter uma lista de todos os nomes disponíveis, separados por vírgula.
pchValueBuffer	char *	Retorna o valor associado com pchPropertyName.
punValueBufferSizeOut	uint32 *	Deve ser do mesmo tamanho que pchValueBuffer. Retorna o número de bytes necessários para armazenar o valor.

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

Nota: algumas propriedades (por exemplo, "name") podem ser traduzidas e irão depender das definições de idioma atuais do Steam (consulte ISteamApps::GetCurrentGameLanguage). Nomes de propriedades irão conter caracteres ASCII alfanuméricos e o traço de sublinhado ( _ ).

Passe NULL no parâmetro pchPropertyName para obter uma lista dos nomes das propriedades disponíveis, separados por vírgula. Neste modo, punValueBufferSizeOut irá conter o tamanho sugerido para o buffer. Caso contrário, irá conter o número de bytes copiados para pchValueBuffer.

Retorna: bool
Retorna true em caso de sucesso; false se as definições de itens não foram carregadas do servidor, se nenhuma definição de item existir para a aplicação atual ou se a definição de item não contiver o nome de propriedade especificado.

O valor associado é retornado através do pchValueBuffer e o número total de bytes necessários para armazenar o valor está disponível em punValueBufferSizeOut. Recomendamos que chame esta função duas vezes; a primeira com pchValueBuffer definido como NULL e punValueBufferSizeOut definido como 0 para obter o tamanho necessário para o buffer da chamada subsequente.

O output será algo como o seguinte:
pchPropertyName definido como NULL:
appid,itemdefid,Timestamp etc...
pchPropertyName definido como "name":
SW_DECORATION_HAT

ATENÇÃO: chame a função LoadItemDefinitions primeiro, para garantir que os itens estão prontos para serem usados, antes de chamar a função GetItemDefinitionProperty.

GetItemsByID

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

Obtém o estado de um subconjunto do inventário do utilizador atual.

O subconjunto é especificado por um array de IDs de instância de item.

Os resultados desta chamada podem ser serializados ao usar SerializeResult e passados a outros jogadores para "provar" que o utilizador atual possui itens específicos sem expor o respetivo inventário inteiro. Por exemplo, pode chamar esta função com os IDs dos itens equipados pelo utilizador, serializá-los num buffer e depois transmitir este buffer para os outros jogadores ao entrar numa partida.

Retorna: bool
Esta função retorna sempre true quando é chamada por um utilizador comum e retorna sempre false quando é chamada a partir de SteamGameServer.

Retorna um handle de resultado novo via pResultHandle.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

GetItemPrice

Nome	Tipo	Descrição
iDefinition	SteamItemDef_t	O ID da definição de item cujo preço se pretende obter.
pPrice	uint64*	O ponteiro de preço que se pretende preencher. Os preços são apresentados na moeda local do utilizador.

Depois de uma chamada bem-sucedida a RequestPrices, pode chamar esta função para obter os preços de uma definição de item específica.

Retorna: bool
true em caso de sucesso, indicando que pPrice foi preenchido com o preço da definição de item especificada;
false se os parâmetros forem inválidos ou se não houver um preço associado à definição de item especificada.

Consulte também: RequestPrices

GetItemsWithPrices

Nome	Tipo	Descrição
pArrayItemDefs	SteamItemDef_t *	O array de IDs de definição de item que se pretende preencher.
pPrices	uint64*	O array de preços para cada ID de definição de item correspondente em pArrayItemDefs. Os preços são apresentados na moeda local do utilizador.
unArrayLength	uint32	Deve ser o tamanho dos arrays pArrayItemDefs e pPrices, resultantes da chamada a GetNumItemsWithPrices.

Depois de uma chamada bem-sucedida a RequestPrices, pode chamar esta função para obter todos os preços de definições de itens aplicáveis. Use o resultado de GetNumItemsWithPrices como o tamanho dos arrays passados.

Retorna: bool
true em caso de sucesso, indicando que 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

Depois de uma chamada bem-sucedida a RequestPrices, será retornado o número de definições de itens 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 se pretende obter.
unItemIndex	uint32
pchPropertyName	const char *	O nome da propriedade cujo valor se pretende obter. Se for NULL, pchValueBuffer irá conter uma lista de todos os nomes disponíveis, separados por vírgula.
pchValueBuffer	char *	Retorna o valor associado com pchPropertyName.
punValueBufferSizeOut	uint32 *	Deve ser do mesmo tamanho que pchValueBuffer. Retorna o número de bytes necessários para armazenar o valor.

Obtém as propriedades dinâmicas de um item num conjunto de resultados de inventário.

Nomes de propriedades são sempre compostos de caracteres ASCII alfanuméricos e o traço de sublinhado ( _ ).

Se os resultados não couberem no buffer fornecido, poderão ser copiados resultados parciais.

Retorna: bool
Retorna true em caso de sucesso; false se o handle do resultado do inventário for inválido ou se o índice fornecido não contiver um item.

GetResultItems

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado do inventário cujos itens se pretende obter.
pOutItemsArray	SteamItemDetails_t *	Os detalhes são retornados ao copiá-los para este array.
punOutItemsArraySize	uint32 *	Deve ser do mesmo tamanho que pOutItemsArray. Se pOutItemsArray for NULL, será retornado o número de elementos necessários no array.

Obtém os itens associados ao handle do resultado do inventário.

Retorna: bool
true se a chamada foi bem-sucedida; caso contrário, irá retornar false.
Possíveis motivos de falha:

• resultHandle é inválido ou o handle do resultado do inventário não está pronto.
  
• pOutItemsArray é demasiado pequeno para armazenar o array.
  
• O utilizador não tem itens.

Se a chamada for bem-sucedida, punItemDefIDsArraySize irá conter o número 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 se pretende obter.

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

É o equivalente de "polling" a registar uma função para o callback SteamInventoryResultReady_t.

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

Valores possíveis:

• k_EResultPending – Em curso.
  
• k_EResultOK – Pronto; o pedido foi concluído com sucesso e o resultado está pronto.
  
• k_EResultExpired – Pronto; o resultado está pronto, talvez desatualizado (consultar DeserializeResult).
  
• k_EResultInvalidParam – ERRO: parâmetros de chamada à API inválidos.
  
• k_EResultServiceUnavailable – ERRO: o serviço está indisponível temporariamente, tente mais tarde.
  
• k_EResultLimitExceeded – ERRO: a operação ultrapassaria os limites de acessos.
  
• k_EResultFail – ERRO: erro genérico.

Exemplo:

GetResultTimestamp

Nome	Tipo	Descrição
resultHandle	SteamInventoryResult_t	O handle do resultado do inventário cuja data e hora se pretende obter.

Obtém a data e a hora do servidor em que o resultado foi gerado.

Retorna: uint32
A data e a hora são especificadas no formato de Era Unix (segundos desde 1 de janeiro de 1970).

Pode comparar este valor com ISteamUtils::GetServerRealTime para determinar a idade do resultado.

GrantPromoItems

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

Concede todos os itens promocionais únicos ao utilizador atual.

Esta função pode ser chamada em segurança a partir da aplicação Steam, porque os itens que pode conceder podem ser bloqueados mediante políticas nas ItemDefs. Um dos principais cenários desta chamada é conceder um item a utilizadores que também têm um jogo específico. Caso queira conceder um item promocional específico em vez de todos, consulte: AddPromoItem e AddPromoItems.

Qualquer item que possa ser concedido TEM de conter o atributo "promo" na respetiva ItemDef. O item promocional lista os AppIDs que o utilizador deve possuir para que possa receber o item. Esta versão irá conceder todos os itens com um atributo "promo" especificado nas ItemDefs configuradas. Desta forma, é possível adicionar mais itens promocionais sem ser necessário atualizar a aplicação do jogo. Por exemplo, o seguinte atributo irá permitir que o item seja concedido se o utilizador tiver o jogo TF2 ou Spacewar.

promo: owns:440;owns:480

Retorna: bool
Esta função retorna sempre true quando é chamada por um utilizador comum e retorna sempre false quando é chamada a partir de SteamGameServer.

Em caso de sucesso, o resultado do inventário irá incluir os itens que foram concedidos, se algum existe. Se nenhum item foi concedido porque o utilizador não é elegível para nenhuma promoção, a chamada é mesmo assim considerada um sucesso.

Retorna um handle de resultado novo via pResultHandle.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

Exemplo:

LoadItemDefinitions

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

Definições de itens são um mapeamento de "IDs de definições" (números inteiros entre 1 e 999999999) a um conjunto de strings de propriedades. Algumas destas propriedades são obrigatórias para apresentar itens no site da Comunidade Steam. Outras propriedades podem ser definidas por aplicações. Não há motivo para chamar esta função se os IDs de definição numéricos forem fixos no jogo (por exemplo, máscara roxa = 20, modificação de arma azul = 55) e não permite que novos tipos de item sejam adicionados sem uma atualização da aplicação.

Retorna: bool
Ativa um callback SteamInventoryDefinitionUpdate_t.
Retorna sempre true.

RequestEligiblePromoItemDefinitionsIDs

Nome	Tipo	Descrição
steamID	CSteamID	O SteamID do utilizador cuja lista de itens promocionais disponíveis para concessão se pretende obter.

Pede a lista de itens promocionais que podem ser concedidos manualmente ao utilizador especificado.

Estes são itens promocionais do tipo "manual" que não serão concedidos automaticamente. Um exemplo de utilização seria um item que se torna disponível todas as semanas.

Depois de chamar esta função, precisa de chamar GetEligiblePromoItemDefinitionIDs para obter os IDs de definição dos itens em questão.

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

RequestPrices

Obtém os preços de todas as definições de itens que podem ser comprados na moeda local do utilizador. Um resultado de chamada SteamInventoryRequestPricesResult_t será retornado com o código da moeda local do utilizador. De seguida, chame GetNumItemsWithPrices e GetItemsWithPrices para obter os preços de todas as definições de itens conhecidas, ou GetItemPrice para uma definição de item específica.

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

Consulte também: GetNumItemsWithPrices, GetItemsWithPrices, GetItemPrice

SendItemDropHeartbeat

Obsoleto.

SerializeResult

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

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

Um conjunto de resultados pode ser serializado no cliente local, transmitido para outros jogadores através do sistema de rede do seu jogo e desserializado pelos jogadores remotos. Esta é uma forma segura de impedir que algum hacker finja possuir itens raros ou de grande valor. Serializa um conjunto de resultados com bytes de assinatura e copia-o para um buffer de output. O tamanho de um resultado serializado depende do número de itens serializados. Ao transmitir itens de modo seguro para outros jogadores, é recomendado que use primeiro a função GetItemsByID para criar um conjunto de resultados mínimo.

Os resultados contêm a indicação da hora, que será considerada "expirada" depois de uma hora se ter passado. Consulte DeserializeResult para informações sobre a gestão de dados expirados.

Se pOutBuffer for NULL, então punOutBufferSize será o tamanho necessário do buffer. Pode criar o buffer e, de seguida, chamar esta função novamente para o preencher com o tamanho necessário do buffer.

Retorna: bool
true em caso de sucesso, 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 se:

• Esta função não foi chamada por um utilizador comum. Esta chamada não é permitida em GameServers.
  
• resultHandle é inválido ou o handle do resultado do inventário não está pronto.
  
• O valor passado para punOutBufferSize era mais pequeno do que o esperado e pOutBuffer não era NULL.

StartPurchase

Nome	Tipo	Descrição
pArrayItemDefs	SteamItemDef_t *	O array de IDs de definição de item que o utilizador pretende comprar.
punArrayQuantity	uint32 *	O array com as quantidades de cada definição de item que o utilizador pretende comprar.
unArrayLength	uint32	O tamanho dos arrays pArrayItemDefs e punArrayQuantity.

Inicia o processo de compra para o utilizador, dado um "carrinho de compras" de definições de item que o utilizador pretende comprar. No Painel Steam, será pedido ao utilizador que conclua a compra na moeda local e, se necessário para tal, que adicione fundos à Carteira Steam.

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

Se o utilizador autorizar a transação e concluir a compra, o callback SteamInventoryResultReady_t será ativado e poderá obter os novos itens adquiridos. ATENÇÃO: deve chamar DestroyResult no resultado do inventário quando o terminar de usar.

Retorna: SteamAPICall_t, a ser usado com um resultado de chamada SteamInventoryStartPurchaseResult_t.
Returns k_uAPICallInvalid se o input foi inválido.

TransferItemQuantity

Nome	Tipo	Descrição
pResultHandle	SteamInventoryResult_t *	Retorna um handle de resultado novo do inventário.
itemIdSource	SteamItemInstanceID_t	O item original cuja quantidade se pretende transferir.
unQuantity	uint32	A quantidade do item que será transferida de itemIdSource para itemIdDest.
itemIdDest	SteamItemInstanceID_t	O item de destino. Pode passar k_SteamItemInstanceIDInvalid para dividir a pilha original em novas pilhas de itens com a quantidade pedida.

Transfere itens entre pilhas dentro do inventário de um utilizador.

Esta função pode ser usada para empilhar, dividir e mover itens. Os itens originais e de destino devem ter o mesmo ID de definição de item. De forma a mover itens para uma pilha de destino, especifique o item original, a quantidade que pretende mover e o ID do item de destino. Para dividir uma pilha existente, passe k_SteamItemInstanceIDInvalid para itemIdDest. Uma nova pilha de itens será gerada com a quantidade pedida.

ATENÇÃO: as restrições de troca e de Mercado são copiadas com os itens transferidos. A pilha de destino recebe as restrições de troca e de Mercado com a data mais distante de entre os itens incluídos.

Retorna: bool
Esta função retorna sempre true quando é chamada por um utilizador comum e retorna sempre false quando é chamada a partir de SteamGameServer.

Retorna um handle de resultado novo via pResultHandle.

NOTA: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

Consulte também: ConsumeItem, ExchangeItems

Exemplo:

TriggerItemDrop

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

Concede um item se o utilizador tiver jogado durante um período suficiente.

Este período pode ser personalizado em dois locais:

• A nível da aplicação, na secção de serviço de inventário: Distribuições de itens por tempo de jogo. As alterações irão aplicar-se automaticamente a todos os itens do tipo "playtimegenerator" sem valores especificados.
  
• Na definição de um item do tipo "playtimegenerator". Esta configuração terá prioridade sobre qualquer valor especificado a nível da aplicação.

Apenas definições de itens marcadas como "playtimegenerator" podem ser geradas.

Normalmente, esta função deve ser chamada no fim de um jogo, nível, partida ou qualquer outro ponto significativo do jogo em que um item pode ser concedido. Como o gerador de itens é definido à base de minutos, chamar esta função mais de uma vez por minuto não é útil e a aplicação Steam irá limitar a sua frequência de utilização. Os servidores do Steam irão analisar o tempo de jogo para impedirem que itens sejam concedidos com demasiada frequência. Os servidores também tratam de adicionar o item ao inventário do jogador.

Retorna: bool
Esta função retorna sempre true quando é chamada por um utilizador comum e retorna sempre false quando é chamada a partir de SteamGameServer.

Retorna um handle de resultado novo via pResultHandle.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

O resultado do inventário retornado por esta função será o novo item concedido se o jogador puder receber um. Caso contrário, será retornado um resultado vazio ("[]").

Exemplo:

StartUpdateProperties

Inicia um pedido de transação para atualizar as propriedades dinâmicas de itens do utilizador atual. A frequência desta chamada é limitada por utilizador, logo modificações de propriedades devem ser agrupadas sempre que possível (por exemplo, no fim de um mapa ou sessão). Depois de chamar SetProperty ou RemoveProperty para todos os itens que pretende modificar, terá de chamar SubmitUpdateProperties para enviar o pedido aos servidores do Steam. Irá ocorrer um callback SteamInventoryResultReady_t com os resultados da operação.

Exemplo:

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido por SubmitUpdateProperties quando o terminar de usar.

Retorna: SteamInventoryUpdateHandle_t

Consulte também: SetProperty, RemoveProperty, SubmitUpdateProperties

SubmitUpdateProperties

Nome	Tipo	Descrição
handle	SteamInventoryUpdateHandle_t	O handle de atualização correspondente ao pedido de transação retornado por StartUpdateProperties.
pResultHandle	SteamInventoryResult_t *	Retorna um handle de resultado novo do inventário.

Envia o pedido de transação para modificar propriedades dinâmicas de itens do utilizador atual. Consulte: StartUpdateProperties.

ATENÇÃO: deve chamar DestroyResult no resultado do inventário fornecido quando o terminar de usar.

Retorna: bool

Consulte também: StartUpdateProperties, SetProperty, RemoveProperty

RemoveProperty

Nome	Tipo	Descrição
handle	SteamInventoryUpdateHandle_t	O handle de atualização correspondente ao pedido de transação retornado por StartUpdateProperties.
nItemID	SteamItemInstanceID_t	O ID do item a ser modificado.
pchPropertyName	const char*	A propriedade dinâmica a ser removida.

Remove uma propriedade dinâmica do item especificado.

Retorna: bool

Consulte também: StartUpdateProperties, SetProperty, SubmitUpdateProperties

SetProperty

Nome	Tipo	Descrição
handle	SteamInventoryUpdateHandle_t	O handle de atualização correspondente ao pedido de transação retornado por StartUpdateProperties.
nItemID	SteamItemInstanceID_t	O ID do item a ser modificado.
pchPropertyName	const char*	A propriedade dinâmica a ser adicionada ou atualizada.
pchPropertyValue	const char*	A string a ser definida.
bValue	bool	O valor booleano a ser definido.
nValue	int64	O valor inteiro de 64 bits a ser definido.
flValue	float	O número de ponto flutuante a ser definido.

Define uma propriedade dinâmica para o item especificado. Os tipos de valores possíveis são strings, booleanos, ints de 64 bits e floats de 32 bits.

Retorna: bool

Consulte também: StartUpdateProperties, RemoveProperty, SubmitUpdateProperties

Callbacks

Estes são os callbacks que podem ocorrer ao chamar SteamAPI_RunCallbacks. Muitos destes callbacks irão ocorrer diretamente como resposta às funções de membro de ISteamInventory.

SteamInventoryDefinitionUpdate_t

Este callback ocorre 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 (por exemplo, pela adição dinâmica de novos tipos de itens enquanto os jogadores estiverem a jogar).

Este callback não tem campos.

Funções associadas: LoadItemDefinitions

SteamInventoryEligiblePromoItemDefIDs_t

Este callback ocorre depois de ter pedido a lista de itens promocionais que podem ser concedidos manualmente ao utilizador especificado. Estes são itens promocionais do tipo "manual" que não serão concedidos automaticamente. Um exemplo de utilização seria um item que se torna disponível todas as semanas.

Nome	Tipo	Descrição
m_result	EResult	k_EResultOK em caso de sucesso. Qualquer outro valor indica falha.
m_steamID	CSteamID	O SteamID do utilizador destinatário destes itens.
m_numEligiblePromoItemDefs	int	O número de itens promocionais disponíveis para este utilizador. Deve usar este valor para criar um buffer SteamItemDef_t e assim obter as definições de itens com a função GetEligiblePromoItemDefinitionIDs.
m_bCachedData	bool	Indica que os dados foram obtidos da cache e não do servidor. Ocorre se o utilizador não tiver iniciado sessão ou se não pode estabelecer ligação com os servidores do Steam.

Funções associadas: RequestEligiblePromoItemDefinitionsIDs

SteamInventoryFullUpdate_t

Ocorre quando GetAllItems retorna, com sucesso, um resultado mais recente do que o último resultado conhecido (Não irá ocorrer se o inventário não foi alterado ou se os resultados de duas chamadas seguidas chegaram em ordem inversa e já se sabe que o resultado da primeira chamada é antigo ou está desatualizado).
O callback SteamInventoryResultReady_t comum irá ocorrer de imediato logo a seguir; esta é uma notificação adicional para a sua conveniência.

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

SteamInventoryResultReady_t

Ocorre sempre que um resultado do inventário faz a transição do estado k_EResultPending para qualquer outro estado de conclusão. Consulte GetResultStatus para a lista completa de estados. Haverá sempre exatamente um callback por handle.

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

SteamInventoryStartPurchaseResult_t

Este callback ocorre após uma chamada à função StartPurchase.

Nome	Tipo	Descrição
m_result	EResult	k_EResultOK em caso de sucesso. Qualquer outro valor indica falha.
m_ulOrderID	uint64	O ID gerado automaticamente (OrderID) do pedido associado à compra iniciada.
m_ulTransID	uint64	O ID gerado automaticamente da transação referente à compra iniciada.

SteamInventoryRequestPricesResult_t

Este callback ocorre após uma chamada à função RequestPrices.

Nome	Tipo	Descrição
m_result	EResult	k_EResultOK em caso de sucesso. Qualquer outro valor indica falha.
m_rgchCurrency	char	A string que representa o código da moeda local do utilizador.

Structs

As funções de ISteamInventory podem retornar e/ou interagir com estas structs.

SteamItemDetails_t

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

Enums

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

ESteamItemFlags

Bit flags definidos em SteamItemDetails_t.

Nome	Valor	Descrição
k_ESteamItemNoTrade	1 << 0	O item está preso à conta e não pode ser trocado ou oferecido. Esta é uma flag de estado que é anexada permanentemente a instâncias de item específicas.
k_ESteamItemRemoved	1 << 8	Item destruído, trocado, expirado ou invalidado. Esta é uma flag de confirmação de ação que é definida apenas uma vez como parte de um conjunto de resultados.
k_ESteamItemConsumed	1 << 9	A quantidade do item foi reduzida em 1 através da API ConsumeItem. Esta é uma flag de confirmação de ação que é definida apenas uma vez como parte de um conjunto de resultados.

Typedefs

Estes são os typedefs definidos 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	Os tipos de itens no seu jogo são identificados por um "número de definição de item" de 32 bits. Números de definição válidos vão de 1 a 999999999. Números menores do que/iguais a zero são inválidos e números maiores do que/iguais a mil milhões (1x10^9) são reservados para uso interno do Steam.
SteamItemInstanceID_t	uint64	Cada instância individual de um item tem um ID da instância globalmente único. Este ID é único para a combinação de um jogador e instância específica de item. Não será transferido para outro jogador nem reutilizado para outro item.
SteamInventoryUpdateHandle_t	uint64	Retornado pela função StartUpdateProperties, que inicia um pedido de transação para modificar propriedades dinâmicas em itens do utilizador 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. Normalmente retornado quando uma operação falha. Recomendamos que inicialize todas as novas instâncias de item com este valor.
STEAMINVENTORY_INTERFACE_VERSION	const char *	"STEAMINVENTORY_INTERFACE_V002"