Changed the RFCOMM-specific ItemProtocolChannel_t type to a more generic ItemProtocol...

[pub/USBasp.git] / LUFA / Drivers / USB / Class / Device / CDC.h

diff --git a/LUFA/Drivers/USB/Class/Device/CDC.h b/LUFA/Drivers/USB/Class/Device/CDC.h
index f0351f5..3bd9c9d 100644 (file)
--- a/LUFA/Drivers/USB/Class/Device/CDC.h
+++ b/LUFA/Drivers/USB/Class/Device/CDC.h
@@ -103,15 +103,15 @@
 
                                        uint8_t  DataINEndpointNumber; /**< Endpoint number of the CDC interface's IN data endpoint */
                                        uint16_t DataINEndpointSize; /**< Size in bytes of the CDC interface's IN data endpoint */
 
                                        uint8_t  DataINEndpointNumber; /**< Endpoint number of the CDC interface's IN data endpoint */
                                        uint16_t DataINEndpointSize; /**< Size in bytes of the CDC interface's IN data endpoint */

-                                       bool     DataINEndpointDoubleBank; /** Indicates if the CDC interface's IN data endpoint should use double banking */
+                                       bool     DataINEndpointDoubleBank; /**< Indicates if the CDC interface's IN data endpoint should use double banking */

 
                                        uint8_t  DataOUTEndpointNumber; /**< Endpoint number of the CDC interface's OUT data endpoint */
                                        uint16_t DataOUTEndpointSize;  /**< Size in bytes of the CDC interface's OUT data endpoint */
 
                                        uint8_t  DataOUTEndpointNumber; /**< Endpoint number of the CDC interface's OUT data endpoint */
                                        uint16_t DataOUTEndpointSize;  /**< Size in bytes of the CDC interface's OUT data endpoint */

-                                       bool     DataOUTEndpointDoubleBank; /** Indicates if the CDC interface's OUT data endpoint should use double banking */
+                                       bool     DataOUTEndpointDoubleBank; /**< Indicates if the CDC interface's OUT data endpoint should use double banking */

 
                                        uint8_t  NotificationEndpointNumber; /**< Endpoint number of the CDC interface's IN notification endpoint, if used */
                                        uint16_t NotificationEndpointSize;  /**< Size in bytes of the CDC interface's IN notification endpoint, if used */
 
                                        uint8_t  NotificationEndpointNumber; /**< Endpoint number of the CDC interface's IN notification endpoint, if used */
                                        uint16_t NotificationEndpointSize;  /**< Size in bytes of the CDC interface's IN notification endpoint, if used */

-                                       bool     NotificationEndpointDoubleBank; /** Indicates if the CDC interface's notification endpoint should use double banking */
+                                       bool     NotificationEndpointDoubleBank; /**< Indicates if the CDC interface's notification endpoint should use double banking */

                                } Config; /**< Config data for the USB class interface within the device. All elements in this section
                                           *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.
                                           */
                                } Config; /**< Config data for the USB class interface within the device. All elements in this section
                                           *   <b>must</b> be set or the interface will fail to enumerate and operate correctly.
                                           */


@@ -203,12 +203,12 @@
                         *  \ref CDC_Device_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be 
                         *  packed into a single endpoint packet, increasing data throughput.
                         *
                         *  \ref CDC_Device_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be 
                         *  packed into a single endpoint packet, increasing data throughput.
                         *

-                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
-                        *        the call will fail.
+                        *  \pre This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
+                        *       the call will fail.

                         *
                         *

-                        *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
-                        *  \param[in] Data  Pointer to the string to send to the host
-                        *  \param[in] Length  Size in bytes of the string to send to the host
+                        *  \param[in,out]   CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
+                        *  \param[in]       Data              Pointer to the string to send to the host
+                        *  \param[in]       Length            Size in bytes of the string to send to the host

                         *
                         *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum
                         */
                         *
                         *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum
                         */


@@ -220,11 +220,11 @@
                         *  \ref CDC_Device_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be 
                         *  packed into a single endpoint packet, increasing data throughput.
                         *
                         *  \ref CDC_Device_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be 
                         *  packed into a single endpoint packet, increasing data throughput.
                         *

-                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
-                        *        the call will fail.
+                        *  \pre This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
+                        *       the call will fail.

                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state

-                        *  \param[in] Data  Byte of data to send to the host
+                        *  \param[in]     Data              Byte of data to send to the host

                         *
                         *  \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum
                         */
                         *
                         *  \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum
                         */


