X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/f555ad7ced743a19eb1eefaf5eaf536fcbe58d80..2e76ad721e494f3a14ece73100ea9a2144c6fe8e:/LUFA/Drivers/USB/Class/Host/CDC.h diff --git a/LUFA/Drivers/USB/Class/Host/CDC.h b/LUFA/Drivers/USB/Class/Host/CDC.h index 9033cbfb9..455e2f9ef 100644 --- a/LUFA/Drivers/USB/Class/Host/CDC.h +++ b/LUFA/Drivers/USB/Class/Host/CDC.h @@ -38,7 +38,7 @@ */ /** \ingroup Group_USBClassCDC - * @defgroup Group_USBClassCDCHost CDC Class Host Mode Driver + * \defgroup Group_USBClassCDCHost CDC Class Host Mode Driver * * \section Sec_Dependencies Module Source Dependencies * The following files must be built with any user project that uses this module: @@ -58,7 +58,6 @@ #include "../Common/CDC.h" #include - #include /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) @@ -186,7 +185,7 @@ */ uint8_t CDC_Host_SendControlLineStateChange(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); - /** Sends a Send Break request to the device. This is generally used to separate data data or to indicate a special condition + /** Sends a Send Break request to the device. This is generally used to separate data or to indicate a special condition * to the receiving device. * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class host configuration and state. @@ -197,23 +196,39 @@ uint8_t CDC_Host_SendBreak(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, const uint8_t Duration) ATTR_NON_NULL_PTR_ARG(1); - /** Sends a given string to the attached USB device, if connected. If a device is not connected when the function is called, the - * string is discarded. Bytes will be queued for transmission to the device until either the pipe bank becomes full, or the - * \ref CDC_Host_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be - * packed into a single pipe packet, increasing data throughput. + /** Sends a given data buffer to the attached USB device, if connected. If a device is not connected when the function is + * called, the data will be discarded. Bytes will be queued for transmission to the device until either the pipe bank + * becomes full, or the \ref CDC_Host_Flush() function is called to flush the pending data to the device. This allows for + * multiple bytes to be packed into a single pipe packet, increasing data throughput. * * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the * call will fail. * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class host configuration and state. - * \param[in] Data Pointer to the string to send to the device. - * \param[in] Length Size in bytes of the string to send to the device. + * \param[in] Buffer Pointer to a buffer containing the data to send to the device. + * \param[in] Length Length of the data to send to the device. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t CDC_Host_SendData(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, + const uint8_t* const Buffer, + const uint16_t Length); + + /** Sends a given null-terminated string to the attached USB device, if connected. If a device is not connected when the + * function is called, the string is discarded. Bytes will be queued for transmission to the device until either the pipe + * bank becomes full, or the \ref CDC_Host_Flush() function is called to flush the pending data to the device. This allows + * for multiple bytes to be packed into a single pipe packet, increasing data throughput. + * + * \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the + * call will fail. + * + * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class host configuration and state. + * \param[in] String Pointer to the null terminated string to send to the device. * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ uint8_t CDC_Host_SendString(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, - const char* const Data, - const uint16_t Length) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); + const char* const String) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); /** Sends a given byte to the attached USB device, if connected. If a device is not connected when the function is called, the * byte is discarded. Bytes will be queued for transmission to the device until either the pipe bank becomes full, or the @@ -270,11 +285,19 @@ uint8_t CDC_Host_Flush(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); /** Creates a standard character stream for the given CDC Device instance so that it can be used with all the regular - * functions in the avr-libc \c library that accept a FILE stream as a destination (e.g. fprintf). The created + * functions in the standard \c library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created * stream is bidirectional and can be used for both input and output functions. * + * Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single + * fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may + * be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own + * line buffering. + * * \note The created stream can be given as stdout if desired to direct the standard output from all \c functions * to the given CDC interface. + * \n\n + * + * \note This function is not available on all microcontroller architectures. * * \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. @@ -282,9 +305,11 @@ void CDC_Host_CreateStream(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, FILE* const Stream); - /** Identical to CDC_Host_CreateStream(), except that reads are blocking until the calling stream function terminates + /** Identical to \ref CDC_Host_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. * + * \note This function is not available on all microcontroller architectures. + * * \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. */ @@ -305,10 +330,12 @@ #if !defined(__DOXYGEN__) /* Function Prototypes: */ #if defined(__INCLUDE_FROM_CDC_HOST_C) + #if defined(FDEV_SETUP_STREAM) static int CDC_Host_putchar(char c, FILE* Stream) ATTR_NON_NULL_PTR_ARG(2); static int CDC_Host_getchar(FILE* Stream) ATTR_NON_NULL_PTR_ARG(1); static int CDC_Host_getchar_Blocking(FILE* Stream) ATTR_NON_NULL_PTR_ARG(1); + #endif void CDC_Host_Event_Stub(void) ATTR_CONST; void EVENT_CDC_Host_ControLineStateChanged(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo)