/// <summary>
/// Assigns, asynchronously, a license to a specific user or e-mail address and specified <see cref="OS"/>.
/// </summary>
/// <param name="user">The user id (required unless e-mail is specified).</param>
/// <param name="email">The user's e-mail address (required unless user is specified).</param>
/// <param name="os">The <see cref="OS"/> to assign the license to.</param>
/// <returns>Returns a <see cref="AssignLicenseResponse"/>.</returns>
/// <seealso href="https://pushover.net/api/licensing#assign">Pushover API documentation</seealso>
/// <exception cref="InvalidOperationException">When user and email are both null.</exception>
/// <exception cref="ArgumentOutOfRangeException">Invalid <see cref="OS"/> specified.</exception>
public async Task <AssignLicenseResponse> AssignLicenseAsync(string user, string email, OS os)
{
if (user != null)
{
(this.UserOrGroupKeyValidator ?? new UserOrGroupKeyValidator()).Validate("user", user);
}
if (email != null)
{
(this.EmailValidator ?? new EMailValidator()).Validate("email", email);
}
if (user == null && email == null)
{
throw new InvalidOperationException("User or Email required");
}
if (!Enum.IsDefined(typeof(OS), os))
{
throw new ArgumentOutOfRangeException("os");
}
var parameters = new NameValueCollection {
{ "token", this.ApplicationKey },
};
parameters.AddConditional("user", user);
parameters.AddConditional("email", email);
parameters.AddConditional("os", os);
return(await this.Post <AssignLicenseResponse>(GetV1APIUriFromBase("licenses/assign.json"), parameters).ConfigureAwait(false));
}
/// <summary>
/// Sends, asynchronously, the specified <see cref="Message"/> using Pushover to the specified device(s) of the
/// specified user or group.
/// </summary>
/// <param name="message">The <see cref="Message"/> to send.</param>
/// <param name="userOrGroup">The user or group id to send the message to.</param>
/// <param name="deviceNames">The devicenames to send the message to.</param>
/// <returns>Returns the <see cref="PushoverUserResponse"/> returned by the server.</returns>
/// <seealso href="https://pushover.net/api#messages">Pushover API documentation</seealso>
/// <exception cref="ArgumentNullException">Thrown when message or user/group arguments are null.</exception>
/// <exception cref="InvalidKeyException">Thrown when an invalid user/group is specified.</exception>
public async Task <PushoverUserResponse> SendMessageAsync(Message message, string userOrGroup, string[] deviceNames)
{
(this.MessageValidator ?? new DefaultMessageValidator()).Validate("message", message);
(this.UserOrGroupKeyValidator ?? new UserOrGroupKeyValidator()).Validate("userOrGroup", userOrGroup);
if (deviceNames != null && deviceNames.Length > 0)
{
foreach (var device in deviceNames)
{
(this.DeviceNameValidator ?? new DeviceNameValidator()).Validate("device", device);
}
}
var parameters = new NameValueCollection {
{ "token", this.ApplicationKey },
{ "user", userOrGroup },
{ "message", message.Body }
};
parameters.Add("priority", (int)message.Priority);
parameters.AddConditional("device", deviceNames);
parameters.AddConditional("title", message.Title);
parameters.AddConditional("sound", message.Sound);
parameters.AddConditional("html", message.IsHtmlBody);
if (message.SupplementaryUrl != null)
{
parameters.Add("url", message.SupplementaryUrl.Uri);
parameters.AddConditional("url_title", message.SupplementaryUrl.Title);
}
if (message.Priority == Priority.Emergency)
{
parameters.Add("retry", message.RetryOptions.RetryEvery);
parameters.Add("expire", message.RetryOptions.RetryPeriod);
parameters.Add("callback", message.RetryOptions.CallBackUrl);
}
if (message.Timestamp != null)
{
parameters.Add("timestamp", (int)(TimeZoneInfo.ConvertTimeToUtc(message.Timestamp.Value).Subtract(EPOCH).TotalSeconds));
}
return(await this.Post <PushoverUserResponse>(GetV1APIUriFromBase("messages.json"), parameters).ConfigureAwait(false));
}
/// <summary>
/// Migrates, asynchronously, a specific subscription to a user/group and limits it to a specified device, setting the user's preferred default sound.
/// </summary>
/// <param name="subscription">Subscription code to migrate.</param>
/// <param name="user">User code to migrate the subscription to.</param>
/// <param name="device">The device name that the subscription should be limited to.</param>
/// <param name="sound">The user's preferred default sound.</param>
/// <returns>Returns a <see cref="MigrateSubscriptionResponse"/>.</returns>
/// <remarks>Applications that formerly collected Pushover user keys are encouraged to migrate to subscription keys.</remarks>
/// <seealso href="https://pushover.net/api/subscriptions#migration">Pushover API documentation</seealso>
/// <exception cref="ArgumentNullException">Thrown when subscription or user is null.</exception>
/// <exception cref="InvalidKeyException">Thrown when user or devicename are invalid.</exception>
public async Task <MigrateSubscriptionResponse> MigrateSubscriptionAsync(string subscription, string user, string device, string sound)
{
if (string.IsNullOrEmpty(subscription))
{
throw new ArgumentNullException("subscription");
}
(this.UserOrGroupKeyValidator ?? new UserOrGroupKeyValidator()).Validate("user", user);
if (device != null)
{
(this.DeviceNameValidator ?? new DeviceNameValidator()).Validate("device", device);
}
var parameters = new NameValueCollection {
{ "token", this.ApplicationKey },
{ "subscription", subscription },
{ "user", user },
};
parameters.AddConditional("device_name", device);
parameters.AddConditional("sound", sound);
return(await this.Post <MigrateSubscriptionResponse>(GetV1APIUriFromBase("subscriptions/migrate.json"), parameters).ConfigureAwait(false));
}