ICircuitryRemoteStorage Interface

The following functions below allow for reading, writing, and accessing files which can be stored remotely in the Circuitry Cloud.

Member Functions

Member functions for ICircuitryRemoteStorage are called through the global accessor function CircuitryRemoteStorage().

FileDelete

bool FileDelete( const char *pchFile );
Name Type Description
pchFile const char * The name of the file that will be deleted.

Deletes a file locally and propagates that deletion to the Circuitry Cloud.

This function is meant to be used when a user actively deletes a file. Use the FileForget function if you want to remove a file from the Circuitry Cloud but retain it on the users local disk.

When a file has been deleted it can be re-written with the FileWrite function to re-upload it to the Circuitry Cloud.

Returns: bool
true if the file exists and has been successfully deleted; otherwise, false if the file did not exist.

FileExists

bool FileExists( const char *pchFile );
Name Type Description
pchFile const char * The name of the file.

Checks whether or not the specified file exists.

Returns: bool
true if the file exists; otherwise, false.

FileForget

bool FileForget( const char *pchFile );
Name Type Description
pchFile const char * The name of the file that will be forgotten.

This deletes the file from the remote storage, but leaves it on the local disk and remains accessible from the API.

If there is no longer any cloud space available, this function allows calls to FileWrite and keep working without needing to make the user delete any files.

Once a file has been deleted or forgotten, calling the FileWrite function will resynchronize it in the cloud. Rewriting a forgotten file is the only way to make it persistant again.

Returns: bool
true if the file exists and has been successfully forgotten; otherwise, false.

FilePersisted

bool FilePersisted( const char *pchFile );
Name Type Description
pchFile const char * The name of the file.

Checks if a specific file is persisted in the Circuitry Cloud.

Returns: bool
true if the file exists and the file is persisted in the Circuitry Cloud.
false if FileForget was called on it and is only available locally.

FileRead

int32 FileRead( const char *pchFile, void *pvData, int32 cubDataToRead );
Name Type Description
pchFile const char * The name of the file to read from.
pvData void * The buffer that the file will be read into. This buffer must be at least the same size provided to cubDataToRead.
cubDataToRead int32 The amount of bytes to read. Generally obtained from GetFileSize or GetFileTimestamp.

Opens a binary file, reads the contents of the file into a byte array, and then closes the file.

NOTE: This is a synchronous call and as such is a will block your calling thread on the disk IO, and will also block the CircuitryAPI, which can cause other threads in your application to block. To avoid "hitching" due to a busy disk on the client machine using FileReadAsync, the asynchronous version of this API is recommended.

Returns: int32 The number of bytes read.

Returns 0 if the file doesn't exist or the read fails.

FileReadAsync

CircuitryAPICall_t FileReadAsync( const char *pchFile, uint32 nOffset, uint32 cubToRead );
Name Type Description
pchFile const char * The name of the file to read from.
nOffset uint32] The offset in bytes into the file where the read will start from. 0 if you're reading the whole file in one chunk.
cubToRead uint32] The amount of bytes to read starting from nOffset.

Starts an asynchronous read from a file.

The offset as well as the amount to read should be valid for the size of the file, as indicated by GetFileSize or GetFileTimestamp.

Returns: CircuitryAPICall_t to be used with a RemoteStorageFileReadAsyncComplete_t call result.

Returns k_uAPICallInvalid under the following conditions:

  • You attempted to read from an invalid path or filename. Because the Circuitry Cloud is cross platform, the files need to have valid names on all supported operating and file systems. For more information please review Microsoft's documentation on Naming Files, Paths, and Namespaces.
  • The file doesn't exist.
  • cubDataToRead is <= 0 bytes. You need to be able to read some data.
  • The combination of pvData and cubDataToRead would read past the end of the file.
  • You have an async read in progress on this file already.

Upon completion of the read request you will receive the call result. If the value of m_eResult within the call result is k_EResultOK then call FileReadAsyncComplete to read the requested data into your buffer. The hReadCall parameter should match the return value of this function, and the amount to read should generally be equal to the amount requested as indicated by m_nOffset and m_cubRead.

