| // Copyright 2016 Google Inc. All Rights Reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| // Module Overview: Starboard User module |
| // |
| // Defines a user management API. This module defines functions only for |
| // managing signed-in users. Platforms that do not have users must still |
| // implement this API, always reporting a single user that is current and |
| // signed in. |
| // |
| // These APIs are NOT expected to be thread-safe, so either call them from a |
| // single thread, or perform proper synchronization around all calls. |
| |
| #ifndef STARBOARD_USER_H_ |
| #define STARBOARD_USER_H_ |
| |
| #include "starboard/export.h" |
| #include "starboard/time.h" |
| #include "starboard/types.h" |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| // Private structure representing a device user. |
| typedef struct SbUserPrivate SbUserPrivate; |
| |
| // A handle to a user. |
| typedef SbUserPrivate* SbUser; |
| |
| // A set of string properties that can be queried on a user. |
| typedef enum SbUserPropertyId { |
| // The URL to the avatar for a user. Avatars are not provided on all |
| // platforms. |
| kSbUserPropertyAvatarUrl, |
| |
| // The path to a user's home directory, if supported on this platform. |
| kSbUserPropertyHomeDirectory, |
| |
| // The username of a user, which may be the same as the User ID, or it may be |
| // friendlier. |
| kSbUserPropertyUserName, |
| |
| // A unique user ID of a user. |
| kSbUserPropertyUserId, |
| } SbUserPropertyId; |
| |
| #if SB_HAS(USER_APPLICATION_LINKING_SUPPORT) |
| // Information about an application-specific authorization token. |
| typedef struct SbUserApplicationTokenResults { |
| // The size of the buffer pointed to by |token_buffer|. Call |
| // SbUserMaxAuthenticationTokenSizeInBytes() to get an appropriate size. |
| // |token_buffer_size| must be set to a value greater than zero. |
| size_t token_buffer_size; |
| |
| // Pointer to a buffer into which the token will be copied. |
| // |token_buffer| must not be NULL. |
| char* token_buffer; |
| |
| // If true, |expiry| will be set. If false, the token never expires. |
| bool has_expiry; |
| |
| // The absolute time that this token expires. It is valid to use the value of |
| // |expiry| only if |has_expiry| is true. |
| SbTime expiry; |
| } SbUserApplicationTokenResults; |
| #endif |
| |
| // Well-defined value for an invalid user. |
| #define kSbUserInvalid (SbUser) NULL |
| |
| // Returns whether the given user handle is valid. |
| static SB_C_INLINE bool SbUserIsValid(SbUser user) { |
| return user != kSbUserInvalid; |
| } |
| |
| // Gets a list of up to |users_size| signed-in users and places the results in |
| // |out_users|. The return value identifies the actual number of signed-in |
| // users, which may be greater or less than |users_size|. |
| // |
| // It is expected that there will be a unique |SbUser| per signed-in user and |
| // that the referenced objects will persist for the lifetime of the app. |
| // |
| // |out_users|: Handles for the retrieved users. |
| // |users_size|: The maximum number of signed-in users to retrieve. |
| SB_EXPORT int SbUserGetSignedIn(SbUser* out_users, int users_size); |
| |
| // Gets the current primary user, if one exists. This is the user that is |
| // determined, in a platform-specific way, to be the primary user controlling |
| // the application. For example, the determination might be made because that |
| // user launched the app, though it should be made using whatever criteria are |
| // appropriate for the platform. |
| // |
| // It is expected that there will be a unique SbUser per signed-in user, and |
| // that the referenced objects will persist for the lifetime of the app. |
| SB_EXPORT SbUser SbUserGetCurrent(); |
| |
| // Returns the size of the value of |property_id| for |user|, INCLUDING the |
| // terminating null character. The function returns |0| if |user| is invalid |
| // or if |property_id| is not recognized, supported, or set for the user. |
| // |
| // |user|: The user for which property size data is being retrieved. |
| // |property_id|: The property for which the data is requested. |
| SB_EXPORT int SbUserGetPropertySize(SbUser user, SbUserPropertyId property_id); |
| |
| // Retrieves the value of |property_id| for |user| and places it in |out_value|. |
| // The function returns: |
| // - |true| if the property value is retrieved successfully |
| // - |false| if |user| is invalid; if |property_id| isn't recognized, supported, |
| // or set for |user|; or if |value_size| is too small. |
| // |
| // |user|: The user for which property size data is being retrieved. |
| // |property_id|: The property for which the data is requested. |
| // |out_value|: The retrieved property value. |
| // |value_size|: The size of the retrieved property value. |
| SB_EXPORT bool SbUserGetProperty(SbUser user, |
| SbUserPropertyId property_id, |
| char* out_value, |
| int value_size); |
| #ifdef __cplusplus |
| } // extern "C" |
| #endif |
| |
| #endif // STARBOARD_USER_H_ |