1 /* 2 * Copyright (C) 2020 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 #pragma once 17 18 #include <stddef.h> 19 #include <stdint.h> 20 21 using ApcCompatServiceHandle = void*; 22 23 #define APC_COMPAT_ERROR_OK 0 24 #define APC_COMPAT_ERROR_CANCELLED 1 25 #define APC_COMPAT_ERROR_ABORTED 2 26 #define APC_COMPAT_ERROR_OPERATION_PENDING 3 27 #define APC_COMPAT_ERROR_IGNORED 4 28 #define APC_COMPAT_ERROR_SYSTEM_ERROR 5 29 30 extern "C" { 31 32 extern const ApcCompatServiceHandle INVALID_SERVICE_HANDLE; 33 34 /** 35 * This struct holds the ui options for the protected confirmation dialog. 36 */ 37 struct ApcCompatUiOptions { 38 /** 39 * If set to true inverted color mode is used. 40 */ 41 bool inverted; 42 /** 43 * If set to true magnified fonts are used. 44 */ 45 bool magnified; 46 }; 47 48 /** 49 * Represents a result callback that is called when a confirmation session was successfully 50 * started. 51 * The field `data` is an opaque callback context handle. It must be passed to the `result` 52 * function. 53 * 54 * IMPORTANT: The life cycle of `data` ends when `result` is called. The callback must not 55 * be called a second time. 56 * 57 * The callback function `result` has the prototype: 58 * void result( 59 * void* data, 60 * uint32_t rc, 61 * const uint8_t* tbs_message, 62 * size_t tbs_message_size, 63 * const uint8_t* confirmation_token, 64 * size_t confirmation_token_size) 65 * 66 * * data - must be the data field of the structure. 67 * * rc - response code, one of: 68 * * APC_COMPAT_ERROR_OK - The user confirmed the prompt text. 69 * * APC_COMPAT_ERROR_CANCELLED - The user rejected the prompt text. 70 * * APC_COMPAT_ERROR_ABORTED - `abortUserConfirmation` was called. 71 * * APC_COMPAT_ERROR_SYSTEM_ERROR - An unspecified system error occurred. 72 * * tbs_message(_size) - Pointer to and size of the to-be-signed message. Must 73 * be NULL and 0 respectively if `rc != APC_COMPAT_ERROR_OK`. 74 * * confirmation_token(_size) - Pointer to and size of the confirmation token. Must 75 * be NULL and 0 respectively if `rc != APC_COMPAT_ERROR_OK`. 76 */ 77 struct ApcCompatCallback { 78 void* data; 79 void (*result)(void*, uint32_t, const uint8_t*, size_t, const uint8_t*, size_t); 80 }; 81 82 /** 83 * Attempts to make a connection to the confirmationui HIDL backend. 84 * If a valid service handle is returned it stays valid until 85 * `closeUserConfirmationService` is called. 86 * 87 * @return A valid service handle on success or INVALID_SERVICE_HANDLE 88 * on failure. 89 */ 90 ApcCompatServiceHandle tryGetUserConfirmationService(); 91 92 /** 93 * Attempts to start a protected confirmation session on the given service handle. 94 * The function takes ownership of the callback object (`cb`) IFF APC_COMPAT_ERROR_OK 95 * is returned. The resources referenced by the callback object must stay valid 96 * until the callback is called. 97 * 98 * @param handle A valid service handle as returned by `tryGetUserConfirmationService()`. 99 * @cb A ApcCompatCallback structure that represents a callback function with session data. 100 * @param prompt_text A UTF-8 encoded prompt string. 101 * @param extra_data Free form extra data. 102 * @param extra_data_size size of the extra data buffer in bytes. 103 * @param locale A locale string. 104 * @param ui_options A UI options. See ApcCompatUiOptions above. 105 * @retval APC_COMPAT_ERROR_OK on success. 106 * @retval APC_COMPAT_ERROR_OPERATION_PENDING if another operation was already in progress. 107 * @retval APC_COMPAT_ERROR_SYSTEM_ERROR if an unspecified system error occurred. 108 */ 109 uint32_t promptUserConfirmation(ApcCompatServiceHandle handle, struct ApcCompatCallback cb, 110 const char* prompt_text, const uint8_t* extra_data, 111 size_t extra_data_size, char const* locale, 112 ApcCompatUiOptions ui_options); 113 114 /** 115 * Aborts a running confirmation session or no-op if no session is running. 116 * If a session is running this results in a `result` callback with 117 * `rc == APC_COMPAT_ERROR_ABORTED`. Mind though that the callback can still yield other 118 * results even after this function was called, because it may race with an actual user 119 * response. In any case, there will be only one callback response for each session 120 * successfully started with promptUserConfirmation. 121 * 122 * @param handle A valid session handle as returned by `tryGetUserConfirmationService()` 123 */ 124 void abortUserConfirmation(ApcCompatServiceHandle handle); 125 126 /** 127 * Closes a valid service session as returned by `tryGetUserConfirmationService()`. 128 * If a session is still running it is implicitly aborted. In this case, freeing up of the resources 129 * referenced by the service handle is deferred until the callback has completed. 130 * 131 * @param handle A valid session handle as returned by `tryGetUserConfirmationService()` 132 */ 133 void closeUserConfirmationService(ApcCompatServiceHandle); 134 135 } 136