src/include/cynara-creds-dbus.h

   1 /*
   2  *  Copyright (c) 2014 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        cynara-creds-dbus.h
  18  * @author      Lukasz Wojciechowski <l.wojciechow@partner.samsung.com>
  19  * @author      Radoslaw Bartosiak <r.bartosiak@samsung.com>
  20  * @version     1.0
  21  * @brief       This file contains Cynara credentials helper APIs for dbus clients.
  22  */
  23
  24
  25 #ifndef CYNARA_CREDS_DBUS_H
  26 #define CYNARA_CREDS_DBUS_H
  27
  28 #include <dbus/dbus.h>
  29 #include <sys/types.h>
  30
  31 #include "cynara-creds-commons.h"
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * \par Description:
  39  * Creates a client identification string with given method. Client is a process identified by the
  40  * unique name at the other side of the dbus connection.
  41  *
  42  * \par Purpose:
  43  * Client identification string is required for cynara_check() and cynara_async_check() functions.
  44  *
  45  * \par Typical use case:
  46  * The function is called before the call of one of ...check() functions.
  47  * Returned string is used as client parameter in ...check() function.
  48  * String is released with free() function when it is no longer needed.
  49  *
  50  * \par Method of function operation:
  51  * The function generates client string by calling a method from DBus Interface
  52  * ("org.freedesktop.DBus") which is placed on system bus ("org.freedesktop.DBus").
  53  *
  54  * \par Sync (or) Async:
  55  * This is a synchronous API.
  56  *
  57  * \par Thread safety:
  58  * This function is NOT thread-safe. If functions from described API are called by multithreaded
  59  * application from different threads, they must be put into mutex protected critical section.
  60  *
  61  * \par Important notes:
  62  * Memory for returned client string is obtained with malloc(), and should be freed with free().
  63  * Allocated string is returned only, when function succeeds.
  64  *
  65  * \param[in] connection DBus connection to a bus. It manages incomming and outgoing messages
  66  * \param[in] uniqueName DBus identifier of the client
  67  * \param[in] method Method of client identifier creation
  68  * \param[out] client Placeholder for allocated string containing client id
  69  *
  70  * \return CYNARA_API_SUCCESS on success
  71  *         CYNARA_API_INVALID_PARAM when client is NULL or uniqueName or client has wrong
  72  *                                  value (i.e NULL or non-existing)
  73  *         CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported
  74  *         CYNARA_API_OUT_OF_MEMORY when there was error allocating memory
  75  */
  76 int cynara_creds_dbus_get_client(DBusConnection *connection, const char *uniqueName,
  77                                  enum cynara_client_creds method, char **client);
  78
  79 /**
  80  * \par Description:
  81  * Creates a user identification string with given method. User is an executor of process
  82  * at the other side of socket.
  83  *
  84  * \par Purpose:
  85  * User identification string is required for cynara_check() and cynara_async_check() functions.
  86  *
  87  * \par Typical use case:
  88  * The function is called before the call of one of ...check() functions.
  89  * Returned string is used as user parameter in ...check() function.
  90  * String is released with free() function when it is no longer needed.
  91  *
  92  * \par Method of function operation:
  93  * The function generates user string by calling a method from DBus Interface
  94  * ("org.freedesktop.DBus") which is placed on system bus ("org.freedesktop.DBus").
  95  *
  96  * \par Sync (or) Async:
  97  * This is a synchronous API.
  98  *
  99  * \par Thread safety:
 100  * This function is NOT thread-safe. If functions from described API are called by multithreaded
 101  * application from different threads, they must be put into mutex protected critical section.
 102  *
 103  * \par Important notes:
 104  * Memory for returned user string is obtained with malloc(), and should be freed with free().
 105  * Allocated string is returned only, when function succeeds.
 106  *
 107  * \param[in] connection DBus connection to a bus. It manages incomming and outgoing messages
 108  * \param[in] uniqueName DBus identifier of the client invoked by the user
 109  * \param[in] method Method of client identifier creation
 110  * \param[out] user Placeholder for allocated string containing user id
 111  *
 112  * \return CYNARA_API_SUCCESS on success
 113  *         CYNARA_API_INVALID_PARAM when user is NULL or connection is not valid DBus connection or
 114  *                                  uniqueName does not represent a process conected to the DBus
 115  *         CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported
 116  *         CYNARA_API_OUT_OF_MEMORY when there was error allocating memory
 117  */
 118 int cynara_creds_dbus_get_user(DBusConnection *connection, const char *uniqueName,
 119                                enum cynara_user_creds method, char **user);
 120
 121 /**
 122  * \par Description:
 123  * Return PID of a proces identified by the unique name at the other side of the dbus connection.
 124  *
 125  * \par Purpose:
 126  * PID may be used for client_session creation with cynara_helper_session_from_pid() function
 127  * from libcynara-helper-session library. Client_session is needed for cynara_check()
 128  * and cynara_async_check() functions.
 129  *
 130  * \par Typical use case:
 131  * The function is called before the call of cynara_helper_session_from_pid() function.
 132  *
 133  * \par Method of function operation:
 134  * The function reads PID of the peer by calling a method from DBus Interface
 135  * ("org.freedesktop.DBus") which is placed on system bus ("org.freedesktop.DBus")
 136  * with "GetConnectionUnixProcessID" argument.
 137  *
 138  * \par Sync (or) Async:
 139  * This is a synchronous API.
 140  *
 141  * \par Thread safety:
 142  * This function is NOT thread-safe. If functions from described API are called by multithreaded
 143  * application from different threads, they must be put into mutex protected critical section.
 144  *
 145  * \param[in] connection DBus connection to a bus. It manages incomming and outgoing messages
 146  * \param[in] uniqueName DBus identifier of the client invoked by the user
 147  * \param[out] pid Placeholder for PID returned by function
 148  *
 149  * \return CYNARA_API_SUCCESS on success
 150  *         CYNARA_API_INVALID_PARAM when socket_fd is not valid connected socket descriptor
 151  *         CYNARA_API_UNKNOWN_ERROR when system function fails in incredible situation
 152  *         CYNARA_API_OUT_OF_MEMORY when there was error allocating memory
 153  */
 154 int cynara_creds_dbus_get_pid(DBusConnection *connection, const char *uniqueName, pid_t *pid);
 155
 156 #ifdef __cplusplus
 157 }
 158 #endif
 159
 160 #endif /* CYNARA_CREDS_DBUS_H */