src/include/cynara-creds-commons.h

   1 /*
   2  *  Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved
   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  * @file        src/include/cynara-creds-commons.h
  18  * @author      Lukasz Wojciechowski <l.wojciechow@partner.samsung.com>
  19  * @author      Radoslaw Bartosiak <r.bartosiak@samsung.com>
  20  * @author      Aleksander Zdyb <a.zdyb@samsung.com>
  21  * @version     1.0
  22  * @brief       This file contains common APIs for Cynara credentials helper.
  23  */
  24
  25
  26 #ifndef CYNARA_CREDS_COMMONS_H
  27 #define CYNARA_CREDS_COMMONS_H
  28
  29 #include <cynara-error.h>
  30
  31 enum cynara_client_creds {
  32     CLIENT_METHOD_SMACK,
  33     CLIENT_METHOD_PID
  34 };
  35
  36 enum cynara_user_creds {
  37     USER_METHOD_UID,
  38     USER_METHOD_GID
  39 };
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 /**
  46  * \par Description:
  47  * Gets the system default method value for client feature used in cynara-creds.
  48  *
  49  * \par Purpose:
  50  * Functions cynara_creds_dbus_get_client() and cynara_creds_socket_get_client() take a method
  51  * parameter, which determines a kind of process feature (i.e PID, SMACK label) returned by them.
  52  * The described function provides implementation for obtaining a system default value
  53  * for this parameter.
  54  *
  55  * \par Typical use case:
  56  * The function might be called before cynara_creds_dbus_get_client()
  57  * and cynara_creds_socket_get_client(), when functions shall be invoked with system default
  58  * value of method parameter.
  59  *
  60  * \par Method of function operation:
  61  * When this function is called for the first time it reads and returns the value of client_default
  62  * parameter from /etc/cynara/creds.conf file (the path is determined by CYNARA_CONFIGURATION_DIR).
  63  * Returned value is cached so subsequent calls will not consult file again but use cached value.
  64  * This also means that after the initial call any changes in the file will be ignored for the
  65  * remaining lifetime of the process.
  66  *
  67  * \par Sync (or) Async:
  68  * This is a synchronous API.
  69  *
  70  * \par Thread safety:
  71  * This function is thread-safe.
  72  *
  73  * \param[out] method Placeholder for system default client feature
  74  *                     (like CLIENT_METHOD_SMACK, CLIENT_METHOD_PID)
  75  *
  76  * \return CYNARA_API_SUCCESS on success
  77  *         CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or
  78  *                                        there are errors in configuration file.
  79  *         CYNARA_API_OUT_OF_MEMORY if there is error in memory allocation.
  80  *         CYNARA_API_UNKNOWN_ERROR if there is other error.
  81  *
  82  */
  83 int cynara_creds_get_default_client_method(enum cynara_client_creds *method);
  84
  85 /**
  86  * \par Description:
  87  * Gets the system default method value for user feature used in cynara-creds.
  88  *
  89  * \par Purpose:
  90  * Functions cynara_creds_dbus_get_user() and cynara_creds_socket_get_user() take a method
  91  * parameter, which determines a kind of process feature (i.e UID, GID) returned by them.
  92  * The described function provides implementation for obtaining a system default value
  93  * for this parameter.
  94  *
  95  * \par Typical use case:
  96  * The function might be called before cynara_creds_dbus_get_user()
  97  * and cynara_creds_socket_get_user() when functions shall be invoked with system default
  98  * value of method parameter.
  99  *
 100  * \par Method of function operation:
 101  * When this function is called for the first time it reads and returns the value of user_default
 102  * parameter from /etc/cynara/creds.conf file (the path is determined by CYNARA_CONFIGURATION_DIR).
 103  * Returned value is cached so subsequent calls will not consult file again but use cached value.
 104  * This also means that after the initial call any changes in the file will be ignored for the
 105  * remaining lifetime of the process.
 106  *
 107  * \par Sync (or) Async:
 108  * This is a synchronous API.
 109  *
 110  * \par Thread safety:
 111  * This function is thread-safe.
 112  *
 113  * \param[out] method Placeholder for system default user feature
 114  * (like USER_METHOD_UID, USER_METHOD_GID)
 115  *
 116  * \return CYNARA_API_SUCCESS on success
 117  *         CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or
 118  *                                        there are errors in configuration file.
 119  *         CYNARA_API_OUT_OF_MEMORY if there is error in memory allocation.
 120  *         CYNARA_API_UNKNOWN_ERROR if there is other error.
 121  */
 122 int cynara_creds_get_default_user_method(enum cynara_user_creds *method);
 123
 124 #ifdef __cplusplus
 125 }
 126 #endif
 127
 128 #endif /* CYNARA_CREDS_COMMONS_H */