presence

package
v2.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 9, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DepthUser is a presence depth that returns only the user node.
	DepthUser = "user"
	// DepthDevice is a presence depth that returns the user and device nodes.
	DepthDevice = "device"
	// DepthTitle is a presence depth that returns the whole tree except activity.
	// This is the default depth.
	DepthTitle = "title"
	// DepthAll is a presence depth that returns the whole tree, including rich
	// presence and media.
	DepthAll = "all"
)
View Source 
const (
	// StateActive indicates that the user is active in the title.
	StateActive = "active"
	// StateInactive indicates that the user is no longer active in the title.
	StateInactive = "inactive"
)
View Source 
const (
	// PlacementFull indicates that the title is using the full screen.
	PlacementFull = "full"
	// PlacementSnapped indicates that the title is snapped alongside another
	// application. Snap was a feature introduced on Xbox One that allowed
	// multiple titles to be displayed on screen simultaneously. It has since
	// been removed due to performance concerns, so this value is unlikely to
	// be seen. The following YouTube videos published by Xbox in 2013 demonstrates
	// how this feature worked:
	//   - https://youtu.be/Yxb3k9rptcM
	//   - https://youtu.be/pEoZbXB78NI?t=14
	PlacementSnapped = "snapped"
	// PlacementFill indicates that the title is occupying the non-snapped
	// portion of the screen while another application is snapped alongside it.
	PlacementFill = "fill"
	// PlacementBackground indicates that the title is running in the background.
	PlacementBackground = "background"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Activity 

type Activity struct {
	// RichPresence is the localized rich presence string for the title.
	// It is only populated for titles that support rich presence. The language
	// is determined by the "Accept-Language" header set by the caller.
	// See [github.com/df-mc/go-xsapi.AcceptLanguage].
	RichPresence string `json:"richPresence"`
	// Media describes the media the user is currently playing. It is only
	// populated for titles that report media activity, such as Spotify.
	Media *Media `json:"media"`
}

Activity holds detailed presence information for a title, such as a rich presence string or the media the user is currently playing.

See: https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/live/rest/json/json-activityrecord

type ActivityRequest 

type ActivityRequest struct {
	// RichPresence sets the rich presence string for the title. Only titles
	// that support rich presence should specify this field.
	RichPresence *RichPresenceRequest `json:"richPresence,omitempty"`
	// Media sets the media the user is currently playing. Only titles that
	// support media presence should specify this field.
	Media *MediaRequest `json:"media,omitempty"`
}

ActivityRequest describes the on-wire structure used to set in-title presence details such as rich presence and media information.

type BatchRequest 

type BatchRequest struct {
	// XUIDs lists the XUIDs of the users to query. Up to 1100 XUIDs may be
	// specified at a time.
	XUIDs []string `json:"users,omitempty"`
	// DeviceTypes filters results to users active on the given device types.
	// If empty, all device types are included.
	DeviceTypes []string `json:"deviceTypes,omitempty"`
	// TitleIDs filters results to the given titles.
	// If empty, all titles are included.
	TitleIDs []string `json:"titles,omitempty"`
	// Depth controls the depth of presence data returned.
	// Possible values are defined in this package with Depth* prefix.
	// Defaults to [DepthTitle] if empty.
	Depth string `json:"level,omitempty"`
	// OnlineOnly, if true, excludes offline and cloaked users from the results.
	OnlineOnly bool `json:"onlineOnly,omitempty"`
}

BatchRequest describes the on-wire format for a batch presence query.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client implements API client for Xbox Live Presence API.

func New 

func New(client *http.Client, userInfo xsts.UserInfo) *Client

New returns a new Client with the provided components.

func (*Client) Batch 

func (c *Client) Batch(ctx context.Context, request BatchRequest, opts ...internal.RequestOption) (presences []*Presence, err error)

Batch returns presences for all users matching the filters in the request.

func (*Client) Close 

func (c *Client) Close() error

Close closes the Client with a context of 15 seconds timeout. It removes any presences if there was any active.

In most cases, github.com/df-mc/go-xsapi.Client.Close should be preferred over calling this method directly.

func (*Client) CloseContext 

func (c *Client) CloseContext(ctx context.Context) error

CloseContext closes the Client using the given context. It removes the authenticated user's current title presence immediately by calling Client.Remove, instead of waiting for the presence record to expire on the server.

This method is intended for title shutdown. Callers that want to keep the current presence active should not call CloseContext.

In most cases, github.com/df-mc/go-xsapi.Client.CloseContext should be preferred over calling this method directly.

func (*Client) Current 

func (c *Client) Current(ctx context.Context, opts ...internal.RequestOption) (*Presence, error)

Current returns the caller's current presence. Unlike [PresenceByXUID], this method does not require the caller to know their own XUID.

func (*Client) PresenceByXUID 

func (c *Client) PresenceByXUID(ctx context.Context, xuid string, opts ...internal.RequestOption) (*Presence, error)

PresenceByXUID returns the presence of the user identified by the given XUID.

func (*Client) Remove 

func (c *Client) Remove(ctx context.Context, opts ...internal.RequestOption) error

Remove removes the presence of the authenticated user's current title immediately, rather than waiting for it to expire on the server. It is safe to call this method even if the user doesn't have any active presence.

func (*Client) Update 

func (c *Client) Update(ctx context.Context, request TitleRequest, opts ...internal.RequestOption) error

Update updates the presence of the authenticated user's current title.

type Device 

type Device struct {
	// Type is the device type. Known values are "D" (Xbox One/Series),
	// "Xbox360", "MoLIVE" (Windows), "WindowsPhone", "WindowsPhone7",
	// "PC" (Games for Windows Live), and "Web" (iOS, Android, or browser).
	Type string `json:"type"`
	// Titles lists the titles currently active on this device.
	Titles []Title `json:"titles"`
}

Device holds the presence of a user on a single device. A user may be active in multiple titles on the same device simultaneously.

See: https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/live/rest/json/json-devicerecord

type LastSeen 

type LastSeen struct {
	// DeviceType is the type of device the user was last seen on.
	// It holds the same set of values as [Device.Type].
	DeviceType string `json:"deviceType"`
	// TitleID is the ID of the last title the user was seen playing.
	TitleID uint32 `json:"titleId"`
	// TitleName is the localized display name of the title. The language
	// is determined by the "Accept-Language" header set by the caller.
	// See [github.com/df-mc/go-xsapi.AcceptLanguage].
	TitleName string `json:"titleName"`
	// Timestamp is when the user was last seen in the title.
	Timestamp time.Time `json:"timestamp"`
}

LastSeen describes the last title a user was seen playing.

See: https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/live/rest/json/json-lastseenrecord

type Media 

type Media struct {
	// ID is the identifier for this media.
	// The format and semantics of this field depends on IDType.
	ID string `json:"id"`
	// IDType indicates how the ID field should be interpreted.
	// Possible values include "bing" and "provider".
	IDType string `json:"idType"`
	// Name is the localized, user-facing name of the media item. The language
	// of this text depends on the "Accept-Language" header set by the caller.
	// See [github.com/df-mc/go-xsapi.AcceptLanguage].
	Name string `json:"name"`
}

Media describes a media item a user is currently playing.

See: https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/live/rest/json/json-mediarecord

type MediaRequest 

type MediaRequest struct {
	// ID identifies the media. The format and semantics of this field
	// depends on IDType.
	ID string `json:"id"`
	// IDType indicates how ID should be interpreted.
	// Known values are "bing" and "provider".
	IDType string `json:"idType"`
}

MediaRequest describes the on-wire structure used to set the user's currently-playing media.

type Presence 

type Presence struct {
	// XUID is the Xbox User ID (XUID) of the user.
	XUID string `json:"xuid"`
	// Devices lists the devices the user is currently active on.
	Devices []Device `json:"devices"`
	// State is the user's current activity on Xbox Live.
	// Not to be confused with [TitleRequest.State].
	//
	// Possible values are:
	//   - "Online": the user has at least one active device record.
	//   - "Away": the user is signed in but not active in any title.
	//   - "Offline": the user is not present on any device.
	State string `json:"state"`
	// LastSeen describes the last title the user was seen playing. It may be
	// nil if the record has been evicted from the Xbox Live cache.
	LastSeen *LastSeen `json:"lastSeen"`
}

Presence holds the online presence of a single user, including the devices they are currently active on and the titles they are playing.

See: https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/live/rest/json/json-presencerecord

type RichPresenceRequest 

type RichPresenceRequest struct {
	// ID is the friendly name of the rich presence string to use, as defined
	// in the title's service configuration. For example: "Creative",
	// "Survival", "Adventure".
	ID string `json:"id"`
	// ServiceConfigID is the SCID of the service configuration where the
	// rich presence strings are defined.
	ServiceConfigID uuid.UUID `json:"scid"`
	// Params is a list of friendly name strings used to complete the rich
	// presence string. Very few titles make use of this field, so its exact
	// behavior in practice is not well-documented.
	Params []string `json:"params,omitempty"`
}

RichPresenceRequest describes the rich presence to set for a title. For example, a Minecraft title may use this to reflect the game mode the user is currently playing.

type Title 

type Title struct {
	// ID is the Title ID.
	ID uint32 `json:"id"`
	// Name is the localized, user-facing name of the title.
	// The language is determined by the "Accept-Language" header
	// set by the caller.
	// See [github.com/df-mc/go-xsapi.AcceptLanguage].
	Name string `json:"name"`
	// Activity holds detailed information about what the user is doing in
	// this title, such as their rich presence string or currently playing media.
	Activity Activity `json:"activity"`
}

Title represents a title a user is currently active in on a Device.

See: https://learn.microsoft.com/en-us/gaming/gdk/docs/reference/live/rest/json/json-titlerecord

type TitleRequest 

type TitleRequest struct {
	// ID is the Title ID to associate with the presence. If zero, the
	// currently-authenticated title's ID is used.
	// It is unknown if the caller can specify a title ID other than the
	// currently-authenticated one.
	ID uint32 `json:"id,omitempty"`
	// Activity holds in-title details such as rich presence and media
	// information. Only titles that support these features should specify
	// this field.
	Activity *ActivityRequest `json:"activity,omitempty"`
	// State indicates whether the user is active in the title.
	// Possible values are [StateActive] and [StateInactive].
	// Defaults to [StateActive] if empty. This field is case-insensitive.
	State string `json:"state,omitempty"`
	// Placement describes how the title is displayed on screen.
	// Valid values are the Placement* constants defined in this package.
	// Defaults to [PlacementFull] if empty.
	Placement string `json:"placement,omitempty"`
}

TitleRequest describes the on-wire structure used to update a title's presence for the user.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.