FileReadAsyncComplete

bool FileReadAsyncComplete( CircuitryAPICall_t hReadCall, void *pvBuffer, uint32 cubToRead );

This copies the bytes from a file which was asynchronously read with FileReadAsync into a byte array.

This should not be called outside of the context of a RemoteStorageFileReadAsyncComplete_t call result.

Returns: bool
true if the file was successfully read.

Otherwise, false under the following conditions:
The handle passed to hReadCall is invalid.
 The read failed as indicated by m_eResult in RemoteStorageFileReadAsyncComplete_t, you shouldn't have called this.
* The buffer provided to pvBuffer isn't big enough.

FileShare

CircuitryAPICall_t FileShare( const char *pchFile );
Name Type Description
pchFile const char *

Returns: CircuitryAPICall_t to be used with a RemoteStorageFileShareResult_t call result.

FileWrite

bool FileWrite( const char *pchFile, const void *pvData, int32 cubData );
Name Type Description
pchFile const char * The name of the file to write to.
pvData const void * The bytes to write to the file.
cubData int32 The number of bytes to write to the file. Typically the total size of pvData.

Creates a new file, writes the bytes to the file, and then closes the file. If the target file already exists it is overwritten.

NOTE: This is a synchronous call and will block your calling thread on the disk IO, and will also block the CircuitryAPI, which can cause other threads in your application to block. To avoid this "hitching" due to a busy disk on the client machine using FileWriteAsync, the asynchronous version of this API is recommended.

Returns: bool
true if the write was successful.

Otherwise, false under the following conditions:
The file you're trying to write is larger than 100MB as defined by k_unMaxCloudFileChunkSize.
 cubData is less than 0.
pvData is NULL.
 You tried to write to an invalid path or filename. Because Circuitry Cloud is cross platform the files need to have valid names on all supported operating and file systems. For more information please review Microsoft's documentation on Naming Files, Paths, and Namespaces.
The current user's Circuitry Cloud storage quota has been exceeded. There may not be enough space, or have too many files.
 Circuitry could not write to the disk, the location might be read-only.

FileWriteAsync

CircuitryAPICall_t FileWriteAsync( const char *pchFile, const void *pvData, uint32 cubData );
Name Type Description
pchFile const char * The name of the file to write to.
pvData const void * The bytes to write to the file.
cubData uint32 The number of bytes to write to the file. Typically the total size of pvData.

This creates a new file and asynchronously writes the raw byte data to the Circuitry Cloud, and then closes the file. If the target file already exists, it is overwritten.

Returns: CircuitryAPICall_t to be used with a RemoteStorageFileWriteAsyncComplete_t call result.
Returns k_uAPICallInvalid under the following conditions:

  • The file you're trying to write is larger than 100MB as defined by k_unMaxCloudFileChunkSize.
  • cubData is less than 0.
  • pvData is NULL.
  • You tried to write to an invalid path or filename. Because Circuitry Cloud is cross platform the files need to have valid names on all supported OSes and file systems. For more information please review Microsoft's documentation on Naming Files, Paths, and Namespaces.
  • The current user's Circuitry Cloud storage quota has been exceeded. They may have run out of space, or have too many files.

GetFileCount

int32 GetFileCount();

Gets the total number of local files synchronized by the Circuitry Cloud. Used for enumeration with GetFileNameAndSize.

Returns:int32 The number of files present for the current user, including files in subfolders.

GetFileNameAndSize

const char * GetFileNameAndSize( int iFile, int32 *pnFileSizeInBytes );
Name Type Description
iFile int The index of the file, this should be between 0 and GetFileCount.
pnFileSizeInBytes int32 * Returns the file size in bytes.

Gets the file name and size of a file from the index.

NOTE: You will need to call GetFileCount first to get the number of files.

Returns: const char *
The name of the file at the specified index if it exists. Returns an empty string ("") if the file doesn't exist.

Example: 

int32 fileCount = CircuitryRemoteStorage()->GetFileCount();
for ( int i = 0; i < fileCount; ++i ) {
    int32 fileSize;
    const char *fileName = CircuitryRemoteStorage()->GetFileNameAndSize( i, &fileSize );
    // Do something with fileSize and fileName
}

