1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef _GTS_NANOAPPS_SHARED_SEND_MESSAGE_H_ 18 #define _GTS_NANOAPPS_SHARED_SEND_MESSAGE_H_ 19 20 #include <cstddef> 21 #include <cstdint> 22 23 #include <shared/abort.h> 24 25 /** 26 * NOTE: The MessageType values are manually synced in the GTS Java's 27 * ContextHubTestConstants.java. If you make a change here, be sure 28 * to update ContextHubTestContants.java as well. 29 */ 30 31 namespace nanoapp_testing { 32 33 /** 34 * Messages types which are sent between Nanoapps and the Java Host testing 35 * code. 36 */ 37 enum class MessageType : uint32_t { 38 /** 39 * Value which should never be used. 40 * 41 * This value starts at CONTEXT_HUB_TYPE_PRIVATE_MSG_BASE. 42 * 43 * This type should never be sent by Host or Nanoapp code. 44 */ 45 kInvalidMessageType = 0x0400, 46 47 /** 48 * Test has completed in success. 49 * 50 * This type should only be sent by the Nanoapp code. 51 */ 52 kSuccess = 0x0401, 53 54 /** 55 * Indicates a failure in the CHRE implementation. 56 * 57 * This should be followed by null-terminated string 58 * giving details of failure. 59 * 60 * This type should only be sent by the Nanoapp code. 61 */ 62 kFailure = 0x0402, 63 64 /** 65 * Indicate a failure within the testing infrastructure. 66 * 67 * This should be followed by null-terminated string 68 * giving details of failure. 69 * 70 * This type should only be sent by the Nanoapp code. 71 */ 72 kInternalFailure = 0x0403, 73 74 /** 75 * Indicate a test is being skipped. 76 * 77 * This should be followed by null-terminated string 78 * giving an explanation of why this test was skipped. 79 * 80 * This type should only be sent by the Nanoapp code. 81 */ 82 kSkipped = 0x0404, 83 84 /** 85 * A generic message indicating that the test should continue. 86 * 87 * The meaning of this generic message depends on the specific test. 88 * In general, it means something along the lines of "The test is 89 * successful thus far, please proceed to the next stage." 90 * 91 * This type can be sent by the Host or Nanoapp code. 92 */ 93 kContinue = 0x0405, 94 95 // Tests wanting to add custom message types for their protocols should 96 // add them below. Remember to update ContextHubTestConstants.java as 97 // well (see NOTE at the top of this header). 98 }; 99 100 /** 101 * Sends a message to the host with the given data. 102 * 103 * This method will make a copy of 'data', so there's no need for the 104 * caller to keep that alive after this call. 105 * 106 * Note it may often be more convenient to use one the other methods 107 * when sending a text string. 108 * 109 * @param messageType The type of the message. 110 * @param data The data to send. This can be nullptr, but then 'dataSize' 111 * must be 0. 112 * @param dataSize The number of bytes of 'data' to send. If 'data' is 113 * not 'nullptr', then this must be non-zero. 114 */ 115 void sendMessageToHost(MessageType messageType, const void *data = nullptr, 116 size_t dataSize = 0); 117 118 /** 119 * Sends a message to the host, optionally with the 'value' appended as in 120 * hex. 121 * 122 * This method will make a copy of 'message' and 'value', so there's no 123 * need for the caller to keep those alive after this call. 124 * 125 * Note it may often be more convenient to use one of the other methods 126 * below. 127 * 128 * @param messageType The type of the message. 129 * @param message The text of the message. This cannot be nullptr. 130 * @param value Optional, defaults to nullptr. If non-null, this value will 131 * be output as hexadecimal at the end of the message to the host. 132 */ 133 void sendStringToHost(MessageType messageType, const char *message, 134 const uint32_t *value = nullptr); 135 136 /** 137 * Same as sendStringToHost(), but using MessageType::kFailure for the 'status'. 138 */ 139 inline void sendFailureToHost(const char *message, 140 const uint32_t *value = nullptr) { 141 sendStringToHost(MessageType::kFailure, message, value); 142 } 143 144 /** 145 * Same as sendFailureToHost(), but aborts the test with the given 'reason', 146 * and never returns. 147 */ 148 void sendFatalFailureToHost(const char *message, 149 const uint32_t *value = nullptr, 150 AbortBlame reason = AbortBlame::kChre); 151 152 /** 153 * Same as sendStringToHost(), but uses MessageType::kInternalFailure for the 154 * 'status', and aborts the test with the given 'reason' and never returns. 155 */ 156 void sendInternalFailureToHost(const char *message, 157 const uint32_t *value = nullptr, 158 AbortBlame reason = AbortBlame::kTestFramework); 159 160 /** 161 * Invoke sendMessageToHost with MessageType::kSuccess and no other information. 162 */ 163 inline void sendSuccessToHost() { 164 sendMessageToHost(MessageType::kSuccess); 165 } 166 167 168 } // namespace nanoapp_testing 169 170 171 #endif // _GTS_NANOAPPS_SHARED_SEND_MESSAGE_H_ 172
