├── README.md
├── LICENSE
└── GatherAsync.usp


/README.md:
--------------------------------------------------------------------------------
1 | # GatherAsync-Example
2 | An explanation for the undocumented GatherAsync() function in detail.
3 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2018 Troy Garner
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/GatherAsync.usp:
--------------------------------------------------------------------------------
 1 | #SYMBOL_NAME "GatherAsyncTest"
 2 | #CATEGORY "10" // Serial
 3 | 
 4 | #DEFAULT_VOLATILE
 5 | #ENABLE_STACK_CHECKING
 6 | #ENABLE_TRACE
 7 | 
 8 | BUFFER_INPUT rx$[4096];
 9 | 
10 | CALLBACK GatherEventHandler RxGatherHandler(GatherEventArgs e)
11 | {
12 |     // class GatherEventArgs
13 |     // {
14 |     //   SIGNED_INTEGER Results
15 |     //   STRING RxString
16 |     //   BUFFER_INPUT Input
17 |     // }
18 |     
19 |     try
20 |     {
21 |         if (e.Results = 0)
22 |         {
23 |             // Success
24 |             // - Use e.RxString here...
25 |         }
26 |         else if (e.Results = -1)
27 |         {
28 |             // Timeout
29 |         }
30 |     }
31 |     catch
32 |     {
33 |         Trace("RxGatherHandler Exception: %s\n", GetExceptionMessage());
34 |     }
35 |     // RETURNS - SIGNED_LONG_INTEGER
36 |     // -1 - failed (gather removed)
37 |     // 0  - success
38 |     //
39 |     // NOTES: calls the function that invoked this callback with the same parameters
40 |     // (i.e. GatherAsync("\r", rx$, RxGatherHandler, 500))
41 |     // - If the function fails (i.e. exception thrown) or terminates/returns prematurely
42 |     //   before the call to ReArmGatherAsync is made, then the asynchronous loop will end.
43 |     //   If you want to continue the gather "loop" then make sure something like a try-catch
44 |     //   statement is surrounding all code before this call to ensure that ReArmGatherAsync
45 |     //   is still called afterwards... Be sure to handle the exception appropriately if it is
46 |     //   a fatal exception to the state of your code.
47 |     //
48 |     // SIGNED_INTEGER RearmGatherAsync (BUFFER_INPUT Input);
49 |     ReArmGatherAsync(e.Input);
50 | }
51 | 
52 | FUNCTION Main()
53 | {
54 |     WaitForInitializationComplete();
55 |     
56 |     // 3-series (or greater) ONLY !!
57 |     
58 |     // RETURNS - SIGNED_LONG_INTEGER:
59 |     // -1 - over capacity
60 |     // 0  - success
61 |     // 1  - success (replaced previous gather criteria)
62 |     //
63 |     // NOTES: call without timeout or set timeout to -1 to disable
64 |     // SIGNED_INTEGER GatherAsync(STRING Delimiter, BUFFER_INPUT Input, GatherEventHandler EventHandler, [INTEGER Timeout]);
65 |     if (GatherAsync("\r", rx$, RxGatherHandler, 500) = -1)
66 |     {
67 |         // Error: over capacity - specifically for GatherAsyncByLength().
68 |         //
69 |         // SIGNED_INTEGER GatherAsyncByLength(INTEGER Length, BUFFER_INPUT Input, GatherEventHandler EventHandler, [INTEGER Timeout]);
70 |         // (i.e. GatherAsyncByLength(MAX_BUFFER_SIZE, rx$, RxGatherHandler, -1))
71 |         // * This function also has an optional timeout parameter.
72 |     }
73 |     
74 |     // RETURNS - SIGNED_LONG_INTEGER:
75 |     // -1 - failed to remove (already removed)
76 |     // 0  - success
77 |     // NOTE: call to terminate the asynchronous "loop"
78 |     // RemoveGatherAsync(rx$);
79 | }
80 | 


--------------------------------------------------------------------------------