Circuitry API - (circuitry_api.h)

This API provides the foundation to initialize and access the Circuitry API. All of the types listed here are 'global' defines and not associated with any one specific API.

Functions

These are global functions which do not require an interface to set up. You can read more about these functions in the Circuitry API Overview.

CircuitryAPI_Init

S_API bool S_CALLTYPE CircuitryAPI_Init();

Initializes the Circuitry API.

See Initialization and Shutdown for additional information.

Returns: bool
true indicates that all the required interfaces have been acquired and are accessible.
false indicates one of the following conditions:
The Circuitry client isn't running. A running Circuitry client is required to provide various implementations of the various Circuitry interfaces.
The Circuitry client could not determine the App ID of an application. If running the application from the executable or debugger directly then you need to have a circuitry_appid.txt in your application directory in the same directory as the executable, with your app ID included and nothing else. Circuitry will look for this file in the current working directory. If you are running your executable from a different directory you may need to relocate the circuitry_appid.txt file.
Your application is not running under the same operating system user context as the Circuitry client, such as a different user or administration access level.
Please ensure that you have the proper rights for the App ID on the currently active Robot Cache account. The application must show up in your Robot Cache Circuitry library.
* Your App ID is not completely set up, or missing default packages.

Example:

int main() { if ( CircuitryAPI_RestartAppIfNecessary( k_uAppIdInvalid ) ) // Replace with your App ID { return 1; } if ( !CircuitryAPI_Init() ) { printf( "Fatal Error - Circuitry must be running to play this application (CircuitryAPI_Init() failed).n" ); return 1; } return 0; }

CircuitryAPI_ReleaseCurrentThreadMemory

S_API void S_CALLTYPE CircuitryAPI_ReleaseCurrentThreadMemory();

Free's up the internal Circuitry API memory that's associated with the calling thread.

Most Circuitry API functions allocate thread-local memory for storing parameters. Calling this function will manually free the memory. This function is automatically called by the CircuitryAPI_RunCallbacks function, so any program that ever accesses the Circuitry API from a single thread never needs to explicitly call this function.

CircuitryAPI_RestartAppIfNecessary

S_API bool S_CALLTYPE CircuitryAPI_RestartAppIfNecessary( uint32 unOwnAppID );

Name	Type	Description
unOwnAppID	uint32	The App ID of this title.

This function checks to see if your executable file was launched through Circuitry and relaunches it through Circuitry if it wasn't.

See Initialization and Shutdown for additional information.

Returns: bool
If this returns true then it starts the client if required and launches the applocation again through the client. You should quit your process immediately. This effectively runs circuitry://run/ so it may not relaunch the same executable that called it, as it will always relaunch from the version installed in your Circuitry library folder.

If it returns false, then your application was launched by the Circuitry client and no action needs to be taken. An exception is if a circuitry_appid.txt file exists then this will return false regardless. This allows you to develop and test your application without launching your game through the Circuitry client. Make sure to remove the circuitry_appid.txt file when uploading the game to your Circuitry depot!

Example:

int main() { if ( CircuitryAPI_RestartAppIfNecessary( k_uAppIdInvalid ) ) // Replace with your App ID { return 1; } if ( !CircuitryAPI_Init() ) { printf( "Fatal Error - Circuitry must be running to play this game (CircuitryAPI_Init() failed).n" ); return 1; } return 0; }

CircuitryAPI_RunCallbacks

S_API void S_CALLTYPE CircuitryAPI_RunCallbacks();

This function call initiates callbacks and results for all registered listeners.

The more time between callin this function the more potential there may be for latency. Most applications call this function once per frame. All registered listener functions will be invoked during this call.

CircuitryAPI_RunCallbacks are safe to call from multiple threads simultaneously, however the code may be executed on any thread.

CircuitryAPI_SetMiniDumpComment

S_API void S_CALLTYPE CircuitryAPI_SetMiniDumpComment( const char *pchMsg );

Name	Type	Description
pchMsg	const char *	The message to attach to the minidump. This must be null terminated.

Attaches an arbitrary comment in the minidump.

A few examples include; the level of the player, many users etc.
This function must be called before calling the CircuitryAPI_WriteMiniDump function.

CircuitryAPI_Shutdown

S_API void S_CALLTYPE CircuitryAPI_Shutdown();

Shuts down the Circuitry API, releases pointers and frees up memory.

You should call this while running ther shutdown process.

CircuitryAPI_WriteMiniDump

S_API void S_CALLTYPE CircuitryAPI_WriteMiniDump( uint32 uStructuredExceptionCode, void* pvExceptionInfo, uint32 uBuildID );

Name	Type	Description
uStructuredExceptionCode	uint32	This is the structured exception code.
pvExceptionInfo	void*	This are the exception pointers that contain the the exception.
uBuildID	uint32	A ID to track the version of the application. NOTE: Not the same as a Circuitry build ID and is used only for reporting crashes.

Writes and uploads a dump of the data to report crashes.

See Circuitry Error Reporting for more information.

Structures

These are structures which function the circuitry_api may return and/or interact with.

CGameID

The globally unique identifier for Robot Cache applications.

CCircuitryID

The globally unique identifier for all Robot Cache accounts, groups, Lobbies and Chat rooms.

See EAccountType and EUniverse.

Enumerators

These are enumerators which are defined for use with the circuitry_api.

EChatEntryType

Chat Entry Types.

Returned by ICircuitryFriends::GetFriendMessage, ICircuitryFriends::GetClanChatMessage and ICircuitryMatchmaking::GetLobbyChatEntry.

Name	Value	Description
k_EChatEntryTypeInvalid	0	Invalid.
k_EChatEntryTypeChatMsg	1	Text message from another user.
k_EChatEntryTypeTyping	2	The other user is typing. Not used in multi-user chat.
k_EChatEntryTypeInviteGame	3	An invite from another user into that users current application.
k_EChatEntryTypeLeftConversation	6	A user has left the conversation.
k_EChatEntryTypeEntered	7	A user has entered the conversation. Used in the multi-user and group chat.
k_EChatEntryTypeWasKicked	8	User was kicked off (Data: Circuitry ID of the user performing the kick).
k_EChatEntryTypeWasBanned	9	User was banned (Data: Circuitry ID of the user performing the ban).
k_EChatEntryTypeDisconnected	10	User has been disconnected.
k_EChatEntryTypeHistoricalChat	11	A message from the user's chat history or offline message.
k_EChatEntryTypeLinkBlocked	14	A link was removed by the chat filter.

EChatRoomEnterResponse

Chat Room Enter Responses.

Name	Value	Description
k_EChatRoomEnterResponseSuccess	1	Success.
k_EChatRoomEnterResponseDoesntExist	2	Chat doesn't exist (may be closed).
k_EChatRoomEnterResponseNotAllowed	3	General denied as the user doesn't have the permissions needed to join the chat.
k_EChatRoomEnterResponseFull	4	The chat room has reached its allowed size.
k_EChatRoomEnterResponseError	5	Unexpected Error.
k_EChatRoomEnterResponseBanned	6	User is banned from this chat room and may not join.
k_EChatRoomEnterResponseLimited	7	Joining this chat is not allowed because the user is limited.
k_EChatRoomEnterResponseClanDisabled	8	Attempt to join a clan chat when the clan is locked or disabled.
k_EChatRoomEnterResponseMemberBlockedYou	10	Joining failed - a user that is in the chat has blocked another user from joining.
k_EChatRoomEnterResponseYouBlockedMember	11	Joining failed - a user has blocked a user that is already in the chat.

EChatCircuitryIDInstanceFlags

These are special flags for Chat accounts. They go in the top 8 bits of the Circuitry ID's "instance", leaving 12 for the actual instances

Name	Value	Description
k_EChatAccountInstanceMask	0x00000FFF	Top 8 bits are flags.
k_EChatInstanceFlagClan	( k_unCircuitryAccountInstanceMask + 1 ) >> 1	The Circuitry ID is for a Circuitry group.
k_EChatInstanceFlagLobby	( k_unCircuitryAccountInstanceMask + 1 ) >> 2	The Circuitry ID is for a Lobby.
k_EChatInstanceFlagMMSLobby	( k_unCircuitryAccountInstanceMask + 1 ) >> 3	The Circuitry ID is for an MMS Lobby.

EDenyReason

These are the result values when a client failed to join or has been kicked from a server. Obtained from GSClientDeny_t and GSClientKick_t.

Name	Value	Description
k_EDenyInvalid	0	Unknown.
k_EDenyInvalidVersion	1	The client and server are not the same version.
k_EDenyGeneric	2	Generic.
k_EDenyNotLoggedOn	3	The client is not logged on.
k_EDenyNoLicense	4	The client does not have the rights to run this application.
k_EDenyCheater	5	The client is banned.
k_EDenyLoggedInElseWhere	6	The client is logged in somewhere else.
k_EDenyUnknownText	7
k_EDenyIncompatibleAnticheat	8
k_EDenyMemoryCorruption	9
k_EDenyIncompatibleSoftware	10
k_EDenyCircuitryConnectionLost	11	The server has lost connection to Robot Cache servers.
k_EDenyCircuitryConnectionError	12	The server had a general error connecting to Robot Cache servers.
k_EDenyCircuitryResponseTimedOut	13	The server timed out connecting to Robot Cache servers.
k_EDenyCircuitryValidationStalled	14	The client has not authenticated with the Robot Cache servers.
k_EDenyCircuitryOwnerLeftGuestUser	15	The owner of the shared application has left and has called for each guest of the owner.

EGameIDType

Used to describe the type of CGameID.

Name	Value	Description
k_EGameIDTypeApp	0	The Game ID is a regular Robot Cache app.
k_EGameIDTypeGameMod	1	The Game ID is a mod.
k_EGameIDTypeShortcut	2	The game ID is a shortcut.
k_EGameIDTypeP2P	3	The game ID is a P2P (peer-to-peer) file.

EResult

Circuitry error result codes.

These are frequently returned by functions, callbacks, and call results from both the Circuitry API and the Web API. An API may return arbitrary EResult codes, refer to the documentation for that API function or callback to see what it could return and what they mean in the context of that API call.
This is similar to Win32's HRESULT type or POSIXs errno.

Name	Value	Description
k_EResultOK	1	Success.
k_EResultFail	2	Generic failure.
k_EResultNoConnection	3	Your Circuitry client doesn't have a connection to the back-end.
k_EResultInvalidPassword	5	Password/ticket is invalid.
k_EResultLoggedInElsewhere	6	The user is logged in elsewhere.
k_EResultInvalidProtocolVer	7	Protocol version is incorrect.
k_EResultInvalidParam	8	A parameter is incorrect.
k_EResultFileNotFound	9	File was not found.
k_EResultBusy	10	Called method is busy - action not taken.
k_EResultInvalidState	11	Called object was in an invalid state.
k_EResultInvalidName	12	The name was invalid.
k_EResultInvalidEmail	13	The email was invalid.
k_EResultDuplicateName	14	The name is not unique.
k_EResultAccessDenied	15	Access is denied.
k_EResultTimeout	16	Operation timed out.
k_EResultBanned	17	The user is VAC2 banned.
k_EResultAccountNotFound	18	Account not found.
k_EResultInvalidCircuitryID	19	The Circuitry ID was invalid.
k_EResultServiceUnavailable	20	The requested service is currently unavailable.
k_EResultNotLoggedOn	21	The user is not logged on.
k_EResultPending	22	Request is pending, it may be in process or waiting on third party.
k_EResultEncryptionFailure	23	Encryption or Decryption failed.
k_EResultInsufficientPrivilege	24	Insufficient privilege.
k_EResultLimitExceeded	25	Too much of a good thing.
k_EResultRevoked	26	Access has been revoked (used for revoked guest passes.)
k_EResultExpired	27	License/Guest pass the user is trying to access is expired.
k_EResultAlreadyRedeemed	28	Guest pass has already been redeemed by account, cannot be used again.
k_EResultDuplicateRequest	29	The request is a duplicate and the action has already occurred in the past, ignored this time.
k_EResultAlreadyOwned	30	All the games in this guest pass redemption request are already owned by the user.
k_EResultIPNotFound	31	IP address not found.
k_EResultPersistFailed	32	Failed to write change to the data store.
k_EResultLockingFailed	33	Failed to acquire access lock for this operation.
k_EResultLogonSessionReplaced	34	The logon session has been replaced.
k_EResultConnectFailed	35	Failed to connect.
k_EResultHandshakeFailed	36	The authentication handshake has failed.
k_EResultIOFailure	37	There has been a generic IO failure.
k_EResultRemoteDisconnect	38	The remote server has disconnected.
k_EResultShoppingCartNotFound	39	Failed to find the shopping cart requested.
k_EResultBlocked	40	A user blocked the action.
k_EResultIgnored	41	The target is ignoring sender.
k_EResultNoMatch	42	Nothing matching the request found.
k_EResultAccountDisabled	43	The account is disabled.
k_EResultServiceReadOnly	44	This service is not accepting content changes right now.
k_EResultAccountNotFeatured	45	Account doesn't have value, so this feature isn't available.
k_EResultAdministratorOK	46	Allowed to take this action, but only because requester is admin.
k_EResultContentVersion	47	A Version mismatch in content transmitted within the Circuitry protocol.
k_EResultTryAnotherCM	48	The current CM can't service the user making a request, user should try another.
k_EResultPasswordRequiredToKickSession	49	You are already logged in elsewhere, this cached credential login has failed.
k_EResultAlreadyLoggedInElsewhere	50	The user is logged in elsewhere. (Use k_EResultLoggedInElsewhere instead!)
k_EResultSuspended	51	Long running operation has suspended/paused. (eg. content download.)
k_EResultCancelled	52	Operation has been canceled, typically by user. (eg. a content download.)
k_EResultDataCorruption	53	Operation canceled because data is ill formed or unrecoverable.
k_EResultDiskFull	54	Operation canceled - not enough disk space.
k_EResultRemoteCallFailed	55	The remote or IPC call has failed.
k_EResultPasswordUnset	56	Password could not be verified as it's unset server side.
k_EResultExternalAccountUnlinked	57	External account (PSN, Facebook...) is not linked to a Circuitry account.
k_EResultPSNTicketInvalid	58	PSN ticket was invalid.
k_EResultExternalAccountAlreadyLinked	59	External account (PSN, Facebook...) is already linked to some other account, must explicitly request to replace/delete the link first.
k_EResultRemoteFileConflict	60	The sync cannot resume due to a conflict between the local and remote files.
k_EResultIllegalPassword	61	The requested new password is not allowed.
k_EResultSameAsPreviousValue	62	New value is the same as the old one. This is used for secret question and answer.
k_EResultAccountLogonDenied	63	Account login denied due to 2nd factor authentication failure.
k_EResultCannotUseOldPassword	64	The requested new password is not legal.
k_EResultInvalidLoginAuthCode	65	Account login denied due to auth code invalid.
k_EResultAccountLogonDeniedNoMail	66	Account login denied due to 2nd factor auth failure - and no mail has been sent.
k_EResultHardwareNotCapableOfIPT	67	The users hardware does not support Intel's Identity Protection Technology (IPT).
k_EResultIPTInitError	68	Intel's Identity Protection Technology (IPT) has failed to initialize.
k_EResultParentalControlRestricted	69	Operation failed due to parental control restrictions for current user.
k_EResultFacebookQueryError	70	Facebook query returned an error.
k_EResultExpiredLoginAuthCode	71	Account login denied due to an expired auth code.
k_EResultIPLoginRestrictionFailed	72	The login failed due to an IP restriction.
k_EResultAccountLockedDown	73	The current users account is currently locked for use. This is likely due to a hijacking and pending ownership verification.
k_EResultAccountLogonDeniedVerifiedEmailRequired	74	The logon failed because the accounts email is not verified.
k_EResultNoMatchingURL	75	There is no URL matching the provided values.
k_EResultBadResponse	76	Bad Response due to a Parse failure, missing field, etc.
k_EResultRequirePasswordReEntry	77	The user cannot complete the action until they re-enter their password.
k_EResultValueOutOfRange	78	The value entered is outside the acceptable range.
k_EResultUnexpectedError	79	Something happened that we didn't expect to ever happen.
k_EResultDisabled	80	The requested service has been configured to be unavailable.
k_EResultInvalidCEGSubmission	81	The files submitted to the CEG server are not valid.
k_EResultRestrictedDevice	82	The device being used is not allowed to perform this action.
k_EResultRegionLocked	83	The action could not be complete because it is region restricted.
k_EResultRateLimitExceeded	84	Temporary rate limit exceeded, try again later, different from k_EResultLimitExceeded which may be permanent.
k_EResultAccountLoginDeniedNeedTwoFactor	85	Need two-factor code to login.
k_EResultItemDeleted	86	The thing we're trying to access has been deleted.
k_EResultAccountLoginDeniedThrottle	87	Login attempt failed, try to throttle response to possible attacker.
k_EResultTwoFactorCodeMismatch	88	Two factor authentication (Circuitry Guard) code is incorrect.
k_EResultTwoFactorActivationCodeMismatch	89	The activation code for two-factor authentication (Circuitry Guard) didn't match.
k_EResultAccountAssociatedToMultiplePartners	90	The current account has been associated with multiple partners.
k_EResultNotModified	91	The data has not been modified.
k_EResultNoMobileDevice	92	The account does not have a mobile device associated with it.
k_EResultTimeNotSynced	93	The time presented is out of range or tolerance.
k_EResultSmsCodeFailed	94	SMS code failure - no match, none pending, etc.
k_EResultAccountLimitExceeded	95	Too many accounts access this resource.
k_EResultAccountActivityLimitExceeded	96	Too many changes to this account.
k_EResultPhoneActivityLimitExceeded	97	Too many changes to this phone.
k_EResultRefundToWallet	98	Cannot refund to payment method, must use wallet.
k_EResultEmailSendFailure	99	Cannot send an email.
k_EResultNotSettled	100	Can't perform operation until payment has settled.
k_EResultNeedCaptcha	101	The user needs to provide a valid captcha.
k_EResultGSLTDenied	102	A game server login token owned by this token's owner has been banned.
k_EResultGSOwnerDenied	103	Game server owner is denied for some other reason such as account locked, community ban, vac ban, missing phone, etc.
k_EResultInvalidItemType	104	The type of thing we were requested to act on is invalid.
k_EResultIPBanned	105	The IP address has been banned from taking this action.
k_EResultGSLTExpired	106	This Game Server Login Token (GSLT) has expired from disuse; it can be reset for use.
k_EResultInsufficientFunds	107	user doesn't have enough wallet funds to complete the action
k_EResultTooManyPending	108	There are too many of this thing pending already

ECircuitryUserStatType

Fields used internally to store user stats.

Name	Value	Description
k_ECircuitryUserStatTypeINVALID	0	Invalid.
k_ECircuitryUserStatTypeINT	1	32-bit int stat.
k_ECircuitryUserStatTypeFLOAT	2	32-bit float stat.
k_ECircuitryUserStatTypeAVGRATE	3	Read as FLOAT, set with count / session length.
k_ECircuitryUserStatTypeACHIEVEMENTS	4	Standard user achievement.
k_ECircuitryUserStatTypeGROUPACHIEVEMENTS	5	Deprecated.
k_ECircuitryUserStatTypeMAX	6	Total number of user stat types, used for sanity checks.

EUserHasLicenseForAppResult

Result of ICircuitryUser::UserHasLicenseForApp.

Name	Value	Description
k_EUserHasLicenseResultHasLicense	0	The user has a license for specified app.
k_EUserHasLicenseResultDoesNotHaveLicense	1	The user does not have a license for the specified app.
k_EUserHasLicenseResultNoAuth	2	The user has not been authenticated.

Typedefs

These are typedefs which are defined for use with circuitry_api.

Name	Base type	Description
AppId_t	uint32	This is a unique identifier for an application. For more information see the Applications documentation.
BREAKPAD_HANDLE	void *	Used by the internal Circuitry crash handling interfaces to reference particular installed crash handlers.
DepotId_t	uint32	A unique identifier for a depot.
HAuthTicket	uint32	This is a handle to a user authentication ticket. Return type of ICircuitryUser::GetAuthSessionTicket.
int16	short	Circuitry's version of a 16-bit integer, equivalent to int16_t.
int32	int	Circuitry's version of a 32-bit integer, equivalent to int32_t.
int64	long long	Circuitry's version of a 64-bit integer, equivalent to int64_t.
int8	signed char	Circuitry's version of a 8-bit integer, equivalent to int8_t.
intp	int/long long	Circuitry's version of a signed type that can hold a pointer, equivalent to intptr_t. (Only used internally in Circuitry.)
RTime32	uint32	Circuitry's version of Unix epoch time. It offers 1 second resolution starting from the epoch, 1970-01-01 00:00:00 +0000 (UTC)
CircuitryAPICall_t	uint64	This is a unique handle to a Circuitry API call. If a function returns one of these you will need to track the status by using the Call Result function.
uint16	unsigned short	Circuitry's version of a 16-bit unsigned integer, equivalent to uint16_t.
uint32	unsigned int	Circuitry's version of a 32-bit unsigned integer, equivalent to uint32_t.
uint64	unsigned long long	Circuitry's version of a 64-bit unsigned integer, equivalent to uint64_t.
uint8	unsigned char	Circuitry's version of a 8-bit unsigned integer, equivalent to uint8_t.
uintp	unsigned int/unsigned long long	Circuitry's version of an unsigned type that can hold a pointer, equivalent to uintptr_t. (Only used internally in Circuitry.)

Constants

These are constants which are defined for use with circuitry_api.

Name	Type	Value	Description
BREAKPAD_INVALID_HANDLE	int	(BREAKPAD_HANDLE)0
k_HAuthTicketInvalid	HAuthTicket	0	An invalid user authentication ticket.
k_circuitryIDLanModeGS	int	CCircuitryID(	This Circuitry ID comes from a user application connection.
k_circuitryIDNil	int	CCircuitryID()	Generic invalid CCircuitryID.
k_circuitryIDNonCircuitryGS	int	CCircuitryID(	This Circuitry ID comes from a user application connection to a GS that is not utilizing the authentication system but wants to support the "Join Game" option in the friends list
k_circuitryIDNotInitYetGS	int	CCircuitryID(	This Circuitry ID comes from a user application connection to a GS that has just booted but has not yet initialized its components and logged on.
k_circuitryIDOutofDateGS	int	CCircuitryID(	This comes from a user application connection to an out of date GS that hasnt implemented any such protocol to provide its Circuitry ID
k_uAPICallInvalid	CircuitryAPICall_t	0x0	An Invalid Circuitry API call handle.
k_uAppIdInvalid	AppId_t	0x0	An Invalid App ID.
k_uDepotIdInvalid	DepotId_t	0x0	An Invalid Depot ID.
k_unCircuitryAccountIDMask	unsigned int	0xFFFFFFFF	Used in CCircuitryID to mask out the AccountID_t.
k_unCircuitryAccountInstanceMask	unsigned int	0x000FFFFF	Used in CCircuitryID to mask out the account instance.
k_unCircuitryUserConsoleInstance	unsigned int	2	Used by CCircuitryID to identify users logged in from a console.
k_unCircuitryUserDesktopInstance	unsigned int	1	Used by CCircuitryID to identify users logged in from the client.
k_unCircuitryUserWebInstance	unsigned int	4	Used by CCircuitryID to identify users that are logged in from the internet.
QUERY_PORT_ERROR	int	0xFFFE	Unable to retriev the query port number for this server.
QUERY_PORT_NOT_INITIALIZED	int	0xFFFF