blob: bf9a5d443cc782db80b15fb5045d9c5c5ec2e4ca [file] [log] [blame]
// 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.
// User management API. Platforms that do not have users must still implement
// this API, always reporting a single user 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, placing the results in
// |out_users|, and returning the number of actual users signed in, whether
// 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.
SB_EXPORT int SbUserGetSignedIn(SbUser* out_users, int users_size);
// Gets the current primary user, if any. This is the user that is determined,
// in a platform specific way, to be the primary user controlling the
// application. This may be because that user launched the app, or using
// whatever criteria is 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();
// Gets the size of the value of |property_id| for |user|, INCLUDING the
// terminating null character. Returns 0 if if |user| is invalid, |property_id|
// isn't recognized, supported, or set for |user|.
SB_EXPORT int SbUserGetPropertySize(SbUser user, SbUserPropertyId property_id);
// Gets the value of |property_id| for |user|, and places it in |out_value|,
// returning false if |user| is invalid, |property_id| isn't recognized,
// supported, or set for |user|, or if |value_size| is too small.
SB_EXPORT bool SbUserGetProperty(SbUser user,
SbUserPropertyId property_id,
char* out_value,
int value_size);
#if SB_HAS(USER_APPLICATION_LINKING_SUPPORT)
// Initiates a process to link |user| with a per-application authentication
// token. On success, |out_token| is populated with the authentication token
// and |out_expiry| is set to the number of seconds until the token expires. An
// expiration of 0 indicates that the token never expires.
// This call will block until the linking process is complete, which may involve
// user input.
// After this call completes successfully, subsequent calls to
// SbUserRequestAuthenticationToken will return valid tokens.
// Returns false if |user| is invalid, |token_results| is NULL,
// |token_results.token_buffer| is NULL or if the token is larger than
// |token_results.token_buffer_size|.
// Returns true if process to link the token succeeded, and false if the process
// failed for any reason including user cancellation.
SB_EXPORT bool SbUserRequestApplicationLinking(
SbUser user,
SbUserApplicationTokenResults* token_results);
// Remove the link between |user| and the per-application authentication token.
// This call will block until the linking process is complete, which may involve
// user input.
// After this call completes successfully, subsequent calls to
// SbUserRequestAuthenticationToken will fail.
// Returns false if |user| is invalid.
// Returns true if the process to unlink the token succeeded. Returns false if
// the process failed for any reason including user cancellation.
SB_EXPORT bool SbUserRequestApplicationUnlinking(SbUser user);
// Requests a new per-application authentication token. On success, |out_token|
// is populated with the authentication token and |out_expiry| is set to the
// number of seconds until the token expires. An expiration of 0 indicates that
// the token never expires.
// This call will block until the token has been received.
// Returns false if |user| is invalid, |out_token| or |out_expiration| are NULL,
// or if the token is larger than |out_token_size|.
// Returns false if the user account is not linked with an application. In this
// case, SbUserRequestApplicationLinking should be called.
// Returns true if process to link the token succeeded, and false if the process
// failed for any reason including user cancellation.
SB_EXPORT bool SbUserRequestAuthenticationToken(
SbUser user,
SbUserApplicationTokenResults* token_results);
// Gets the maximum size of an authentication token as returned by
// SbUserRequestApplicationLinking and SbUserRequestAuthenticationToken.
SB_EXPORT size_t SbUserMaxAuthenticationTokenSizeInBytes();
#endif // SB_HAS(USER_APPLICATION_LINKING_SUPPORT)
#ifdef __cplusplus
} // extern "C"
#endif
#endif // STARBOARD_USER_H_