CTR Pia  4.11.3
Game Communication Engine
sync.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: sync.h
4 
5  Copyright Nintendo. All rights reserved.
6 
7  These coded instructions, statements, and computer programs contain
8  proprietary information of Nintendo of America Inc. and/or Nintendo
9  Company Ltd., and are protected by Federal copyright law. They may
10  not be disclosed to third parties or copied or duplicated in any form,
11  in whole or in part, without the prior written consent of Nintendo.
12  *---------------------------------------------------------------------------*/
13 
14 
15 #pragma once
16 
17 #include <pia/definitions.h>
18 
19 
20 /*!
21 @namespace nn::pia::sync
22 @brief Represents the <tt>PiaSync</tt> namespace.
23 
24 @if CTR_DOC
25 @date 2013-04-09 Removed the following: <tt>HidSync</tt>, <tt>SyncProtocolOld</tt>, <tt>StationAddressTable</tt>, <tt>ResultInternalStateMismatch</tt>, <tt>ResultSynchronizationIsLost</tt>, <tt>ResultFailedToSynchronize</tt>, and <tt>ResultInvalidDevice</tt>.
26 @date 2013-01-23 Increased the maximum number of stations available when using the <tt>HidSync</tt> and <tt>SyncProtocolOld</tt> classes.
27 @endif
28 @date 2013-01-18 Added <tt>ResultDataIsNotSet</tt> to the <tt>Result</tt> values.
29 
30 @if CAFE_DOC
31 @date 2012-12-25 Initial version.
32 @endif
33 
34 @if WIN_DOC
35 @date 2012-12-25 Initial version.
36 @endif
37 
38 @if CTR_DOC
39 @date 2012-10-29 Categorized member functions to improve readability of the API reference.
40 @date 2012-10-19 Modified comments in the header field in accordance with changes to the format of the API reference.
41 @date 2012-07-10 Deleted old <tt>Result</tt>-related codes that had been left in the <tt>sync</tt> namespace for compatibility reasons.
42 @date 2012-05-07 The data sharing feature for the accelerometer and gyro sensor is now officially supported.
43 @date 2012-05-07 Changed the Japanese spelling of 'sensor' in the Nintendo 3DS Terminology Guide.
44 @date 2012-04-05 In accordance with the revision of the policy for managing results throughout Pia, the results for the <tt>sync</tt> module have changed, and the references have been made to adhere to those changes.
45 @date 2012-03-12 The <tt>APP_SPECIFIC_DEVICE</tt> defined by the <tt>DeviceId</tt> enumerated type can now be used by applications as an application-specific device. (Equivalent to the Beta version.)
46 @date 2012-03-03 Added a caution when sharing gyro sensor data. For more information, see <tt>sync::SyncDeviceProfile</tt>.
47 @date 2012-02-22 Sharing of accelerometer and gyro sensor data has been implemented on a trial basis. Data sharing is equivalent to an Alpha version. Correct operation is not guaranteed at present.
48 @date 2011-12-07 The severity of <tt>ResultSyncToBeImplemented</tt> changed from <tt>SEVERITY_SHOULD_BE_HANDLED</tt> to <tt>SEVERITY_PROGRAMMING_ERROR</tt>. The severity of <tt>ResultSyncDataIsNotArrivedYet</tt> changed from <tt>SEVERITY_IGNORABLE</tt> to <tt>SEVERITY_SHOULD_BE_HANDLED</tt>.
49 @date 2011-11-29 Added <tt>ResultSyncInvalidDevice</tt> to the <tt>Result</tt> values.
50 @date 2011-11-16 Provided the <tt>sync::ErrorReason</tt> enumerated type.
51 @date 2011-11-16 Discontinued the original plans to provide specifications for callback during synchronization start. Deleted a callback type definition.
52 @date 2011-11-10 Added <tt>STATE_MASTER_REINITIALIZING</tt> and <tt>STATE_CLIENT_REINITIALIZING</tt> to the <tt>sync::State</tt> enumeration.
53 @date 2011-11-10 Added information about the <tt>Initialize</tt> function's return values, which had been previously left out.
54 @date 2011-10-31 Changed specifications for initialization processing beneath the <tt>sync</tt> module, so that it is now performed during the setup period from the execution of the <tt>sync::BeginSetup</tt> function until the execution of the <tt>sync::EndSetup</tt> function.
55 @date 2011-10-31 Removed arguments from the <tt>sync::Initialize</tt> function.
56 @date 2011-10-31 Changed specifications for the <tt>Initialize</tt> function's return value from <tt>void</tt> to <tt>nn::Result</tt>.
57 @date 2011-10-21 Added documentation.
58 @date 2011-10-19 Released the alpha version.
59 @endif
60 */
61 namespace nn
62 {
63 namespace pia
64 {
65 namespace sync
66 {
67 /*! @name Finish Initialization
68  @{
69 */
70 
71 /*!
72 @brief Initializes the <tt>PiaSync</tt> module.
73 Execute the <tt>nn::pia::common::Initialize</tt> function in advance.
74 
75 @details Memory that the <tt>sync</tt> module dynamically allocates and uses is allocated from memory passed by the <tt>@ref nn::pia::common::Initialize</tt> function.
76 
77 @return Returns a <tt>Result</tt> value indicating success if it is called at the right time.
78 @retval nn::pia::ResultInvalidState Indicates that the function has already been executed and initialization has completed.
79 
80 */
81 nn::Result Initialize();
82 
83 /*!
84 @brief Declares the start of setup.
85 
86 @details Call this function before initializing the <tt>sync</tt> module.
87 
88 @attention This function does not operate correctly if called during another module's setup processing.
89 After calling the <tt>@ref sync::BeginSetup</tt> function, perform initialization in the <tt>sync</tt> module, and promptly call the <tt>@ref sync::EndSetup</tt> function to complete setup.
90 
91 @return Returns a <tt>Result</tt> value indicating success if it is called at the right time.
92 @retval nn::pia::ResultNotInitialized Indicates that the <tt>sync::Initialize</tt> function has not been called. Programming error. Fix your program so that this error is not returned.
93 @retval nn::pia::ResultInvalidState Indicates that this function is being called during the setup period. Programming error. Fix your program so that this error is not returned.
94 */
95 nn::Result BeginSetup(void);
96 
97 /*!
98 @cond PRIVATE
99 @brief Checks whether setup is currently underway.
100 
101 @details The application should not call this function. It is provided for internal use.
102 
103 @return Returns <tt>true</tt> if this function is called between calls to the <tt>@ref sync::BeginSetup</tt> and <tt>@ref sync::EndSetup</tt> functions.
104 */
105 bool IsSetupNow(void);
106 /** @endcond */
107 
108 /*!
109 @brief Declares the end of setup.
110 
111 @details Call this function after initializing the <tt>sync</tt> module.
112 Calling this function establishes memory to be consumed by the singleton <tt>sync</tt> module and other modules, and optimizes memory management within the library.
113 
114 @attention This function does not operate correctly if it is called during another module's setup processing.
115 After calling the <tt>@ref BeginSetup</tt> function, perform initialization in the <tt>sync</tt> module, and promptly call the <tt>@ref EndSetup</tt> function to complete setup.
116 
117 @return Returns a <tt>Result</tt> value indicating success if it is called at the right time.
118 
119 @retval nn::pia::ResultNotInitialized Indicates that the <tt>sync::Initialize</tt> function has not been called. Programming error. Fix your program so that this error is not returned.
120 @retval nn::pia::ResultInvalidState Indicates that this function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
121 */
122 nn::Result EndSetup(void);
123 
124 /*!
125 @brief Indicates whether the <tt>PiaSync</tt> module is initialized.
126 
127 @return Returns <tt>true</tt> if initialized, and <tt>false</tt> otherwise.
128 */
129 bool IsInitialized(void);
130 
131 /*!
132 @brief Finalizes the <tt>PiaSync</tt> module.
133 Call this function before calling the <tt>@ref nn::pia::common::Finalize</tt> function.
134 
135 @details All processing for the <tt>PiaSync</tt> module must be ended before executing this function.
136 Calling this function has no effect if the <tt>@ref nn::pia::sync::Initialize</tt> function has not been called.
137 */
138 void Finalize(void);
139 /*!
140 end of name Finish Initialization
141  @}
142 */
143 }
144 }
145 }
146 
147 #include <pia/sync/sync_SyncProtocol.h>
bool IsInitialized(void)
Indicates whether the PiaSync module is initialized.
Definition: assert.h:115
void Finalize(void)
Finalizes the PiaSync module. Call this function before calling the nn::pia::common::Finalize functio...
nn::Result BeginSetup(void)
Declares the start of setup.
nn::Result EndSetup(void)
Declares the end of setup.
nn::Result Initialize()
Initializes the PiaSync module. Execute the nn::pia::common::Initialize function in advance...