From: Victor Julien <victor@inliniac.net>
Date: Fri, 13 Mar 2020 13:43:00 +0000 (+0100)
Subject: app-layer: document return macros
X-Git-Tag: suricata-6.0.0-beta1~639
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=21e6f1f063e676f41cd85a30c83b236b1e845e72;p=thirdparty%2Fsuricata.git

app-layer: document return macros
---

diff --git a/rust/src/parser.rs b/rust/src/parser.rs
index 61a3098302..0970532475 100644
--- a/rust/src/parser.rs
+++ b/rust/src/parser.rs
@@ -1,4 +1,4 @@
-/* Copyright (C) 2017 Open Information Security Foundation
+/* Copyright (C) 2017-2020 Open Information Security Foundation
  *
  * You can copy, redistribute or modify this Program under the terms of
  * the GNU General Public License version 2 as published by the Free
@@ -34,6 +34,7 @@ pub struct AppLayerResult {
 }
 
 impl AppLayerResult {
+    /// parser has successfully processed in the input, and has consumed all of it
     pub fn ok() -> AppLayerResult {
         return AppLayerResult {
             status: 0,
@@ -41,6 +42,8 @@ impl AppLayerResult {
             needed: 0,
         };
     }
+    /// parser has hit an unrecoverable error. Returning this to the API
+    /// leads to no further calls to the parser.
     pub fn err() -> AppLayerResult {
         return AppLayerResult {
             status: -1,
@@ -48,6 +51,11 @@ impl AppLayerResult {
             needed: 0,
         };
     }
+    /// parser needs more data. Through 'consumed' it will indicate how many
+    /// of the input bytes it has consumed. Through 'needed' it will indicate
+    /// how many more bytes it needs before getting called again.
+    /// Note: consumed should never be more than the input len
+    ///       needed + consumed should be more than the input len
     pub fn incomplete(consumed: u32, needed: u32) -> AppLayerResult {
         return AppLayerResult {
             status: 1,
diff --git a/src/app-layer-parser.h b/src/app-layer-parser.h
index a4aa93166f..44248cceb3 100644
--- a/src/app-layer-parser.h
+++ b/src/app-layer-parser.h
@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2013 Open Information Security Foundation
+/* Copyright (C) 2007-2020 Open Information Security Foundation
  *
  * You can copy, redistribute or modify this Program under the terms of
  * the GNU General Public License version 2 as published by the Free
@@ -51,8 +51,20 @@
  *  completely inspected */
 #define APP_LAYER_TX_PREFILTER_MASK             ~APP_LAYER_TX_INSPECTED_FLAG
 
+/** parser has successfully processed in the input, and has consumed
+ *  all of it. */
 #define APP_LAYER_OK (AppLayerResult) { 0, 0, 0 }
+
+/** parser has hit an unrecoverable error. Returning this to the API
+ *  leads to no further calls to the parser. */
 #define APP_LAYER_ERROR (AppLayerResult) { -1, 0, 0 }
+
+/** parser needs more data. Through 'c' it will indicate how many
+ *  of the input bytes it has consumed. Through 'n' it will indicate
+ *  how many more bytes it needs before getting called again.
+ *  \note consumed (c) should never be more than the input len
+ *        needed (n) + consumed (c) should be more than the input len
+ */
 #define APP_LAYER_INCOMPLETE(c,n) (AppLayerResult) { 1, (c), (n) }
 
 int AppLayerParserProtoIsRegistered(uint8_t ipproto, AppProto alproto);