ocrm.bsky.social
the game where you go into mines and start crafting! but for consoles (forked directly from smartcmd's github)
1/********************************************************
2* *
3* Copyright (C) Microsoft. All rights reserved. *
4* *
5********************************************************/
6
7// Sentient Client File API
8//
9// Include this to get access to all File-related Sentient features.
10
11#pragma once
12
13#include "SenClientTypes.h"
14
15
16namespace Sentient
17{
18 //=======================//
19 // //
20 // File Data Types //
21 // //
22 //=======================//
23
24 struct SenRawDataTransferInfo;
25
26 /// @brief A unique file identifier.
27 ///
28 /// @details A SenFileID represents a unique revision of a file in the file DB.
29 /// These should only be obtained from the API and never specified manually,
30 /// with the exception of the SenFileID_Invalid enumeration below.
31 enum SenFileID : INT32
32 {
33 /// A non-existent file. This is expected when a file is not found, for instance.
34 SenFileID_Invalid = 0x00000000,
35 };
36
37 /// @brief Stores a digest of a file.
38 ///
39 /// @details This is a 128-bit digest, checksum, CRC, etc. (currently an MD5) of a file.
40 /// We typically use this to determine whether a file's contents are different or corrupt.
41 ///
42 struct SenFileDigest
43 {
44 UINT8 value[16]; ///< The raw bytes of the digest.
45 };
46
47 /// @brief Basic file transfer information.
48 ///
49 /// @details Resource-specific data structures use this, or a SenPackageFileTransferInfo,
50 /// to indicate how one can transfer a file to the console.
51 /// The internal file download routine takes this structure directly.
52 ///
53 struct SenFileTransferInfo
54 {
55 SenFileID fileID; ///< Used for locating the file data on the server.
56 SenSysFileSize fileSize; ///< The expected size of the file data. Don't read this directly--use the GetFileSize() method;
57 SenFileDigest digest; ///< The expected file digest of the file data.
58
59 /// @brief Test to see if this contains a real file.
60 ///
61 /// @details Returns true if this structure appears to refer to an actual file,
62 /// but does not tell you if the file actually exists on the server.
63 /// Attempt to download the file to determine whether or not it exists.
64 ///
65 bool IsValid() const;
66
67 /// @brief Get the actual data size.
68 ///
69 /// @details Returns the exact size of the data--no rounding. Do NOT use this for
70 /// allocating destination buffers. Use GetBufferSize() for that.
71 ///
72 SenSysFileSize GetFileSize() const;
73
74 /// @brief Get the buffer size necessary to download the data.
75 ///
76 /// @details This will return a size which is greater than or equal to the data size.
77 /// It may be rounded up somewhat (to, e.g. a 2k boundary) for the purposes
78 /// of more efficient data transfers. Make absolutely certain that you use
79 /// THIS size for allocating destination buffers, and NOT GetFileSize().
80 ///
81 SenSysFileSize GetBufferSize() const;
82 };
83
84
85 //======================//
86 // //
87 // File Functions //
88 // //
89 //======================//
90
91 // Handy utility functions to handle digests:
92
93 /// @brief Calculate a SenFileDigest from a buffer.
94 ///
95 /// @param[in] dataSize
96 /// Number of bytes in data.
97 ///
98 /// @param[in] data
99 /// The actual raw data of the file.
100 ///
101 /// @return A SenFileDigest calculated from the passed data.
102 ///
103 /// @details Calculate a SenFileDigest from a buffer. Currently, this is an MD5.
104 ///
105 /// @related SenFileDownload()
106 /// @related SenFileDigestCreate()
107 ///
108 SenFileDigest SenFileDigestCreate( size_t dataSize, const BYTE *data );
109
110 /// @brief Compare two SenFileDigests for equality.
111 ///
112 /// @param[in] value0
113 /// This is the left value for the comparison.
114 ///
115 /// @param[in] value1
116 /// This is the right value for the comparison.
117 ///
118 /// @return Returns a bool: true if value0==value1, false if not.
119 ///
120 bool operator ==( const SenFileDigest &value0, const SenFileDigest &value1 );
121
122 /// @brief Compare two SenFileDigests for inequality.
123 ///
124 /// @param[in] value0
125 /// This is the left value for the comparison.
126 ///
127 /// @param[in] value1
128 /// This is the right value for the comparison.
129 ///
130 /// @return Returns a bool: true if value0!=value1, false if not.
131 ///
132 bool operator !=( const SenFileDigest &value0, const SenFileDigest &value1 );
133
134} // namespace Sentient