Home | History | Annotate | Download | only in app 
      1 /*
      2  * Copyright (C) 2017 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 ESE_APP_WEAVER_H_
     18 #define ESE_APP_WEAVER_H_ 1
     19 
     20 #include "../../../../../libese/include/ese/ese.h"
     21 #include "../../../../../libese/include/ese/log.h"
     22 #include "../../../../../libese-sysdeps/include/ese/sysdeps.h"
     23 
     24 #include "../../../../include/ese/app/result.h"
     25 
     26 #ifdef __cplusplus
     27 extern "C" {
     28 #endif
     29 
     30 /**
     31  * EseWeaverSession carries the necessary start for interfacing
     32  * with the methods below.
     33  *
     34  * Its usage follows a lifecycle like:
     35  *
     36  *   EseAppResult res;
     37  *   EseWeaverSession session;
     38  *   ese_weaver_session_init(&session);
     39  *   res = ese_weaver_session_open(ese, &session);
     40  *   if (res != ESE_APP_RESULT_OK) {
     41  *     ... handle error (especially cooldown) ...
     42  *   }
     43  *   ... ese_weaver_* ...
     44  *   ese_weaver_session_close(&session);
     45  *
     46  */
     47 struct EseWeaverSession {
     48   struct EseInterface *ese;
     49   bool active;
     50   uint8_t channel_id;
     51 };
     52 
     53 /** The keys are 16 bytes */
     54 const uint8_t kEseWeaverKeySize = 16;
     55 
     56 /** The values are 16 bytes */
     57 const uint8_t kEseWeaverValueSize = 16;
     58 
     59 
     60 const int ESE_WEAVER_READ_WRONG_KEY = ese_make_app_result(0x6a, 0x85);
     61 const int ESE_WEAVER_READ_TIMEOUT = ese_make_app_result(0x6a, 0x87);
     62 
     63 /**
     64  * Initializes a pre-allocated |session| for use.
     65  */
     66 void ese_weaver_session_init(struct EseWeaverSession *session);
     67 
     68 /**
     69  * Configures a communication session with the Storage applet using a logical
     70  * channel on an already open |ese| object.
     71  *
     72  * @returns ESE_APP_RESULT_OK on success.
     73  */
     74 EseAppResult ese_weaver_session_open(struct EseInterface *ese, struct EseWeaverSession *session);
     75 
     76 /**
     77  * Shuts down the logical channel with the Storage applet and invalidates
     78  * the |session| internal state.
     79  *
     80  * @returns ESE_APP_RESULT_OK on success.
     81  */
     82 EseAppResult ese_weaver_session_close(struct EseWeaverSession *session);
     83 
     84 /**
     85  * Retreives the number of slots available.
     86  * @returns ESE_APP_RESULT_OK if |numSlots| contains a valid value.
     87  */
     88 EseAppResult ese_weaver_get_num_slots(struct EseWeaverSession *session, uint32_t *numSlots);
     89 
     90 /**
     91  * Writes a new key-value pair into the slot.
     92  *
     93  * |key| and |value| must be buffers of sizes |kEseWeaverKeySize| and
     94  * |kEseWeaverValueSize| respectively.
     95  *
     96  * @returns ESE_APP_RESULT_OK on success.
     97  */
     98 EseAppResult ese_weaver_write(struct EseWeaverSession *session, uint32_t slotId,
     99                               const uint8_t *key, const uint8_t *value);
    100 
    101 
    102 /**
    103  * Reads the value in the slot provided the correct key was passed.
    104  *
    105  * |key| and |value| must be buffers of sizes |kEseWeaverKeySize| and
    106  * |kEseWeaverValueSize| respectively.
    107  *
    108  * @returns ESE_APP_RESULT_OK if |value| was filled with the value.
    109  *          ESE_WEAVER_READ_WRONG_KEY if |key| was wrong and |timeout| contains
    110  *          a valid timeout.
    111  *          ESE_WEAVER_READ_TIMEOUT if Weaver is in backoff mode and |timeout|
    112  *          contains a valid timeout.
    113  */
    114 EseAppResult ese_weaver_read(struct EseWeaverSession *session, uint32_t slotId,
    115                              const uint8_t *key, uint8_t *value, uint32_t *timeout);
    116 
    117 /**
    118  * Erase the value of a slot whilst maintaining the same key.
    119  *
    120  * @returns ESE_APP_RESULT_OK on success.
    121  */
    122 EseAppResult ese_weaver_erase_value(struct EseWeaverSession *session, uint32_t slotId);
    123 
    124 #ifdef __cplusplus
    125 }  /* extern "C" */
    126 #endif
    127 
    128 #endif  /* ESE_APP_WEAVER_H_ */
    129