Add a note to the sessiond.h header on the "" subsession

Change-Id: Id6ddafd8f017ede6423b20539f0c4d0c341570ba

diff --git a/libsessiond/include/sessiond.h b/libsessiond/include/sessiond.h
index 032967f..4114cf7 100644 (file)
--- a/libsessiond/include/sessiond.h
+++ b/libsessiond/include/sessiond.h
@@ -172,6 +172,14 @@ int subsession_switch_user(int session_uid, const subsession_user_t next_user, s
  *          ret = subsession_get_user_list(5001, &user_list_ptr, &user_count);
  *          ...
  *          free(user_list_ptr);
+ *
+ * Also, the user list depends on whether the session ID exists or not. If it
+ * doesn't, the user list is empty (in particular this is not an error).
+ * However if the session ID exists, the user list will contain the subsession
+ * IDs (if they exist), but also the default value, which is "" (empty string;
+ * see subsession_switch_user()). This doesn't mean that "" is a subsession ID
+ * in the same way as others; it is just a marker meaning that no subsession is
+ * enabled.
  */
 int subsession_get_user_list(int session_uid, subsession_user_t **user_list, int *user_count);
 
@@ -189,6 +197,10 @@ int subsession_get_user_list(int session_uid, subsession_user_t **user_list, int
  * @retval #SUBSESSION_ERROR_IO_ERROR Internal error occurred
  * @retval #SUBSESSION_ERROR_PERMISSION_DENIED Not permitted
  * @retval #SUBSESSION_ERROR_NOT_SUPPORTED Not supported
+ * @remarks When no subsession is enabled, "" (empty string) is returned, which
+ * is consistent with subsession_switch_user(). Again, this doesn't mean that
+ * "" is a subsession ID in the same way as others; it is just a marker meaning
+ * that no subsession is enabled.
  */
 int subsession_get_current_user(int session_uid, subsession_user_t user);