/*---------------------------------------------------------------------------* Project: Horizon File: rdt_Receiver.h Copyright (C) Nintendo. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. $Rev: 54504 $ *---------------------------------------------------------------------------*/ ////#include #ifndef NN_RDT_RECEIVER_H_ #define NN_RDT_RECEIVER_H_ #include #include #include namespace nn { namespace rdt { /*! @addtogroup nn_rdt_api @{ */ class ReceiverImpl; /*! @brief Structure that contains all configuration information passed to @ref Receiver::Initialize. */ struct ReceiverConfig{ void *pWorkBuf; //!< Pointer to the work memory region used by the Receiver instance. It must be 8-byte aligned. Allocate a working memory buffer of at least Receiver::RECEIVER_WORKBUF_SIZE bytes. void *pRecvBuf; //!< Takes the starting address of the receive buffer. u16 recvBufSize; //!< Size (in bytes) of the receive buffer (pRecvBuf). u16 nodeId; //!< Node ID of the UDS communication partner. u8 port; //!< Port number used during UDS communication. u8 padding[3]; //!< Padding. #ifdef _WIN32 SOCKET sock; #endif }; /*! @brief Class representing a device receiving data. The following description shows how to use the Receiver class. Detailed instructions on calling @ref Process have been left out of the following description. In actual practice, @ref Process must be called periodically at a frequency of about once per game frame or less.

Create an instance of the Receiver class.
Call @ref Initialize to initialize the instance. (The receive buffer memory and the work memory for use by the Receiver instance are allocated at this time.)
Call @ref Wait and wait for connection from a Sender instance.
When the state changes to RECEIVER_STATE_OPENED, periodically call @ref Receive to write received data (to the memory buffer provided by the application).
When the state changes to RECEIVER_STATE_FINISHED and you have confirmed that the size of data that can be read using @ref Receive has reached 0, call @ref Close.
When the state changes to RECEIVER_STATE_CLOSED, call @ref Finalize to clean up the Sender class.