@@ -232,8 +232,8 @@
                        
                        /** Determines the number of bytes received by the CDC interface from the host, waiting to be read.
                         *
                        
                        /** Determines the number of bytes received by the CDC interface from the host, waiting to be read.
                         *

-                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
-                        *        the call will fail.
+                        *  \pre This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
+                        *       the call will fail.

                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         *
                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         *


@@ -245,8 +245,8 @@
                         *  returns 0. The \ref CDC_Device_BytesReceived() function should be queried before data is received to ensure that no data
                         *  underflow occurs.
                         *
                         *  returns 0. The \ref CDC_Device_BytesReceived() function should be queried before data is received to ensure that no data
                         *  underflow occurs.
                         *

-                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
-                        *        the call will fail.
+                        *  \pre This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
+                        *       the call will fail.

                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         *
                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         *


@@ -256,8 +256,8 @@
                        
                        /** Flushes any data waiting to be sent, ensuring that the send buffer is cleared.
                         *
                        
                        /** Flushes any data waiting to be sent, ensuring that the send buffer is cleared.
                         *

-                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
-                        *        the call will fail.
+                        *  \pre This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
+                        *       the call will fail.

                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         *
                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         *


@@ -270,8 +270,8 @@
                         *  until they are cleared via a second notification. This should be called each time the CDC class driver's 
                         *  ControlLineStates.DeviceToHost value is updated to push the new states to the USB host.
                         *
                         *  until they are cleared via a second notification. This should be called each time the CDC class driver's 
                         *  ControlLineStates.DeviceToHost value is updated to push the new states to the USB host.
                         *

-                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
-                        *        the call will fail.
+                        *  \pre This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
+                        *       the call will fail.

                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         */
                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         */


@@ -290,25 +290,27 @@
                         *        to the given CDC interface.
                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
                         *        to the given CDC interface.
                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state

-                        *  \param[in,out] Stream  Pointer to a FILE structure where the created stream should be placed
+                        *  \param[in,out] Stream            Pointer to a FILE structure where the created stream should be placed

                         */
                         */

-                       void CDC_Device_CreateStream(USB_ClassInfo_CDC_Device_t* CDCInterfaceInfo, FILE* Stream);
+                       void CDC_Device_CreateStream(USB_ClassInfo_CDC_Device_t* CDCInterfaceInfo, FILE* Stream)
+                                                    ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);

 
                        /** Identical to CDC_Device_CreateStream(), except that reads are blocking until the calling stream function terminates
                         *  the transfer. While blocking, the USB and CDC service tasks are called repeatedly to maintain USB communications.
                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state
 
                        /** Identical to CDC_Device_CreateStream(), except that reads are blocking until the calling stream function terminates
                         *  the transfer. While blocking, the USB and CDC service tasks are called repeatedly to maintain USB communications.
                         *
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state

-                        *  \param[in,out] Stream  Pointer to a FILE structure where the created stream should be placed
+                        *  \param[in,out] Stream            Pointer to a FILE structure where the created stream should be placed

                         */
                         */

-                       void CDC_Device_CreateBlockingStream(USB_ClassInfo_CDC_Device_t* CDCInterfaceInfo, FILE* Stream);
+                       void CDC_Device_CreateBlockingStream(USB_ClassInfo_CDC_Device_t* CDCInterfaceInfo, FILE* Stream)
+                                                            ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);

 
        /* Private Interface - For use in library only: */
        #if !defined(__DOXYGEN__)
                /* Function Prototypes: */
                        #if defined(__INCLUDE_FROM_CDC_CLASS_DEVICE_C)
 
        /* Private Interface - For use in library only: */
        #if !defined(__DOXYGEN__)
                /* Function Prototypes: */
                        #if defined(__INCLUDE_FROM_CDC_CLASS_DEVICE_C)

-                               static int CDC_Device_putchar(char c, FILE* Stream);
-                               static int CDC_Device_getchar(FILE* Stream);
-                               static int CDC_Device_getchar_Blocking(FILE* Stream);
+                               static int CDC_Device_putchar(char c, FILE* Stream) ATTR_NON_NULL_PTR_ARG(2);
+                               static int CDC_Device_getchar(FILE* Stream) ATTR_NON_NULL_PTR_ARG(1);
+                               static int CDC_Device_getchar_Blocking(FILE* Stream) ATTR_NON_NULL_PTR_ARG(1);

                                
                                void CDC_Device_Event_Stub(void);
                                void EVENT_CDC_Device_LineEncodingChanged(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo)
                                
                                void CDC_Device_Event_Stub(void);
                                void EVENT_CDC_Device_LineEncodingChanged(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo)