/// <summary>
/// Retrieves all of the groups for given enterprise. Must have permissions to see an enterprise's groups.
/// </summary>
/// <param name="limit">The number of results to return with this request. Refer to the Box API for defaults.</param>
/// <param name="offset">The offset of the results. Refer to the Box API for more details.</param>
/// <param name="fields">Attribute(s) to include in the response.</param>
/// <param name="autoPaginate">Whether or not to auto-paginate to fetch all groups; defaults to false.</param>
/// <returns>A collection of groups.</returns>
public async Task <BoxCollection <BoxGroup> > GetAllGroupsAsync(int?limit = null, int?offset = null, IEnumerable <string> fields = null, bool autoPaginate = false)
{
BoxRequest request = new BoxRequest(_config.GroupsEndpointUri)
.Param(ParamFields, fields)
.Param("limit", limit.ToString())
.Param("offset", offset.ToString());
if (autoPaginate)
{
if (!limit.HasValue)
{
limit = 100;
request.Param("limit", limit.ToString());
}
if (!offset.HasValue)
{
request.Param("offset", "0");
}
return(await AutoPaginateLimitOffset <BoxGroup>(request, limit.Value));
}
else
{
IBoxResponse <BoxCollection <BoxGroup> > response = await ToResponseAsync <BoxCollection <BoxGroup> >(request).ConfigureAwait(false);
return(response.ResponseObject);
}
}
/// <summary>
/// Retrieves all of the group collaborations for a given group. Note this is only available to group admins.
/// </summary>
/// <param name="groupId">The id of the group to get the list of collaborations for.</param>
/// <param name="limit">The number of results to return with this request. Refer to the Box API for defaults.</param>
/// <param name="offset">The offset of the results. Refer to the Box API for more details.</param>
/// <param name="fields">Attribute(s) to include in the response.</param>
/// <param name="autoPaginate">Whether or not to auto-paginate to fetch all group collaborations; defaults to false.</param>
/// <returns>A collection of collaborations for the specified group id.</returns>
public async Task <BoxCollection <BoxCollaboration> > GetCollaborationsForGroupAsync(string groupId, int?limit = null, int?offset = null,
IEnumerable <string> fields = null, bool autoPaginate = false)
{
var request = new BoxRequest(_config.GroupsEndpointUri, string.Format(Constants.CollaborationsPathString, groupId))
.Param(ParamFields, fields)
.Param("limit", limit.ToString())
.Param("offset", offset.ToString());;
if (autoPaginate)
{
if (!limit.HasValue)
{
limit = 100;
request.Param("limit", limit.ToString());
}
if (!offset.HasValue)
{
request.Param("offset", "0");
}
return(await AutoPaginateLimitOffset <BoxCollaboration>(request, limit.Value));
}
else
{
var response = await ToResponseAsync <BoxCollection <BoxCollaboration> >(request).ConfigureAwait(false);
return(response.ResponseObject);
}
}
/// <summary>
/// Get the list of group memberships for a given user.
/// </summary>
/// <param name="userId">The id of the user to get the list of memberships for.</param>
/// <param name="limit">The number of results to return with this request. Refer to the Box API for defaults.</param>
/// <param name="offset">The offset of the results. Refer to the Box API for more details.</param>
/// <param name="fields">Attribute(s) to include in the response.</param>
/// <param name="autoPaginate">Whether or not to auto-paginate to fetch all group memberships; defaults to false.</param>
/// <returns>A collection of group memberships for the specified user id.</returns>
public async Task <BoxCollection <BoxGroupMembership> > GetAllGroupMembershipsForUserAsync(string userId, int?limit = null, int?offset = null,
IEnumerable <string> fields = null, bool autoPaginate = false)
{
userId.ThrowIfNullOrWhiteSpace("userId");
BoxRequest request = new BoxRequest(_config.UserEndpointUri, string.Format(Constants.GroupMembershipPathString, userId))
.Param(ParamFields, fields)
.Param("limit", limit.ToString())
.Param("offset", offset.ToString());
if (autoPaginate)
{
if (!limit.HasValue)
{
limit = 100;
request.Param("limit", limit.ToString());
}
if (!offset.HasValue)
{
request.Param("offset", "0");
}
return(await AutoPaginateLimitOffset <BoxGroupMembership>(request, limit.Value));
}
else
{
IBoxResponse <BoxCollection <BoxGroupMembership> > response = await ToResponseAsync <BoxCollection <BoxGroupMembership> >(request).ConfigureAwait(false);
return(response.ResponseObject);
}
}
/// <summary>
/// Retrieves all of the groups for given enterprise. Must have permissions to see an enterprise's groups.
/// </summary>
/// <param name="limit">The number of results to return with this request. Refer to the Box API for defaults.</param>
/// <param name="offset">The offset of the results. Refer to the Box API for more details.</param>
/// <param name="fields">Attribute(s) to include in the response.</param>
/// <param name="autoPaginate">Whether or not to auto-paginate to fetch all groups; defaults to false.</param>
/// <returns>A collection of groups.</returns>
public async Task<BoxCollection<BoxGroup>> GetAllGroupsAsync(int? limit = null, int? offset = null, List<string> fields = null, bool autoPaginate = false)
{
BoxRequest request = new BoxRequest(_config.GroupsEndpointUri)
.Param(ParamFields, fields)
.Param("limit", limit.ToString())
.Param("offset", offset.ToString());
if (autoPaginate)
{
if (!limit.HasValue)
{
limit = 100;
request.Param("limit", limit.ToString());
}
if (!offset.HasValue)
request.Param("offset", "0");
return await AutoPaginateLimitOffset<BoxGroup>(request, limit.Value);
}
else
{
IBoxResponse<BoxCollection<BoxGroup>> response = await ToResponseAsync<BoxCollection<BoxGroup>>(request).ConfigureAwait(false);
return response.ResponseObject;
}
}
/// <summary>
/// Used to fetch all results using pagination based on limit and offset
/// </summary>
/// <typeparam name="T">The type of BoxCollection item to expect.</typeparam>
/// <param name="request">The pre-configured BoxRequest object.</param>
/// <param name="limit">The limit specific to the endpoint.</param>
/// <returns></returns>
protected async Task <BoxCollection <T> > AutoPaginateLimitOffset <T>(BoxRequest request, int limit) where T : class, new()
{
var allItemsCollection = new BoxCollection <T>();
allItemsCollection.Entries = new List <T>();
int offset = 0;
bool keepGoing;
do
{
var response = await ToResponseAsync <BoxCollection <T> >(request).ConfigureAwait(false);
var newItems = response.ResponseObject;
allItemsCollection.Entries.AddRange(newItems.Entries);
allItemsCollection.Order = newItems.Order;
offset += limit;
request.Param("offset", offset.ToString());
keepGoing = newItems.Entries.Count >= limit;
} while (keepGoing);
allItemsCollection.TotalCount = allItemsCollection.Entries.Count;
return(allItemsCollection);
}
/// <summary>
/// Returns a collection of search results that match the keyword, if there are are no matching search results
/// an empty collection will be returned
/// </summary>
/// <param name="keyword"></param>
/// <param name="limit"></param>
/// <param name="offset"></param>
/// <param name="extraParameters">additional search parameters, see https://developers.box.com/docs/#search-searching-for-content </param>
/// <returns></returns>
public async Task<BoxCollection<BoxItem>> SearchAsync(string keyword, int limit, int offset = 0, Dictionary<string,string> extraParameters = null)
{
keyword.ThrowIfNullOrWhiteSpace("keyword");
BoxRequest request = new BoxRequest(_config.SearchEndpointUri)
.Param("query", keyword)
.Param("limit", limit.ToString())
.Param("offset", offset.ToString());
if (extraParameters != null)
{
if (extraParameters.ContainsKey("query"))
{
throw new ArgumentException("ExtraParamters can not contain query paramter","extraParamters");
}
foreach (string key in extraParameters.Keys)
{
request.Param(key, extraParameters[key]);
}
}
IBoxResponse<BoxCollection<BoxItem>> response = await ToResponseAsync<BoxCollection<BoxItem>>(request).ConfigureAwait(false);
return response.ResponseObject;
}
/// <summary>
/// Gets the events that have occurred since the provided stream position.
/// </summary>
/// <param name="streamPosition">
/// <para>Optional. The stream position after which events should be returned. Default is "0" meaning "all".</para>
/// <para>The current stream position can be found with <see cref="GetcurrentStreamPositionAsync"/></para>
/// </param>
/// <param name="filter">
/// Optional. The types of events to include in the query. Default is <see cref="BoxEventFilter.All"/>
/// </param>
/// <param name="limit">
/// <para>Optional The maximum number of events to limit the results count to. Default is 100.</para>
/// <para>Must be a value between <see cref="Constants.MinStreamLimit"/> and <see cref="Constants.MaxStreamLimit"/></para>
/// </param>
/// <returns>
/// The events that have occurred since the provided stream position.
/// </returns>
public async Task <BoxEvents> GetEventsSinceAsync(long streamPosition = 0, BoxEventFilter filter = Constants.DefaultEventFilter, int limit = Constants.DefaultEventLimit)
{
if (limit < Constants.MinStreamLimit || limit > Constants.MaxStreamLimit)
{
throw new ArgumentOutOfRangeException("limit", string.Format("limit must be within the range {0} <= limit <= {1}", Constants.MinStreamLimit, Constants.MaxStreamLimit));
}
BoxRequest request = new BoxRequest(this._config.EventsEndpointUri);
// only add params if not default
if (streamPosition > 0)
{
request = request.Param(Constants.RequestParameters.StreamPosition, streamPosition.ToString());
}
// convert the enum to the expected JSON key
if (filter != Constants.DefaultEventFilter)
{
string filterValue = "all";
switch (filter)
{
case BoxEventFilter.FolderChanges:
filterValue = "changes";
break;
case BoxEventFilter.SyncedFolderChanges:
filterValue = "sync";
break;
}
request.Param(Constants.RequestParameters.StreamType, filterValue);
}
if (limit != Constants.DefaultEventLimit)
{
request = request.Param(Constants.RequestParameters.StreamLimit, limit.ToString());
}
IBoxResponse <BoxEvents> response = await this.ToResponseAsync <BoxEvents>(request).ConfigureAwait(false);
return(response.ResponseObject);
}
/// <summary>
/// Used to add a collaboration for a single user to a folder. Descriptions of the various roles can be found
/// <see cref="https://support.box.com/entries/20366031-what-are-the-different-collaboration-permissions-and-what-access-do-they-provide"/>
/// Either an email address or a user ID can be used to create the collaboration.
/// </summary>
/// <param name="collaborationRequest"></param>
/// <param name="fields">Attribute(s) to include in the response</param>
/// <param name="notify">Determines if the user, (or all the users in the group) should receive email notification of the collaboration.</param>
/// <returns></returns>
public async Task <BoxCollaboration> AddCollaborationAsync(BoxCollaborationRequest collaborationRequest, List <string> fields = null, bool?notify = null)
{
collaborationRequest.ThrowIfNull("collaborationRequest")
.Item.ThrowIfNull("collaborationRequest.Item")
.Id.ThrowIfNullOrWhiteSpace("collaborationRequest.Item.Id");
collaborationRequest.AccessibleBy.ThrowIfNull("collaborationRequest.AccessibleBy");
BoxRequest request = new BoxRequest(_config.CollaborationsEndpointUri)
.Method(RequestMethod.Post)
.Param(ParamFields, fields)
.Payload(_converter.Serialize(collaborationRequest));
if (notify.HasValue)
{
var value = notify.Value ? "true" : "false";
request.Param("notify", value);
}
IBoxResponse <BoxCollaboration> response = await ToResponseAsync <BoxCollaboration>(request).ConfigureAwait(false);
return(response.ResponseObject);
}
/// <summary>
/// Used to fetch all results using pagination based on next_marker, V2 is for sort order is an object.
/// </summary>
/// <typeparam name="T">The type of BoxCollectionMarkerBased item to expect.</typeparam>
/// <param name="request">The pre-configured BoxRequest object.</param>
/// <param name="limit">The limit specific to the endpoint.</param>
/// <returns></returns>
protected async Task <BoxCollectionMarkerBasedV2 <T> > AutoPaginateMarkerV2 <T>(BoxRequest request, int limit) where T : BoxEntity, new()
{
var allItemsCollection = new BoxCollectionMarkerBasedV2 <T>();
allItemsCollection.Entries = new List <T>();
bool keepGoing;
do
{
var response = await ToResponseAsync <BoxCollectionMarkerBasedV2 <T> >(request).ConfigureAwait(false);
var newItems = response.ResponseObject;
allItemsCollection.Entries.AddRange(newItems.Entries);
allItemsCollection.Order = newItems.Order;
request.Param("marker", newItems.NextMarker);
keepGoing = !string.IsNullOrWhiteSpace(newItems.NextMarker);
} while (keepGoing);
return(allItemsCollection);
}
/// <summary>
/// Used to add a collaboration for a single user or a single group to a folder.
/// Either an email address, a user ID, or a group id can be used to create the collaboration.
/// If the collaboration is being created with a group, access to this endpoint is granted based on the group's invitability_level.
/// </summary>
/// <param name="collaborationRequest">BoxCollaborationRequest object.</param>
/// <param name="fields">Attribute(s) to include in the response.</param>
/// <param name="notify">Determines if the user, (or all the users in the group) should receive email notification of the collaboration.</param>
/// <returns>The new collaboration object is returned. Errors may occur if the IDs are invalid or if the user does not have permissions to create a collaboration.</returns>
public async Task<BoxCollaboration> AddCollaborationAsync(BoxCollaborationRequest collaborationRequest, List<string> fields = null, bool? notify = null)
{
collaborationRequest.ThrowIfNull("collaborationRequest")
.Item.ThrowIfNull("collaborationRequest.Item")
.Id.ThrowIfNullOrWhiteSpace("collaborationRequest.Item.Id");
collaborationRequest.AccessibleBy.ThrowIfNull("collaborationRequest.AccessibleBy");
collaborationRequest.Role.ThrowIfNullOrWhiteSpace("Role");
BoxRequest request = new BoxRequest(_config.CollaborationsEndpointUri)
.Method(RequestMethod.Post)
.Param(ParamFields, fields)
.Payload(_converter.Serialize(collaborationRequest));
if (notify.HasValue)
{
var value = notify.Value ? "true" : "false";
request.Param("notify", value);
}
IBoxResponse<BoxCollaboration> response = await ToResponseAsync<BoxCollaboration>(request).ConfigureAwait(false);
return response.ResponseObject;
}
/// <summary>
/// Get the list of group memberships for a given user.
/// </summary>
/// <param name="userId">The id of the user to get the list of memberships for.</param>
/// <param name="limit">The number of results to return with this request. Refer to the Box API for defaults.</param>
/// <param name="offset">The offset of the results. Refer to the Box API for more details.</param>
/// <param name="fields">Attribute(s) to include in the response.</param>
/// <param name="autoPaginate">Whether or not to auto-paginate to fetch all group memberships; defaults to false.</param>
/// <returns>A collection of group memberships for the specified user id.</returns>
public async Task<BoxCollection<BoxGroupMembership>> GetAllGroupMembershipsForUserAsync(string userId, int? limit = null, int? offset = null,
List<string> fields = null, bool autoPaginate = false)
{
userId.ThrowIfNullOrWhiteSpace("userId");
BoxRequest request = new BoxRequest(_config.UserEndpointUri, string.Format(Constants.GroupMembershipPathString, userId))
.Param(ParamFields, fields)
.Param("limit", limit.ToString())
.Param("offset", offset.ToString());
if (autoPaginate)
{
if (!limit.HasValue)
{
limit = 100;
request.Param("limit", limit.ToString());
}
if (!offset.HasValue)
request.Param("offset", "0");
return await AutoPaginateLimitOffset<BoxGroupMembership>(request, limit.Value);
}
else
{
IBoxResponse<BoxCollection<BoxGroupMembership>> response = await ToResponseAsync<BoxCollection<BoxGroupMembership>>(request).ConfigureAwait(false);
return response.ResponseObject;
}
}
/// <summary>
/// Retrieves all of the group collaborations for a given group. Note this is only available to group admins.
/// </summary>
/// <param name="groupId">The id of the group to get the list of collaborations for.</param>
/// <param name="limit">The number of results to return with this request. Refer to the Box API for defaults.</param>
/// <param name="offset">The offset of the results. Refer to the Box API for more details.</param>
/// <param name="fields">Attribute(s) to include in the response.</param>
/// <param name="autoPaginate">Whether or not to auto-paginate to fetch all group collaborations; defaults to false.</param>
/// <returns>A collection of collaborations for the specified group id.</returns>
public async Task<BoxCollection<BoxCollaboration>> GetCollaborationsForGroupAsync(string groupId, int? limit = null, int? offset = null,
List<string> fields = null, bool autoPaginate = false)
{
var request = new BoxRequest(_config.GroupsEndpointUri, string.Format(Constants.CollaborationsPathString, groupId))
.Param(ParamFields, fields)
.Param("limit", limit.ToString())
.Param("offset", offset.ToString()); ;
if (autoPaginate)
{
if (!limit.HasValue)
{
limit = 100;
request.Param("limit", limit.ToString());
}
if(!offset.HasValue)
request.Param("offset", "0");
return await AutoPaginateLimitOffset<BoxCollaboration>(request, limit.Value);
}
else
{
var response = await ToResponseAsync<BoxCollection<BoxCollaboration>>(request).ConfigureAwait(false);
return response.ResponseObject;
}
}