Moved all source to the trunk directory.

[pub/lufa.git] / LUFA / Drivers / USB / LowLevel / StreamCallbacks.h

diff --git a/LUFA/Drivers/USB/LowLevel/StreamCallbacks.h b/LUFA/Drivers/USB/LowLevel/StreamCallbacks.h
new file mode 100644 (file)
index 0000000..60e408e
--- /dev/null
+++ b/LUFA/Drivers/USB/LowLevel/StreamCallbacks.h
@@ -0,0 +1,87 @@
+/*\r
+             LUFA Library\r
+     Copyright (C) Dean Camera, 2009.\r
+              \r
+  dean [at] fourwalledcubicle [dot] com\r
+      www.fourwalledcubicle.com\r
+*/\r
+\r
+/*\r
+  Copyright 2009  Dean Camera (dean [at] fourwalledcubicle [dot] com)\r
+\r
+  Permission to use, copy, modify, and distribute this software\r
+  and its documentation for any purpose and without fee is hereby\r
+  granted, provided that the above copyright notice appear in all\r
+  copies and that both that the copyright notice and this\r
+  permission notice and warranty disclaimer appear in supporting\r
+  documentation, and that the name of the author not be used in\r
+  advertising or publicity pertaining to distribution of the\r
+  software without specific, written prior permission.\r
+\r
+  The author disclaim all warranties with regard to this\r
+  software, including all implied warranties of merchantability\r
+  and fitness.  In no event shall the author be liable for any\r
+  special, indirect or consequential damages or any damages\r
+  whatsoever resulting from loss of use, data or profits, whether\r
+  in an action of contract, negligence or other tortious action,\r
+  arising out of or in connection with the use or performance of\r
+  this software.\r
+*/\r
+\r
+/** \file\r
+ *\r
+ *  Macros and enums for the stream callback routines in Endpoint.h and Pipe.c. This module contains the\r
+ *  code required to easily set up stream callback functions which can be used to force early abort of a\r
+ *  stream read/write process.\r
+ */\r
+ \r
+#ifndef __STREAMCALLBACK_H__\r
+#define __STREAMCALLBACK_H__\r
+\r
+       /* Public Interface - May be used in end-application: */\r
+               /* Macros: */\r
+                       /** Creates a prototype for or begins a stream callback routine. Stream callback routines are small\r
+                        *  routines which are executed during stream read or writes (if the callback-enabled versions of\r
+                        *  these functions are used) which allow the user application to abort the transfer when certain\r
+                        *  arbitrary conditions are met.\r
+                        *\r
+                        *  Stream callback functions should return a value from the StreamCallback_Return_ErrorCodes_t\r
+                        *  enum.\r
+                        *\r
+                        *  Usage Example (Device Endpoint, but applicable for Host pipes also):\r
+                        *  \code\r
+                        *  STREAM_CALLBACK(GlobalNotSet); // Callback Prototype\r
+                        *\r
+                        *  STREAM_CALLBACK(GlobalNotSet)\r
+                        *  {\r
+                        *     if (MyGlobal == false)\r
+                        *         return ENDPOINT_STREAMCALLBACK_Continue;\r
+                        *     else\r
+                        *         return ENDPOINT_STREAMCALLBACK_Abort;\r
+                        *  }\r
+                        *\r
+                        *  //...\r
+                        *  // Inside some routine:\r
+                        *  if (Endpoint_Write_CStream_LE(DataBuffer, sizeof(DataBuffer), GlobalNotSet) == \r
+                        *                                ENDPOINT_RWSTREAM_ERROR_CallbackAborted)\r
+                        *  {\r
+                        *      // Do something when the callback aborted the transfer early\r
+                        *  }\r
+                        *  \endcode\r
+                        */\r
+                       #define STREAM_CALLBACK(name) uint8_t name (void)\r
+\r
+                       /** Used with the Endpoint and Pipe stream functions as the callback function parameter, indicating that the stream\r
+                        *  call has no callback function to be called between USB packets.\r
+                        */\r
+                       #define NO_STREAM_CALLBACK    NULL\r
+                       \r
+               /* Enums: */\r
+                       /** Enum for the possible error return codes of a stream callback function */\r
+                       enum StreamCallback_Return_ErrorCodes_t\r
+                       {\r
+                               STREAMCALLBACK_Continue            = 0, /**< Continue sending or receiving the stream. */\r
+                               STREAMCALLBACK_Abort               = 1, /**< Abort the stream send or reciving process. */\r
+                       };\r
+                       \r
+#endif\r