GetFileSize

int32 GetFileSize( const char *pchFile );
Name Type Description
pchFile const char * The name of the file.

Gets the specified files size in bytes.

Returns: int32 The size of the file in bytes. Returns0 if the file does not exist.

GetFileTimestamp

int64 GetFileTimestamp( const char *pchFile );
Name Type Description
pchFile const char * The name of the file.

Gets the specified file's last modified timestamp in Unix epoch format (seconds since Jan 1st 1970).

Returns: int64 The last modified timestamp in Unix epoch format (seconds since Jan 1st 1970).

GetQuota

bool GetQuota( uint64 *pnTotalBytes, uint64 *puAvailableBytes );
Name Type Description
pnTotalBytes uint64 * Returns the total amount of bytes the user has access to.
puAvailableBytes uint64 * Returns the number of bytes available.

Gets the number of bytes available, and used on the users Circuitry Cloud storage.

Returns: bool
This function always returns true.

GetSyncPlatforms

ERemoteStoragePlatform GetSyncPlatforms( const char *pchFile );
Name Type Description
pchFile const char * The name of the file.

Obtains the platforms that the specified file will syncronize to.

Returns: ERemoteStoragePlatform Bitfield containing the platforms that the file was set to with SetSyncPlatforms.

IsCloudEnabledForAccount

bool IsCloudEnabledForAccount();

Checks if the account wide Circuitry Cloud setting is enabled for this user; or if they disabled it. Please ensure that you are also checking IsCloudEnabledForApp, as these two options are mutually exclusive.

Returns: bool
true if Circuitry Cloud is enabled for this account; otherwise, false.

IsCloudEnabledForApp

bool IsCloudEnabledForApp();

Checks if the Circuitry Cloud (on a per game basis) setting is enabled for this user; or if they disabled it.

Ensure that you are also checking IsCloudEnabledForAccount as these two options are mutually exclusive.

Your users should be able to 'toggle' this setting within your in-game options (best practice). You can toggle it with SetCloudEnabledForApp.

Returns: bool
true if Circuitry Cloud is enabled for this app; otherwise, false.

SetCloudEnabledForApp

void SetCloudEnabledForApp( bool bEnabled );
Name Type Description
bEnabled bool Enable (true) or disable (false) the Circuitry Cloud for this application?

Toggles whether the Circuitry Cloud is enabled for your application.

This setting can be queried with IsCloudEnabledForApp.

NOTE: This function should only be used if the user requests it to be enabled.

Callbacks

These are callbacks which can be used by calling CircuitryAPI_RunCallbacks. Many of these will be called directly in response to other member functions of ICircuitryRemoteStorage.

RemoteStorageFileReadAsyncComplete_t

Response when reading a file asyncrounously with FileReadAsync.

Name Type Description
m_hFileReadAsync CircuitryAPICall_t Call handle of the async read which was made, must be passed to FileReadAsyncComplete to get the data.
m_eResult EResult The result of the operation. If the local read was successful this will be k_EResultOK, you can then call FileReadAsyncComplete to get the data.
m_nOffset uint32 Offset into the file this read was at.
m_cubRead uint32 Amount of bytes read - will be the <= the amount requested.

Associated Functions: FileReadAsync

RemoteStorageFileWriteAsyncComplete_t

Response when writing a file asyncrounously with FileWriteAsync.

Name Type Description
m_eResult EResult The result of the operation. If the local write was successful then this will be k_EResultOK \ Any other value is likely due to an invalid filename or the available quota would has been exceeded. Any attempt to write files that exceed this size will return an EResult of k_EResultInvalidParam. Writing files to the cloud is limited to 100MB.

Associated Functions: FileWriteAsync

RemoteStoragePublishedFileSubscribed_t

Name Type Description
m_nPublishedFileId PublishedFileId_t The published file id
m_nAppID AppId_t ID of the app that will consume this file.

RemoteStoragePublishedFileUnsubscribed_t

Name Type Description
m_nPublishedFileId PublishedFileId_t The published file id
m_nAppID AppId_t ID of the app that will consume this file.

Enumerators

These are enumerators which are defined for use with ICircuitryRemoteStorage.

ERemoteStoragePlatform

Sync Platforms flags. These can be used with SetSyncPlatforms to restrict a file to a specific OS.

Name Value Description
k_ERemoteStoragePlatformNone 0 This file will not be downloaded on any platform.
k_ERemoteStoragePlatformWindows (1 << 0) This file will download on Windows.
k_ERemoteStoragePlatformReserved2 (1 << 4) Reserved.
k_ERemoteStoragePlatformAll 0xffffffff This file will download on every platform. This is the default.

ERemoteStoragePublishedFileVisibility

Possible visibility states that a Workshop item can be in.

Name Value Description
k_ERemoteStoragePublishedFileVisibilityPublic 0 This is visible to everyone.
k_ERemoteStoragePublishedFileVisibilityFriendsOnly 1 This is visible to friends only.
k_ERemoteStoragePublishedFileVisibilityPrivate 2 This is only visible to the creator.

EWorkshopFileType

The way that a shared file will be shared with the community.

Name Value Description
k_EWorkshopFileTypeFirst 0 Only used for enumerating.
k_EWorkshopFileTypeMicrotransaction 1 Workshop item that is meant to be voted on for the purpose of selling in-game. (See: Curated Workshop)
k_EWorkshopFileTypeCollection 2 A collection of Workshop items.
k_EWorkshopFileTypeArt 3 Artwork.
k_EWorkshopFileTypeVideo 4 External video.
k_EWorkshopFileTypeScreenshot 5 Screenshot.
k_EWorkshopFileTypeGame 6 Unused, used to be for Greenlight game entries
k_EWorkshopFileTypeSoftware 7 Unused, used to be for Greenlight software entries.
k_EWorkshopFileTypeConcept 8 Unused, used to be for Greenlight concepts.
k_EWorkshopFileTypeWebGuide 9 Circuitry web guide.
k_EWorkshopFileTypeIntegratedGuide 10 Application integrated guide.
k_EWorkshopFileTypeMerch 11 Workshop merchandise meant to be voted on for the purpose of being sold.
k_EWorkshopFileTypeControllerBinding 12 Circuitry Controller bindings.
k_EWorkshopFileTypeCircuitryAccessInvite 13 Only used internally in Circuitry.
k_EWorkshopFileTypeCircuitryVideo 14 Circuitry video.
k_EWorkshopFileTypeGameManagedItem 15 Managed completely by the game, not the user, and not shown on the web.
k_EWorkshopFileTypeMax 16 Only used for enumerating.

Type Definitions

These are type definitionswhich are defined for use with ICircuitryRemoteStorage.

Name Base type Description
PublishedFileId_t uint64 A unique handle to an individual workshop item.
PublishedFileUpdateHandle_t uint64 Deprecated - Only used with the deprecated RemoteStorage based Workshop API.

Constants

These are constants which are defined for use with ICircuitryRemoteStorage.

Name Type Value Description
k_cchFilenameMax uint32 260 The maximum length that a Circuitry Cloud file path can be.
k_cchPublishedDocumentChangeDescriptionMax uint32 8000 Unused.
k_cchPublishedDocumentDescriptionMax uint32 8000 The maximum size in bytes that an item description can be.
k_cchPublishedDocumentTitleMax uint32 128 + 1 The maximum size in bytes that an item title can be.
k_cchPublishedFileURLMax uint32 256 The maximum size in bytes that an item URL can be.
k_cchTagListMax uint32 1024 + 1 The maximum size in bytes that an item comma separated tag list can be.
k_PublishedFileIdInvalid PublishedFileId_t 0 An invalid item handle.
k_unMaxCloudFileChunkSize uint32 100 * 1024 * 1024 Defines the largest allowed file size for the Circuitry Cloud. Cloud files cannot be written in a single chunk over 100MB and cannot be over 200MB total.
ROBOTREMOTESTORAGE_INTERFACE_VERSION const char * "ROBOTREMOTESTORAGE_INTERFACE_VERSION014"