//====== Copyright © 1996-2008, Valve Corporation, All rights reserved. ======= // // Purpose: interface to both friends list data and general information about users // //============================================================================= #ifndef ISTEAMFRIENDS_H #define ISTEAMFRIENDS_H #ifdef _WIN32 #pragma once #endif #include "isteamclient.h" #include "steamclientpublic.h" //----------------------------------------------------------------------------- // Purpose: set of relationships to other users //----------------------------------------------------------------------------- enum EFriendRelationship { k_EFriendRelationshipNone = 0, k_EFriendRelationshipBlocked = 1, k_EFriendRelationshipRequestRecipient = 2, k_EFriendRelationshipFriend = 3, k_EFriendRelationshipRequestInitiator = 4, k_EFriendRelationshipIgnored = 5, k_EFriendRelationshipIgnoredFriend = 6, }; //----------------------------------------------------------------------------- // Purpose: list of states a friend can be in //----------------------------------------------------------------------------- enum EPersonaState { k_EPersonaStateOffline = 0, // friend is not currently logged on k_EPersonaStateOnline = 1, // friend is logged on k_EPersonaStateBusy = 2, // user is on, but busy k_EPersonaStateAway = 3, // auto-away feature k_EPersonaStateSnooze = 4, // auto-away for a long time k_EPersonaStateMax, }; //----------------------------------------------------------------------------- // Purpose: flags for enumerating friends list, or quickly checking a the relationship between users //----------------------------------------------------------------------------- enum EFriendFlags { k_EFriendFlagNone = 0x00, k_EFriendFlagBlocked = 0x01, k_EFriendFlagFriendshipRequested = 0x02, k_EFriendFlagImmediate = 0x04, // "regular" friend k_EFriendFlagClanMember = 0x08, k_EFriendFlagOnGameServer = 0x10, // k_EFriendFlagHasPlayedWith = 0x20, // not currently used // k_EFriendFlagFriendOfFriend = 0x40, // not currently used k_EFriendFlagRequestingFriendship = 0x80, k_EFriendFlagRequestingInfo = 0x100, k_EFriendFlagIgnored = 0x200, k_EFriendFlagIgnoredFriend = 0x400, k_EFriendFlagAll = 0xFFFF, }; //----------------------------------------------------------------------------- // Purpose: avatar sizes, used in ISteamFriends::GetFriendAvatar() //----------------------------------------------------------------------------- enum EAvatarSize { k_EAvatarSize32x32 = 0, k_EAvatarSize64x64 = 1, }; // friend game played information struct FriendGameInfo_t { CGameID m_gameID; uint32 m_unGameIP; uint16 m_usGamePort; uint16 m_usQueryPort; CSteamID m_steamIDLobby; }; // maximum number of characters in a user's name. Two flavors; one for UTF-8 and one for UTF-16. // The UTF-8 version has to be very generous to accomodate characters that get large when encoded // in UTF-8. enum { k_cchPersonaNameMax = 128, k_cwchPersonaNameMax = 32, }; // size limit on chat room or member metadata const uint32 k_cubChatMetadataMax = 8192; //----------------------------------------------------------------------------- // Purpose: interface to accessing information about individual users, // that can be a friend, in a group, on a game server or in a lobby with the local user //----------------------------------------------------------------------------- class ISteamFriends { public: // returns the local players name - guaranteed to not be NULL. // this is the same name as on the users community profile page // this is stored in UTF-8 format // like all the other interface functions that return a char *, it's important that this pointer is not saved // off; it will eventually be free'd or re-allocated virtual const char *GetPersonaName() = 0; // sets the player name, stores it on the server and publishes the changes to all friends who are online virtual void SetPersonaName( const char *pchPersonaName ) = 0; // gets the status of the current user virtual EPersonaState GetPersonaState() = 0; // friend iteration // takes a set of k_EFriendFlags, and returns the number of users the client knows about who meet that criteria // then GetFriendByIndex() can then be used to return the id's of each of those users virtual int GetFriendCount( int iFriendFlags ) = 0; // returns the steamID of a user // iFriend is a index of range [0, GetFriendCount()) // iFriendsFlags must be the same value as used in GetFriendCount() // the returned CSteamID can then be used by all the functions below to access details about the user virtual CSteamID GetFriendByIndex( int iFriend, int iFriendFlags ) = 0; // returns a relationship to a user virtual EFriendRelationship GetFriendRelationship( CSteamID steamIDFriend ) = 0; // returns the current status of the specified user // this will only be known by the local user if steamIDFriend is in their friends list; on the same game server; in a chat room or lobby; or in a small group with the local user virtual EPersonaState GetFriendPersonaState( CSteamID steamIDFriend ) = 0; // returns the name another user - guaranteed to not be NULL. // same rules as GetFriendPersonaState() apply as to whether or not the user knowns the name of the other user // note that on first joining a lobby, chat room or game server the local user will not known the name of the other users automatically; that information will arrive asyncronously // virtual const char *GetFriendPersonaName( CSteamID steamIDFriend ) = 0; // gets the avatar of the current user, which is a handle to be used in IClientUtils::GetImageRGBA(), or 0 if none set virtual int GetFriendAvatar( CSteamID steamIDFriend, int eAvatarSize ) = 0; // returns true if the friend is actually in a game, and fills in pFriendGameInfo with an extra details virtual bool GetFriendGamePlayed( CSteamID steamIDFriend, FriendGameInfo_t *pFriendGameInfo ) = 0; // accesses old friends names - returns an empty string when their are no more items in the history virtual const char *GetFriendPersonaNameHistory( CSteamID steamIDFriend, int iPersonaName ) = 0; // returns true if the specified user meets any of the criteria specified in iFriendFlags // iFriendFlags can be the union (binary or, |) of one or more k_EFriendFlags values virtual bool HasFriend( CSteamID steamIDFriend, int iFriendFlags ) = 0; // clan (group) iteration and access functions virtual int GetClanCount() = 0; virtual CSteamID GetClanByIndex( int iClan ) = 0; virtual const char *GetClanName( CSteamID steamIDClan ) = 0; // iterators for getting users in a chat room, lobby, game server or clan // note that large clans that cannot be iterated by the local user // steamIDSource can be the steamID of a group, game server, lobby or chat room virtual int GetFriendCountFromSource( CSteamID steamIDSource ) = 0; virtual CSteamID GetFriendFromSourceByIndex( CSteamID steamIDSource, int iFriend ) = 0; // returns true if the local user can see that steamIDUser is a member or in steamIDSource virtual bool IsUserInSource( CSteamID steamIDUser, CSteamID steamIDSource ) = 0; // User is in a game pressing the talk button (will suppress the microphone for all voice comms from the Steam friends UI) virtual void SetInGameVoiceSpeaking( CSteamID steamIDUser, bool bSpeaking ) = 0; // activates the game overlay, with an optional dialog to open // valid options are "Friends", "Community", "Players", "Settings", "LobbyInvite", "OfficialGameGroup", "Stats", "Achievements" virtual void ActivateGameOverlay( const char *pchDialog ) = 0; // activates game overlay to a specific place // valid options are // "steamid" - opens the overlay web browser to the specified user or groups profile // "chat" - opens a chat window to the specified user, or joins the group chat virtual void ActivateGameOverlayToUser( const char *pchDialog, CSteamID steamID ) = 0; // activates game overlay web browser directly to the specified URL // full address with protocol type is required, e.g. http://www.steamgames.com/ virtual void ActivateGameOverlayToWebPage( const char *pchURL ) = 0; // activates game overlay to store page for app virtual void ActivateGameOverlayToStore( AppId_t nAppID ) = 0; }; #define STEAMFRIENDS_INTERFACE_VERSION "SteamFriends005" //----------------------------------------------------------------------------- // Purpose: called when a friends' status changes //----------------------------------------------------------------------------- struct PersonaStateChange_t { enum { k_iCallback = k_iSteamFriendsCallbacks + 4 }; uint64 m_ulSteamID; // steamID of the friend who changed int m_nChangeFlags; // what's changed }; // used in PersonaStateChange_t::m_nChangeFlags to describe what's changed about a user // these flags describe what the client has learned has changed recently, so on startup you'll see a name, avatar & relationship change for every friend enum EPersonaChange { k_EPersonaChangeName = 0x001, k_EPersonaChangeStatus = 0x002, k_EPersonaChangeComeOnline = 0x004, k_EPersonaChangeGoneOffline = 0x008, k_EPersonaChangeGamePlayed = 0x010, k_EPersonaChangeGameServer = 0x020, k_EPersonaChangeAvatar = 0x040, k_EPersonaChangeJoinedSource= 0x080, k_EPersonaChangeLeftSource = 0x100, k_EPersonaChangeRelationshipChanged = 0x200, k_EPersonaChangeNameFirstSet = 0x400, }; //----------------------------------------------------------------------------- // Purpose: posted when game overlay activates or deactivates // the game can use this to be pause or resume single player games //----------------------------------------------------------------------------- struct GameOverlayActivated_t { enum { k_iCallback = k_iSteamFriendsCallbacks + 31 }; uint8 m_bActive; // true if it's just been activated, false otherwise }; //----------------------------------------------------------------------------- // Purpose: called when the user tries to join a different game server from their friends list // game client should attempt to connect to specified server when this is received //----------------------------------------------------------------------------- struct GameServerChangeRequested_t { enum { k_iCallback = k_iSteamFriendsCallbacks + 32 }; char m_rgchServer[64]; // server address ("127.0.0.1:27015", "tf2.valvesoftware.com") char m_rgchPassword[64]; // server password, if any }; //----------------------------------------------------------------------------- // Purpose: called when the user tries to join a lobby from their friends list // game client should attempt to connect to specified lobby when this is received //----------------------------------------------------------------------------- struct GameLobbyJoinRequested_t { enum { k_iCallback = k_iSteamFriendsCallbacks + 33 }; CSteamID m_steamIDLobby; CSteamID m_steamIDFriend; // the friend they did the join via (will be invalid if not directly via a friend) }; #endif // ISTEAMFRIENDS_H