This repository has been archived on 2024-06-13. You can view files and clone it, but cannot push or open issues or pull requests.
2020-08-04 13:13:01 -04:00

496 lines
23 KiB
C++

//====== Copyright 1996-2013, Valve Corporation, All rights reserved. =======
//
// Purpose: interface to steam ugc
//
//=============================================================================
#ifndef ISTEAMUGC_H
#define ISTEAMUGC_H
#ifdef _WIN32
#pragma once
#endif
#include "isteamclient.h"
// callbacks
#if defined(VALVE_CALLBACK_PACK_SMALL)
#pragma pack(push, 4)
#elif defined(VALVE_CALLBACK_PACK_LARGE)
#pragma pack(push, 8)
#else
#error isteamclient.h must be included
#endif
typedef uint64 UGCQueryHandle_t;
typedef uint64 UGCUpdateHandle_t;
const UGCQueryHandle_t k_UGCQueryHandleInvalid = 0xffffffffffffffffull;
const UGCUpdateHandle_t k_UGCUpdateHandleInvalid = 0xffffffffffffffffull;
// Matching UGC types for queries
enum EUGCMatchingUGCType {
k_EUGCMatchingUGCType_Items = 0, // both mtx items and ready-to-use items
k_EUGCMatchingUGCType_Items_Mtx = 1,
k_EUGCMatchingUGCType_Items_ReadyToUse = 2,
k_EUGCMatchingUGCType_Collections = 3,
k_EUGCMatchingUGCType_Artwork = 4,
k_EUGCMatchingUGCType_Videos = 5,
k_EUGCMatchingUGCType_Screenshots = 6,
k_EUGCMatchingUGCType_AllGuides =
7, // both web guides and integrated guides
k_EUGCMatchingUGCType_WebGuides = 8,
k_EUGCMatchingUGCType_IntegratedGuides = 9,
k_EUGCMatchingUGCType_UsableInGame =
10, // ready-to-use items and integrated guides
k_EUGCMatchingUGCType_ControllerBindings = 11,
k_EUGCMatchingUGCType_GameManagedItems =
12, // game managed items (not managed by users)
};
// Different lists of published UGC for a user.
// If the current logged in user is different than the specified user, then some
// options may not be allowed.
enum EUserUGCList {
k_EUserUGCList_Published,
k_EUserUGCList_VotedOn,
k_EUserUGCList_VotedUp,
k_EUserUGCList_VotedDown,
k_EUserUGCList_WillVoteLater,
k_EUserUGCList_Favorited,
k_EUserUGCList_Subscribed,
k_EUserUGCList_UsedOrPlayed,
k_EUserUGCList_Followed,
};
// Sort order for user published UGC lists (defaults to creation order
// descending)
enum EUserUGCListSortOrder {
k_EUserUGCListSortOrder_CreationOrderDesc,
k_EUserUGCListSortOrder_CreationOrderAsc,
k_EUserUGCListSortOrder_TitleAsc,
k_EUserUGCListSortOrder_LastUpdatedDesc,
k_EUserUGCListSortOrder_SubscriptionDateDesc,
k_EUserUGCListSortOrder_VoteScoreDesc,
k_EUserUGCListSortOrder_ForModeration,
};
// Combination of sorting and filtering for queries across all UGC
enum EUGCQuery {
k_EUGCQuery_RankedByVote = 0,
k_EUGCQuery_RankedByPublicationDate = 1,
k_EUGCQuery_AcceptedForGameRankedByAcceptanceDate = 2,
k_EUGCQuery_RankedByTrend = 3,
k_EUGCQuery_FavoritedByFriendsRankedByPublicationDate = 4,
k_EUGCQuery_CreatedByFriendsRankedByPublicationDate = 5,
k_EUGCQuery_RankedByNumTimesReported = 6,
k_EUGCQuery_CreatedByFollowedUsersRankedByPublicationDate = 7,
k_EUGCQuery_NotYetRated = 8,
k_EUGCQuery_RankedByTotalVotesAsc = 9,
k_EUGCQuery_RankedByVotesUp = 10,
k_EUGCQuery_RankedByTextSearch = 11,
k_EUGCQuery_RankedByTotalUniqueSubscriptions = 12,
};
enum EItemUpdateStatus {
k_EItemUpdateStatusInvalid =
0, // The item update handle was invalid, job might be finished, listen
// too SubmitItemUpdateResult_t
k_EItemUpdateStatusPreparingConfig =
1, // The item update is processing configuration data
k_EItemUpdateStatusPreparingContent =
2, // The item update is reading and processing content files
k_EItemUpdateStatusUploadingContent =
3, // The item update is uploading content changes to Steam
k_EItemUpdateStatusUploadingPreviewFile =
4, // The item update is uploading new preview file image
k_EItemUpdateStatusCommittingChanges =
5 // The item update is committing all changes
};
enum EItemState {
k_EItemStateNone = 0, // item not tracked on client
k_EItemStateSubscribed =
1, // current user is subscribed to this item. Not just cached.
k_EItemStateLegacyItem = 2, // item was created with ISteamRemoteStorage
k_EItemStateInstalled =
4, // item is installed and usable (but maybe out of date)
k_EItemStateNeedsUpdate =
8, // items needs an update. Either because it's not installed yet or
// creator updated content
k_EItemStateDownloading = 16, // item update is currently downloading
k_EItemStateDownloadPending =
32, // DownloadItem() was called for this item, content isn't available
// until DownloadItemResult_t is fired
};
enum EItemStatistic {
k_EItemStatistic_NumSubscriptions = 0,
k_EItemStatistic_NumFavorites = 1,
k_EItemStatistic_NumFollowers = 2,
k_EItemStatistic_NumUniqueSubscriptions = 3,
k_EItemStatistic_NumUniqueFavorites = 4,
k_EItemStatistic_NumUniqueFollowers = 5,
k_EItemStatistic_NumUniqueWebsiteViews = 6,
k_EItemStatistic_ReportScore = 7,
};
const uint32 kNumUGCResultsPerPage = 50;
const uint32 k_cchDeveloperMetadataMax = 5000;
// Details for a single published file/UGC
struct SteamUGCDetails_t {
PublishedFileId_t m_nPublishedFileId;
EResult m_eResult; // The result of the operation.
EWorkshopFileType m_eFileType; // Type of the file
AppId_t m_nCreatorAppID; // ID of the app that created this file.
AppId_t m_nConsumerAppID; // ID of the app that will consume this file.
char m_rgchTitle[k_cchPublishedDocumentTitleMax]; // title of document
char
m_rgchDescription[k_cchPublishedDocumentDescriptionMax]; // description
// of document
uint64 m_ulSteamIDOwner; // Steam ID of the user who created this content.
uint32 m_rtimeCreated; // time when the published file was created
uint32 m_rtimeUpdated; // time when the published file was last updated
uint32
m_rtimeAddedToUserList; // time when the user added the published file
// to their list (not always applicable)
ERemoteStoragePublishedFileVisibility m_eVisibility; // visibility
bool m_bBanned; // whether the file was banned
bool m_bAcceptedForUse; // developer has specifically flagged this item as
// accepted in the Workshop
bool m_bTagsTruncated; // whether the list of tags was too long to be
// returned in the provided buffer
char m_rgchTags[k_cchTagListMax]; // comma separated list of all tags
// associated with this file
// file/url information
UGCHandle_t m_hFile; // The handle of the primary file
UGCHandle_t m_hPreviewFile; // The handle of the preview file
char m_pchFileName[k_cchFilenameMax]; // The cloud filename of the primary
// file
int32 m_nFileSize; // Size of the primary file
int32 m_nPreviewFileSize; // Size of the preview file
char m_rgchURL[k_cchPublishedFileURLMax]; // URL (for a video or a website)
// voting information
uint32 m_unVotesUp; // number of votes up
uint32 m_unVotesDown; // number of votes down
float m_flScore; // calculated score
// collection details
uint32 m_unNumChildren;
};
//-----------------------------------------------------------------------------
// Purpose: Steam UGC support API
//-----------------------------------------------------------------------------
class ISteamUGC {
public:
// Query UGC associated with a user. Creator app id or consumer app id must
// be valid and be set to the current running app. unPage should start at 1.
virtual UGCQueryHandle_t CreateQueryUserUGCRequest(
AccountID_t unAccountID, EUserUGCList eListType,
EUGCMatchingUGCType eMatchingUGCType, EUserUGCListSortOrder eSortOrder,
AppId_t nCreatorAppID, AppId_t nConsumerAppID, uint32 unPage) = 0;
// Query for all matching UGC. Creator app id or consumer app id must be
// valid and be set to the current running app. unPage should start at 1.
virtual UGCQueryHandle_t CreateQueryAllUGCRequest(
EUGCQuery eQueryType,
EUGCMatchingUGCType eMatchingeMatchingUGCTypeFileType,
AppId_t nCreatorAppID, AppId_t nConsumerAppID, uint32 unPage) = 0;
// Query for the details of the given published file ids (the
// RequestUGCDetails call is deprecated and replaced with this)
virtual UGCQueryHandle_t CreateQueryUGCDetailsRequest(
PublishedFileId_t *pvecPublishedFileID,
uint32 unNumPublishedFileIDs) = 0;
// Send the query to Steam
virtual SteamAPICall_t SendQueryUGCRequest(UGCQueryHandle_t handle) = 0;
// Retrieve an individual result after receiving the callback for querying
// UGC
virtual bool GetQueryUGCResult(UGCQueryHandle_t handle, uint32 index,
SteamUGCDetails_t *pDetails) = 0;
virtual bool GetQueryUGCPreviewURL(UGCQueryHandle_t handle, uint32 index,
char *pchURL, uint32 cchURLSize) = 0;
virtual bool GetQueryUGCMetadata(UGCQueryHandle_t handle, uint32 index,
char *pchMetadata,
uint32 cchMetadatasize) = 0;
virtual bool GetQueryUGCChildren(UGCQueryHandle_t handle, uint32 index,
PublishedFileId_t *pvecPublishedFileID,
uint32 cMaxEntries) = 0;
virtual bool GetQueryUGCStatistic(UGCQueryHandle_t handle, uint32 index,
EItemStatistic eStatType,
uint32 *pStatValue) = 0;
virtual uint32 GetQueryUGCNumAdditionalPreviews(UGCQueryHandle_t handle,
uint32 index) = 0;
virtual bool GetQueryUGCAdditionalPreview(UGCQueryHandle_t handle,
uint32 index, uint32 previewIndex,
char *pchURLOrVideoID,
uint32 cchURLSize,
bool *pbIsImage) = 0;
virtual uint32 GetQueryUGCNumKeyValueTags(UGCQueryHandle_t handle,
uint32 index) = 0;
virtual bool GetQueryUGCKeyValueTag(UGCQueryHandle_t handle, uint32 index,
uint32 keyValueTagIndex, char *pchKey,
uint32 cchKeySize, char *pchValue,
uint32 cchValueSize) = 0;
// Release the request to free up memory, after retrieving results
virtual bool ReleaseQueryUGCRequest(UGCQueryHandle_t handle) = 0;
// Options to set for querying UGC
virtual bool AddRequiredTag(UGCQueryHandle_t handle,
const char *pTagName) = 0;
virtual bool AddExcludedTag(UGCQueryHandle_t handle,
const char *pTagName) = 0;
virtual bool SetReturnKeyValueTags(UGCQueryHandle_t handle,
bool bReturnKeyValueTags) = 0;
virtual bool SetReturnLongDescription(UGCQueryHandle_t handle,
bool bReturnLongDescription) = 0;
virtual bool SetReturnMetadata(UGCQueryHandle_t handle,
bool bReturnMetadata) = 0;
virtual bool SetReturnChildren(UGCQueryHandle_t handle,
bool bReturnChildren) = 0;
virtual bool SetReturnAdditionalPreviews(
UGCQueryHandle_t handle, bool bReturnAdditionalPreviews) = 0;
virtual bool SetReturnTotalOnly(UGCQueryHandle_t handle,
bool bReturnTotalOnly) = 0;
virtual bool SetLanguage(UGCQueryHandle_t handle,
const char *pchLanguage) = 0;
virtual bool SetAllowCachedResponse(UGCQueryHandle_t handle,
uint32 unMaxAgeSeconds) = 0;
// Options only for querying user UGC
virtual bool SetCloudFileNameFilter(UGCQueryHandle_t handle,
const char *pMatchCloudFileName) = 0;
// Options only for querying all UGC
virtual bool SetMatchAnyTag(UGCQueryHandle_t handle, bool bMatchAnyTag) = 0;
virtual bool SetSearchText(UGCQueryHandle_t handle,
const char *pSearchText) = 0;
virtual bool SetRankedByTrendDays(UGCQueryHandle_t handle,
uint32 unDays) = 0;
virtual bool AddRequiredKeyValueTag(UGCQueryHandle_t handle,
const char *pKey,
const char *pValue) = 0;
// DEPRECATED - Use CreateQueryUGCDetailsRequest call above instead!
virtual SteamAPICall_t RequestUGCDetails(PublishedFileId_t nPublishedFileID,
uint32 unMaxAgeSeconds) = 0;
// Steam Workshop Creator API
virtual SteamAPICall_t CreateItem(
AppId_t nConsumerAppId,
EWorkshopFileType eFileType) = 0; // create new item for this app with
// no content attached yet
virtual UGCUpdateHandle_t StartItemUpdate(
AppId_t nConsumerAppId,
PublishedFileId_t
nPublishedFileID) = 0; // start an UGC item update. Set changed
// properties before commiting update with
// CommitItemUpdate()
virtual bool SetItemTitle(
UGCUpdateHandle_t handle,
const char *pchTitle) = 0; // change the title of an UGC item
virtual bool SetItemDescription(
UGCUpdateHandle_t handle,
const char
*pchDescription) = 0; // change the description of an UGC item
virtual bool SetItemUpdateLanguage(
UGCUpdateHandle_t handle,
const char *pchLanguage) = 0; // specify the language of the title or
// description that will be set
virtual bool SetItemMetadata(
UGCUpdateHandle_t handle,
const char *pchMetaData) = 0; // change the metadata of an UGC item
// (max = k_cchDeveloperMetadataMax)
virtual bool SetItemVisibility(
UGCUpdateHandle_t handle,
ERemoteStoragePublishedFileVisibility
eVisibility) = 0; // change the visibility of an UGC item
virtual bool SetItemTags(UGCUpdateHandle_t updateHandle,
const SteamParamStringArray_t
*pTags) = 0; // change the tags of an UGC item
virtual bool SetItemContent(
UGCUpdateHandle_t handle,
const char *pszContentFolder) = 0; // update item content from this
// local folder
virtual bool SetItemPreview(
UGCUpdateHandle_t handle,
const char
*pszPreviewFile) = 0; // change preview image file for this item.
// pszPreviewFile points to local image
// file, which must be under 1MB in size
virtual bool RemoveItemKeyValueTags(
UGCUpdateHandle_t handle,
const char *pchKey) = 0; // remove any existing key-value tags with the
// specified key
virtual bool AddItemKeyValueTag(
UGCUpdateHandle_t handle, const char *pchKey,
const char
*pchValue) = 0; // add new key-value tags for the item. Note that
// there can be multiple values for a tag.
virtual SteamAPICall_t SubmitItemUpdate(
UGCUpdateHandle_t handle,
const char *pchChangeNote) = 0; // commit update process started with
// StartItemUpdate()
virtual EItemUpdateStatus GetItemUpdateProgress(UGCUpdateHandle_t handle,
uint64 *punBytesProcessed,
uint64 *punBytesTotal) = 0;
// Steam Workshop Consumer API
virtual SteamAPICall_t SetUserItemVote(PublishedFileId_t nPublishedFileID,
bool bVoteUp) = 0;
virtual SteamAPICall_t GetUserItemVote(
PublishedFileId_t nPublishedFileID) = 0;
virtual SteamAPICall_t AddItemToFavorites(
AppId_t nAppId, PublishedFileId_t nPublishedFileID) = 0;
virtual SteamAPICall_t RemoveItemFromFavorites(
AppId_t nAppId, PublishedFileId_t nPublishedFileID) = 0;
virtual SteamAPICall_t SubscribeItem(
PublishedFileId_t nPublishedFileID) = 0; // subscribe to this item,
// will be installed ASAP
virtual SteamAPICall_t UnsubscribeItem(
PublishedFileId_t
nPublishedFileID) = 0; // unsubscribe from this item, will be
// uninstalled after game quits
virtual uint32 GetNumSubscribedItems() = 0; // number of subscribed items
virtual uint32 GetSubscribedItems(
PublishedFileId_t *pvecPublishedFileID,
uint32 cMaxEntries) = 0; // all subscribed item PublishFileIDs
// get EItemState flags about item on this client
virtual uint32 GetItemState(PublishedFileId_t nPublishedFileID) = 0;
// get info about currently installed content on disc for items that have
// k_EItemStateInstalled set if k_EItemStateLegacyItem is set, pchFolder
// contains the path to the legacy file itself (not a folder)
virtual bool GetItemInstallInfo(PublishedFileId_t nPublishedFileID,
uint64 *punSizeOnDisk, char *pchFolder,
uint32 cchFolderSize,
uint32 *punTimeStamp) = 0;
// get info about pending update for items that have k_EItemStateNeedsUpdate
// set. punBytesTotal will be valid after download started once
virtual bool GetItemDownloadInfo(PublishedFileId_t nPublishedFileID,
uint64 *punBytesDownloaded,
uint64 *punBytesTotal) = 0;
// download new or update already installed item. If function returns true,
// wait for DownloadItemResult_t. If the item is already installed, then
// files on disk should not be used until callback received. If item is not
// subscribed to, it will be cached for some time. If bHighPriority is set,
// any other item download will be suspended and this item downloaded ASAP.
virtual bool DownloadItem(PublishedFileId_t nPublishedFileID,
bool bHighPriority) = 0;
// game servers can set a specific workshop folder before issuing any UGC
// commands. This is helpful if you want to support multiple game servers
// running out of the same install folder
virtual bool BInitWorkshopForGameServer(DepotId_t unWorkshopDepotID,
const char *pszFolder) = 0;
};
#define STEAMUGC_INTERFACE_VERSION "STEAMUGC_INTERFACE_VERSION007"
//-----------------------------------------------------------------------------
// Purpose: Callback for querying UGC
//-----------------------------------------------------------------------------
struct SteamUGCQueryCompleted_t {
enum { k_iCallback = k_iClientUGCCallbacks + 1 };
UGCQueryHandle_t m_handle;
EResult m_eResult;
uint32 m_unNumResultsReturned;
uint32 m_unTotalMatchingResults;
bool m_bCachedData; // indicates whether this data was retrieved from the
// local on-disk cache
};
//-----------------------------------------------------------------------------
// Purpose: Callback for requesting details on one piece of UGC
//-----------------------------------------------------------------------------
struct SteamUGCRequestUGCDetailsResult_t {
enum { k_iCallback = k_iClientUGCCallbacks + 2 };
SteamUGCDetails_t m_details;
bool m_bCachedData; // indicates whether this data was retrieved from the
// local on-disk cache
};
//-----------------------------------------------------------------------------
// Purpose: result for ISteamUGC::CreateItem()
//-----------------------------------------------------------------------------
struct CreateItemResult_t {
enum { k_iCallback = k_iClientUGCCallbacks + 3 };
EResult m_eResult;
PublishedFileId_t
m_nPublishedFileId; // new item got this UGC PublishFileID
bool m_bUserNeedsToAcceptWorkshopLegalAgreement;
};
//-----------------------------------------------------------------------------
// Purpose: result for ISteamUGC::SubmitItemUpdate()
//-----------------------------------------------------------------------------
struct SubmitItemUpdateResult_t {
enum { k_iCallback = k_iClientUGCCallbacks + 4 };
EResult m_eResult;
bool m_bUserNeedsToAcceptWorkshopLegalAgreement;
};
//-----------------------------------------------------------------------------
// Purpose: a Workshop item has been installed or updated
//-----------------------------------------------------------------------------
struct ItemInstalled_t {
enum { k_iCallback = k_iClientUGCCallbacks + 5 };
AppId_t m_unAppID;
PublishedFileId_t m_nPublishedFileId;
};
//-----------------------------------------------------------------------------
// Purpose: result of DownloadItem(), existing item files can be accessed again
//-----------------------------------------------------------------------------
struct DownloadItemResult_t {
enum { k_iCallback = k_iClientUGCCallbacks + 6 };
AppId_t m_unAppID;
PublishedFileId_t m_nPublishedFileId;
EResult m_eResult;
};
//-----------------------------------------------------------------------------
// Purpose: result of AddItemToFavorites() or RemoveItemFromFavorites()
//-----------------------------------------------------------------------------
struct UserFavoriteItemsListChanged_t {
enum { k_iCallback = k_iClientUGCCallbacks + 7 };
PublishedFileId_t m_nPublishedFileId;
EResult m_eResult;
bool m_bWasAddRequest;
};
//-----------------------------------------------------------------------------
// Purpose: The result of a call to SetUserItemVote()
//-----------------------------------------------------------------------------
struct SetUserItemVoteResult_t {
enum { k_iCallback = k_iClientUGCCallbacks + 8 };
PublishedFileId_t m_nPublishedFileId;
EResult m_eResult;
bool m_bVoteUp;
};
//-----------------------------------------------------------------------------
// Purpose: The result of a call to GetUserItemVote()
//-----------------------------------------------------------------------------
struct GetUserItemVoteResult_t {
enum { k_iCallback = k_iClientUGCCallbacks + 9 };
PublishedFileId_t m_nPublishedFileId;
EResult m_eResult;
bool m_bVotedUp;
bool m_bVotedDown;
bool m_bVoteSkipped;
};
#pragma pack(pop)
#endif // ISTEAMUGC_H