1 /*
2  *  Copyright (c) 2016, The OpenThread Authors.
3  *  All rights reserved.
4  *
5  *  Redistribution and use in source and binary forms, with or without
6  *  modification, are permitted provided that the following conditions are met:
7  *  1. Redistributions of source code must retain the above copyright
8  *     notice, this list of conditions and the following disclaimer.
9  *  2. Redistributions in binary form must reproduce the above copyright
10  *     notice, this list of conditions and the following disclaimer in the
11  *     documentation and/or other materials provided with the distribution.
12  *  3. Neither the name of the copyright holder nor the
13  *     names of its contributors may be used to endorse or promote products
14  *     derived from this software without specific prior written permission.
15  *
16  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26  *  POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  * @brief
32  *   This file includes the OpenThread API for Factory Diagnostics.
33  */
34 
35 #ifndef OPENTHREAD_DIAG_H_
36 #define OPENTHREAD_DIAG_H_
37 
38 #include <openthread/instance.h>
39 #include <openthread/platform/diag.h>
40 
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44 
45 /**
46  * @addtogroup api-factory-diagnostics
47  *
48  * @brief
49  *   This module includes functions that control the Thread stack's execution.
50  *
51  * @{
52  */
53 
54 /* Represents the pointer to callback to output diag messages. */
55 typedef otPlatDiagOutputCallback otDiagOutputCallback;
56 
57 /**
58  * Sets the diag output callback.
59  *
60  * @param[in]  aInstance   The OpenThread instance structure.
61  * @param[in]  aCallback   A pointer to a function that is called on outputting diag messages.
62  * @param[in]  aContext    A pointer to the user context.
63  */
64 void otDiagSetOutputCallback(otInstance *aInstance, otDiagOutputCallback aCallback, void *aContext);
65 
66 /**
67  * Processes a factory diagnostics command line.
68  *
69  * @param[in]   aInstance       A pointer to an OpenThread instance.
70  * @param[in]   aArgsLength     The number of elements in @p aArgs.
71  * @param[in]   aArgs           An array of arguments.
72  *
73  * @retval  OT_ERROR_INVALID_ARGS       The command is supported but invalid arguments provided.
74  * @retval  OT_ERROR_NONE               The command is successfully process.
75  * @retval  OT_ERROR_NOT_IMPLEMENTED    The command is not supported.
76  */
77 otError otDiagProcessCmd(otInstance *aInstance, uint8_t aArgsLength, char *aArgs[]);
78 
79 /**
80  * Processes a factory diagnostics command line.
81  *
82  * @param[in]   aInstance       A pointer to an OpenThread instance.
83  * @param[in]   aString         A NULL-terminated input string.
84  *
85  * @retval  OT_ERROR_NONE               The command is successfully process.
86  * @retval  OT_ERROR_INVALID_ARGS       The command is supported but invalid arguments provided.
87  * @retval  OT_ERROR_NOT_IMPLEMENTED    The command is not supported.
88  * @retval  OT_ERROR_NO_BUFS            The command string is too long.
89  */
90 otError otDiagProcessCmdLine(otInstance *aInstance, const char *aString);
91 
92 /**
93  * Indicates whether or not the factory diagnostics mode is enabled.
94  *
95  * @param[in]  aInstance  A pointer to an OpenThread instance.
96  *
97  * @retval TRUE if factory diagnostics mode is enabled
98  * @retval FALSE if factory diagnostics mode is disabled.
99  */
100 bool otDiagIsEnabled(otInstance *aInstance);
101 
102 /**
103  * @}
104  */
105 
106 #ifdef __cplusplus
107 } // extern "C"
108 #endif
109 
110 #endif // OPENTHREAD_DIAG_H_
111