*/ class Receiver{ public: static const size_t RECEIVER_WORKBUF_SIZE = 128; //!< Size of the working memory required by the Receiver instance. /*! @brief Instantiates an object. You must call @ref Initialize after calling this function to enable use of the Receiver instance. */ Receiver(void); /*! @brief Destroys the object. If @ref Finalize has not been called yet, the destructor calls it. */ ~Receiver(void); /*! @brief Initializes an instance. If initialization succeeds, this function implicitly consumes two nn::uds::EndpointDescriptor objects. If initialization fails, the function returns without consuming any nn::uds::EndpointDescriptor objects. Memory passed to the instance by this call must be allocated before calling @ref Finalize. The @ref nn::uds::Cafe::Attach "nn::uds::Attach" function is called implicitly with @ref nn::uds::Cafe::ATTACH_BUFFER_SIZE_DEFAULT "nn::uds::ATTACH_BUFFER_SIZE_DEFAULT" specified as the receive buffer size. If the application does not supply a large enough buffer to @ref nn::uds::Cafe::Initialize "nn::uds::Initialize", initialization fails, returning @ref nn::uds::Cafe::ResultOutOfResource "nn::uds::ResultOutOfResource", because the @ref nn::uds::Cafe::Attach "nn::uds::Attach" function uses the buffer passed to @ref nn::uds::Cafe::Initialize "nn::uds::Initialize". @param[in] config Data structure storing initialization parameters. For more information, see ReceiverConfig. @return Returns the result of initialization. Specifically, this function may return the following: a value for which the @ref nn::Result::IsSuccess function returns true or a result code returned by the UDS library (such as @ref ResultAlreadyInitialized, @ref ResultNullPointer, or @ref ResultInvalidSize). */ nn::Result Initialize(const ReceiverConfig &config); /*! @brief Frees resources that were used by a Receiver instance, including the receive buffer and the endpoint descriptors. @return None. Calls to @ref Finalize always succeed. If @ref Finalize is called when the instance is not initialized, the function does nothing and returns. */ void Finalize(void); /*! @brief Issues a request to wait for a connection. Issues a request to wait for a remote Sender instance to issue a connection request. If the call to this function succeeds, the state changes to RECEIVER_STATE_WAITING. The actual wait operation is performed by the @ref Process function. @return Returns success if the request was accepted. The function returns failure if it is called when the state of the instance is anything other than RECEIVER_STATE_CLOSED. Specifically, this function may return the following: a value for which the @ref nn::Result::IsSuccess function returns true; or @ref ResultNotInitialized or @ref ResultUntimelyFunctionCall. */ nn::Result Wait(void); /*! @brief Issues a request to revert an instance to the CLOSED state. Call this function after you verify that all data has been received. If the call to this function succeeds, the state transitions to RECEIVER_STATE_CLOSED. @return Returns success if the request was accepted. The function returns failure if it is called when the state of the instance is anything other than RECEIVER_STATE_FINISHED. Specifically, this function may return the following: a value for which the @ref nn::Result::IsSuccess function returns true; or @ref ResultNotInitialized or @ref ResultUntimelyFunctionCall. */ nn::Result Close(void); /*! @brief Reads the data that has accumulated in the receive buffer. Reads the byte string that was sent from the Sender instance and has accumulated in the receive buffer. This byte string is guaranteed to be obtainable in a form that maintains the byte sequence sent by nn::rdt::Sender::Send. We recommend calling this function every game frame to improve throughput. @param[out] pBuf Specifies the starting address of the buffer where the received data is written. @param[out] pRecvSize Stores the number of bytes that were read from the receive buffer. If no data was readable, this parameter is set to 0. @param[in] bufSize Holds the size, in bytes, of the buffer where the received data is written. If this parameter is set to 0, the function does nothing and returns a non-error value. @return Returns the result of the function. Specifically, this function may return the following: a value for which the @ref nn::Result::IsSuccess function returns true, or the @ref ResultDoNothing, @ref ResultNotInitialized, @ref ResultNullPointer, or @ref ResultUntimelyFunctionCall result code. */ nn::Result Receive(void *pBuf, size_t *pRecvSize, size_t bufSize); /*! @brief Proceeds with communication. The actual communication occurs within this function. Applications must always call this function at least every game frame (every 50 ms or less) until the @ref Finalize function is called, even when running in background mode. When sending and receiving real data, you can sometimes improve the transmission performance by calling this function several times in a row. This function results in transfer of up to 1400 bytes per call, but even more data can be received by calling this function multiple times. For more information about specific settings, see the ServerClient sample demo. Do not call other member functions (such as @ref Receive) while this function is running. This results in undefined operations. State transitions of Receiver instances are also handled within this function. @return Returns the result of a series of communication operations. Specifically, this function may return the following: a value for which the @ref nn::Result::IsSuccess function returns true or a result code returned by the UDS library, such as @ref ResultNotInitialized or @ref ResultResetReceived. */ nn::Result Process(void); /*! @brief Cancels the operation. Call this function when you want to forcibly stop communication based on a command by the player. Calling this function makes the Receiver instance transition to the RECEIVER_STATE_CLOSED state. This function is an exception in that it runs its operation right away, without waiting for the @ref Process function to run it. @return None. Calls to the @ref Cancel function always succeed. */ void Cancel(void); /*! @brief Gets the state of a Receiver instance. @return Returns the state of the instance at the time this function was called. */ enum ReceiverState GetStatus(void) const; /*! @brief Sets up a simulated packet loss ratio (for debugging). This function may be removed in a future release without notice. If a value other than zero is set for the packet loss ratio, the rdt library calls std::rand to determine whether to simulate packet loss. Set an appropriate random seed by calling std::srand before using this function. @param[in] per Provide a value so that 0 <= per <= 100. @return None. */ void SetPacketLossRatio(int per); /*! @brief Prints detailed information about the internal state of a Receiver instance (for debugging). This function may be removed in a future release without notice. @return None. */ void PrintDebugInfo(void) const; private: /*! @brief The copy constructor is private. */ Receiver (const Receiver&); /*! @brief The assignment operator is private. */ Receiver& operator=(const Receiver&); /*! @brief Private member variables. */ ReceiverImpl *m_pImpl; }; //! @} }} // namespace nn::rdt #endif // end of NN_RDT_RECEIVER_H_