/// <summary>
/// Gets information about the HealthVault service.
/// </summary>
///
/// <param name="connection">The connection to use to perform the operation. </param>
///
/// <remarks>
/// Gets the latest information about the HealthVault service. This
/// includes:<br/>
/// - The version of the service.<br/>
/// - The SDK assembly URLs.<br/>
/// - The SDK assembly versions.<br/>
/// - The SDK documentation URL.<br/>
/// - The URL to the HealthVault Shell.<br/>
/// - The schema definition for the HealthVault method's request and
/// response.
/// - The common schema definitions for types that the HealthVault methods
/// use.<br/>
/// </remarks>
///
/// <returns>
/// A <see cref="ServiceInfo"/> instance that contains the service version, SDK
/// assemblies versions and URLs, method information, and so on.
/// </returns>
///
/// <exception cref="HealthServiceException">
/// The HealthVault service returns an error.
/// </exception>
///
/// <exception cref="UriFormatException">
/// One or more URL strings returned by HealthVault is invalid.
/// </exception>
///
public static ServiceInfo GetServiceDefinition(HealthServiceConnection connection)
{
return HealthVaultPlatformInformation.Current.GetServiceDefinition(connection);
}
/// <summary>
/// Gets the definitions for one or more health record item type definitions
/// supported by HealthVault.
/// </summary>
///
/// <param name="typeIds">
/// A collection of health item type IDs whose details are being requested. Null
/// indicates that all health item types should be returned.
/// </param>
///
/// <param name="sections">
/// A collection of HealthRecordItemTypeSections enumeration values that indicate the type
/// of details to be returned for the specified health item records(s).
/// </param>
///
/// <param name="imageTypes">
/// A collection of strings that identify which health item record images should be
/// retrieved.
///
/// This requests an image of the specified mime type should be returned. For example,
/// to request a GIF image, "image/gif" should be specified. For icons, "image/vnd.microsoft.icon"
/// should be specified. Note, not all health item records will have all image types and
/// some may not have any images at all.
///
/// If '*' is specified, all image types will be returned.
/// </param>
///
/// <param name="lastClientRefreshDate">
/// A <see cref="DateTime"/> instance that specifies the time of the last refresh
/// made by the client.
/// </param>
///
/// <param name="connection">
/// A connection to the HealthVault service.
/// </param>
///
/// <returns>
/// The type definitions for the specified types, or empty if the
/// <paramref name="typeIds"/> parameter does not represent a known unique
/// type identifier.
/// </returns>
///
/// <remarks>
/// This method calls the HealthVault service if the types are not
/// already in the client-side cache.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// If <paramref name="typeIds"/> is <b>null</b> and empty, or
/// <paramref name="typeIds"/> is <b>null</b> and member in <paramref name="typeIds"/> is
/// <see cref="System.Guid.Empty"/>.
/// </exception>
///
/// <exception cref="ArgumentNullException">
/// If <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
///
public static IDictionary<Guid, HealthRecordItemTypeDefinition> GetHealthRecordItemTypeDefinition(
IList<Guid> typeIds,
HealthRecordItemTypeSections sections,
IList<String> imageTypes,
DateTime? lastClientRefreshDate,
HealthServiceConnection connection)
{
return HealthVaultPlatform.GetHealthRecordItemTypeDefinition(
typeIds,
sections,
imageTypes,
lastClientRefreshDate,
connection);
}
/// <summary>
/// Gets the definition of one or more health record item type definitions
/// supported by HealthVault.
/// </summary>
///
/// <param name="typeIds">
/// The unique identifiers for the type to get the definition of.
/// </param>
///
/// <param name="connection">
/// A connection to the HealthVault service.
/// </param>
///
/// <returns>
/// The type definitions for the specified types, or empty if the
/// <paramref name="typeIds"/> parameter does not represent a known unique
/// type identifier.
/// </returns>
///
/// <remarks>
/// This method calls the HealthVault service if the types are not
/// already in the client-side cache.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// If <paramref name="typeIds"/> is <b>null</b> and empty, or
/// <paramref name="typeIds"/> is <b>null</b> and member in <paramref name="typeIds"/> is
/// <see cref="System.Guid.Empty"/>.
/// </exception>
///
/// <exception cref="ArgumentNullException">
/// If <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
///
public static IDictionary<Guid, HealthRecordItemTypeDefinition> GetHealthRecordItemTypeDefinition(
IList<Guid> typeIds,
HealthServiceConnection connection)
{
return GetHealthRecordItemTypeDefinition(typeIds,
HealthRecordItemTypeSections.All,
connection);
}
/// <summary>
/// Creates a new instance of the <see cref="HealthServiceRequest"/>
/// class for the specified method.
/// </summary>
///
/// <param name="connection">
/// The client-side representation of the HealthVault service.
/// </param>
///
/// <param name="methodName">
/// The name of the method to invoke on the service.
/// </param>
///
/// <param name="methodVersion">
/// The version of the method to invoke on the service.
/// </param>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
///
/// <exception cref="ArgumentException">
/// The <paramref name="methodName"/> parameter is <b>null</b> or empty.
/// </exception>
///
public HealthServiceRequest(
HealthServiceConnection connection,
string methodName,
int methodVersion)
{
Validator.ThrowIfArgumentNull(connection, "connection", "CtorServiceNull");
Validator.ThrowIfStringNullOrEmpty(methodName, "methodName");
_connection = connection;
AuthenticatedConnection authenticatedConnection = connection as AuthenticatedConnection;
if (authenticatedConnection != null)
{
ImpersonatedPersonId = authenticatedConnection.ImpersonatedPersonId;
}
List<HealthServiceRequest> pendingRequests = connection.PendingRequests;
lock (pendingRequests)
{
connection.PendingRequests.Add(this);
}
_methodName = methodName;
_timeoutSeconds = connection.RequestTimeoutSeconds;
_msgTimeToLive = connection.RequestTimeToLive;
_language = connection.Culture.TwoLetterISOLanguageName;
string[] langAndCountry = connection.Culture.Name.Split('-');
if (langAndCountry.Length > 1)
{
_country = langAndCountry[1];
}
_methodVersion = methodVersion;
}
/// <summary>
/// Gets the requested health record item type definitions supported by HealthVault
/// only if they have been updated since the specified last client refresh date.
/// </summary>
///
/// <param name="typeIds">
/// A collection of health item type IDs whose details are being requested. Null
/// indicates that all health item types should be returned.
/// </param>
///
/// <param name="sections">
/// A collection of HealthRecordItemTypeSections enumeration values that indicate the type of
/// details to be returned for the specified health item record(s).
/// </param>
///
/// <param name="lastClientRefreshDate">
/// A <see cref="DateTime"/> instance that specifies the time of the last refresh
/// made by the client.
/// </param>
///
/// <param name="connection">
/// A connection to the HealthVault service.
/// </param>
///
/// <returns>
/// The type definitions for the specified types, or empty if the
/// <paramref name="typeIds"/> parameter does not represent a known unique
/// type identifier.
/// </returns>
///
/// <remarks>
/// This method calls the HealthVault service if the types are not
/// already in the client-side cache.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// If <paramref name="typeIds"/> is <b>null</b> and empty, or
/// <paramref name="typeIds"/> is <b>null</b> and member in <paramref name="typeIds"/> is
/// <see cref="System.Guid.Empty"/>.
/// </exception>
///
/// <exception cref="ArgumentNullException">
/// If <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
///
public static IDictionary<Guid, HealthRecordItemTypeDefinition> GetHealthRecordItemTypeDefinition(
IList<Guid> typeIds,
HealthRecordItemTypeSections sections,
DateTime? lastClientRefreshDate,
HealthServiceConnection connection)
{
return GetHealthRecordItemTypeDefinition(typeIds,
sections,
null,
lastClientRefreshDate,
connection);
}
/// <summary>
/// Gets the application configuration information for the calling application.
/// </summary>
///
/// <param name="connection">The connection to use to perform the operation. This connection
/// must be application level. </param>
///
/// <param name="allLanguages">
/// A boolean value indicating whether the localized values all languages should be
/// returned, just one language. This affects all properties which can have multiple
/// localized values, including <see cref="ApplicationInfo.CultureSpecificNames"/>,
/// <see cref="ApplicationInfo.CultureSpecificDescriptions"/>,
/// <see cref="ApplicationInfo.CultureSpecificAuthorizationReasons"/>,
/// <see cref="ApplicationInfo.LargeLogo"/>,
/// <see cref="ApplicationInfo.SmallLogo"/>,
/// <see cref="ApplicationInfo.PrivacyStatement"/>,
/// <see cref="ApplicationInfo.TermsOfUse"/>,
/// and <see cref="ApplicationInfo.DtcSuccessMessage"/>
/// </param>
///
/// <returns>
/// An ApplicationInfo object for the calling application.
/// </returns>
///
/// <remarks>
/// This method always calls the HealthVault service to get the latest
/// information. It returns installation configuration about the calling
/// application.
/// </remarks>
///
/// <exception cref="HealthServiceException">
/// The HealthVault service returns an error.
/// </exception>
///
public static ApplicationInfo GetApplicationInfo(
HealthServiceConnection connection,
Boolean allLanguages)
{
return HealthVaultPlatformApplication.Current.GetApplicationInfo(connection, allLanguages);
}
/// <summary>
/// Gets the application settings for the current application and
/// person.
/// </summary>
///
/// <param name="connection">The connection to use to perform the operation. This connection
/// must be authenticated. </param>
///
/// <returns>
/// The application settings XML.
/// </returns>
///
/// <remarks>
/// This might be <b>null</b> if no application settings have been
/// stored for the application or user.
/// </remarks>
///
public static IXPathNavigable GetApplicationSettingsAsXml(HealthServiceConnection connection)
{
return HealthVaultPlatformPerson.Current.GetApplicationSettings(connection).XmlSettings;
}
/// <summary>
/// Generates a new signup code that should be passed to HealthVault Shell in order
/// to create a new user account.
/// </summary>
///
/// <param name="connection">The connection to use to perform the operation. This connection
/// must be application level. </param>
///
/// <returns>
/// A signup code that can be used to create an account.
/// </returns>
///
public static string NewSignupCode(HealthServiceConnection connection)
{
return HealthVaultPlatformApplication.Current.NewSignupCode(connection);
}
/// <summary>
/// Searches a specific vocabulary and retrieves the matching vocabulary items.
/// </summary>
///
/// <remarks>
/// This method does text search matching of display text and abbreviation text
/// for the culture defined by the <see cref="HealthServiceConnection.Culture"/>.
/// The <paramref name="searchValue"/> is a string of characters in the specified
/// culture.
/// </remarks>
///
/// <param name="connection">
/// The connection to use for this operation. The connection
/// must have application capability.
/// </param>
///
/// <param name="vocabularyKey">
/// The <see cref="VocabularyKey"/> defining the vocabulary to search. If the
/// family is not specified, the default HealthVault vocabulary family is used.
/// If the version is not specified, the most current version of the vocabulary
/// is used.
/// </param>
///
/// <param name="searchValue">
/// The search string to use.
/// </param>
///
/// <param name="searchType">
/// The type of search to perform.
/// </param>
///
/// <param name="maxResults">
/// The maximum number of results to return. If null, all matching results
/// are returned, up to a maximum number defined by the service config
/// value with key maxResultsPerVocabularyRetrieval.
/// </param>
///
/// <returns>
/// A <see cref="VocabularyItemCollection"/> populated with entries matching
/// the search criteria.
/// </returns>
///
/// <exception cref="ArgumentException">
/// If <paramref name="vocabularyKey"/> is <b>null</b>.
/// <br></br>
/// -Or-
/// <br></br>
/// If <paramref name="searchValue"/> is <b>null</b> or empty or greater
/// than <b>255</b> characters.
/// <br></br>
/// -Or-
/// <br></br>
/// if <paramref name="searchType"/> is not a known
/// <see cref="VocabularySearchType"/> value.
/// <br></br>
/// -Or-
/// <br></br>
/// when <paramref name="maxResults"/> is defined but has a value less than 1.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// There is an error in the server request.
/// <br></br>
/// -Or-
/// <br></br>
/// The requested vocabulary is not found on the server.
/// <br></br>
/// -Or-
/// The requested search culture is not supported.
/// </exception>
///
public static VocabularyItemCollection SearchVocabulary(
HealthServiceConnection connection,
VocabularyKey vocabularyKey,
string searchValue,
VocabularySearchType searchType,
int? maxResults)
{
Validator.ThrowIfArgumentNull(vocabularyKey, "vocabularyKey", "VocabularyKeyNullOrEmpty");
VocabularyItemCollection matchingVocabulary;
ReadOnlyCollection<VocabularyKey> matchingKeys;
HealthVaultPlatformVocabulary.Current.SearchVocabulary(
connection,
vocabularyKey,
searchValue,
searchType,
maxResults,
out matchingVocabulary,
out matchingKeys);
return matchingVocabulary;
}
/// <summary>
/// Retrieves lists of vocabulary items for the specified
/// vocabularies and culture.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection
/// must have application capability.
/// </param>
///
/// <param name="vocabularyKeys">
/// A list of keys identifying the requested vocabularies.
/// </param>
///
/// <param name="cultureIsFixed">
/// HealthVault looks for the vocabulary items for the culture info
/// specified using <see cref="HealthServiceConnection.Culture"/>.
/// If <paramref name="cultureIsFixed"/> is set to <b>false</b> and if
/// items are not found for the specified culture, items for the
/// default fallback culture are returned. If
/// <paramref name="cultureIsFixed"/> is set to <b>true</b>,
/// fallback will not occur, and if items are not found for the
/// specified culture, empty strings are returned.
/// </param>
///
/// <returns>
/// The specified vocabularies and their items, or empty strings.
/// </returns>
///
/// <exception cref="ArgumentException">
/// The <paramref name="vocabularyKeys"/> list is empty.
/// </exception>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="vocabularyKeys"/> list is <b>null</b>
/// or contains a <b>null</b> entry.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// There is an error in the server request.
/// <br></br>
/// -Or-
/// <br></br>
/// One of the requested vocabularies is not found on the server.
/// <br></br>
/// -Or-
/// <br></br>
/// One of the requested vocabularies does not contain representations
/// for its items for the specified culture when
/// <paramref name="cultureIsFixed"/> is <b>true</b>.
/// <br></br>
/// -Or-
/// <br></br>
/// There is an error loading the vocabulary.
/// </exception>
///
public static ReadOnlyCollection<Vocabulary> GetVocabulary(
HealthServiceConnection connection,
IList<VocabularyKey> vocabularyKeys,
bool cultureIsFixed)
{
return HealthVaultPlatformVocabulary.Current.GetVocabulary(
connection,
vocabularyKeys,
cultureIsFixed);
}
/// <summary>
/// Retrieves a collection of key information for identifying and
/// describing the vocabularies in the system.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection
/// must have application capability.
/// </param>
///
/// <returns>
/// A collection of keys identifying the vocabularies in the system.
/// </returns>
///
public static ReadOnlyCollection<VocabularyKey> GetVocabularyKeys(HealthServiceConnection connection)
{
return HealthVaultPlatformVocabulary.Current.GetVocabularyKeys(connection);
}
/// <summary>
/// Retrieves a list of vocabulary items for the specified vocabulary
/// and culture.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection
/// must have application capability.
/// </param>
///
/// <param name="vocabularyKey">
/// A key identifying the vocabulary requested.
/// </param>
///
/// <param name="cultureIsFixed">
/// HealthVault looks for the vocabulary items for the culture info
/// specified using <see cref="HealthServiceConnection.Culture"/>.
/// If <paramref name="cultureIsFixed"/> is set to <b>false</b> and if
/// items are not found for the specified culture, items for the
/// default fallback culture are returned. If
/// <paramref name="cultureIsFixed"/> is set to <b>true</b>,
/// fallback will not occur, and if items are not found for the
/// specified culture, empty strings are returned.
/// </param>
///
/// <returns>
/// The specified vocabulary and its items, or empty strings.
/// </returns>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="vocabularyKey"/> is <b>null</b>.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// There is an error in the server request.
/// <br></br>
/// -Or-
/// <br></br>
/// The requested vocabulary is not found on the server.
/// <br></br>
/// -Or-
/// <br></br>
/// The requested vocabulary does not contain representations
/// for its items for the specified culture when
/// <paramref name="cultureIsFixed"/> is <b>true</b>.
/// <br></br>
/// -Or-
/// <br></br>
/// There is an error loading the vocabulary.
/// </exception>
///
public static Vocabulary GetVocabulary(
HealthServiceConnection connection,
VocabularyKey vocabularyKey,
bool cultureIsFixed)
{
ReadOnlyCollection<Vocabulary> vocabularies =
GetVocabulary(
connection,
new VocabularyKey[] { vocabularyKey },
cultureIsFixed);
return vocabularies[0];
}
/// <summary>
/// Retrieves a list of vocabulary items for the specified vocabulary.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection
/// must have application capability.
/// </param>
///
/// <param name="name">
/// The name of the vocabulary requested.
/// </param>
/// <returns>
/// The requested vocabulary and its items.
/// </returns>
///
/// <exception cref="ArgumentException">
/// The <paramref name="name" /> parameter <b>null</b> or an empty
/// string.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// There is an error in the server request.
/// <br></br>
/// -Or-
/// <br></br>
/// One of the requested vocabularies is not found on the server.
/// <br></br>
/// -Or-
/// <br></br>
/// -Or-
/// <br></br>
/// There is an error loading the vocabulary.
/// </exception>
///
public static Vocabulary GetVocabulary(
HealthServiceConnection connection,
string name)
{
Validator.ThrowIfStringNullOrEmpty(name, "name");
VocabularyKey key = new VocabularyKey(name);
return GetVocabulary(connection, key, false);
}
/// <summary>
/// Gets a list of health record IDs for the current application,
/// that optionally have been updated since a specified date.
/// </summary>
///
/// <param name="connection">The connection to use to perform the operation. This connection
/// must be application level. </param>
///
/// <param name="updatedDate">
/// Date that is used to filter health record IDs according to whether or not they have
/// been updated since the specified date.
/// </param>
///
/// <returns>
/// List of health record IDs filtered by any specified input parameters.
/// </returns>
///
public static IList<Guid> GetUpdatedRecordsForApplication(
HealthServiceConnection connection,
DateTime? updatedDate)
{
return HealthVaultPlatformApplication.Current.GetUpdatedRecordsForApplication(connection, updatedDate);
}
/// <summary>
/// Sets the application settings for the current application and
/// person.
/// </summary>
///
/// <param name="connection">The connection to use to perform the operation. This connection
/// must be authenticated. </param>
///
/// <param name="applicationSettings">
/// The application settings XML.
/// </param>
///
/// <remarks>
/// This may be <b>null</b> if no application settings have been
/// stored for the application or user.
/// </remarks>
///
public static void SetApplicationSettings(
HealthServiceConnection connection,
IXPathNavigable applicationSettings)
{
string requestParameters =
HealthVaultPlatformPerson.GetSetApplicationSettingsParameters(applicationSettings);
HealthVaultPlatformPerson.Current.SetApplicationSettings(connection, requestParameters);
}
/// <summary>
/// Searches the keys of vocabularies defined by the HealthVault service.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection
/// must have application capability.
/// </param>
///
/// <remarks>
/// This method does a text search of vocabulary names and descriptions.
/// </remarks>
///
/// <param name="searchValue">
/// The search string to use.
/// </param>
///
/// <param name="searchType">
/// The type of search to perform.
/// </param>
///
/// <param name="maxResults">
/// The maximum number of results to return. If null, all matching results
/// are returned, up to a maximum number defined by the service config
/// value with key maxResultsPerVocabularyRetrieval.
/// </param>
///
/// <returns>
/// A <b>ReadOnlyCollection</b> of <see cref="VocabularyKey"/> with entries
/// matching the search criteria.
/// </returns>
///
/// <exception cref="ArgumentException">
/// If <paramref name="searchValue"/> is <b>null</b> or empty or greater
/// than <b>255</b> characters.
/// <br></br>
/// -Or-
/// <br></br>
/// if <paramref name="searchType"/> is not a known
/// <see cref="VocabularySearchType"/> value.
/// <br></br>
/// -Or-
/// <br></br>
/// when <paramref name="maxResults"/> is defined but has a value less than 1.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// There is an error in the server request.
/// </exception>
///
public static ReadOnlyCollection<VocabularyKey> SearchVocabularyKeys(
HealthServiceConnection connection,
string searchValue,
VocabularySearchType searchType,
int? maxResults)
{
ReadOnlyCollection<VocabularyKey> matchingKeys;
VocabularyItemCollection matchingVocabulary;
HealthVaultPlatformVocabulary.Current.SearchVocabulary(
connection,
null,
searchValue,
searchType,
maxResults,
out matchingVocabulary,
out matchingKeys);
return matchingKeys;
}
/// <summary>
/// Gets the application configuration information for the calling application.
/// </summary>
///
/// <param name="connection">The connection to use to perform the operation. This connection
/// must be application-level. </param>
///
/// <returns>
/// An ApplicationInfo object for the calling application.
/// </returns>
///
/// <remarks>
/// This method always calls the HealthVault service to get the latest
/// information. It returns installation configuration about the calling
/// application.
/// </remarks>
///
/// <exception cref="HealthServiceException">
/// The HealthVault service returns an error.
/// </exception>
///
public static ApplicationInfo GetApplicationInfo(HealthServiceConnection connection)
{
return HealthVaultPlatformApplication.Current.GetApplicationInfo(connection, false);
}
/// <summary>
/// Sends an insecure message to the specified message recipients.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection must
/// have application capabilities.
/// </param>
///
/// <param name="mailRecipient">
/// The addresses and display names of the people to send the
/// message to.
/// </param>
///
/// <param name="subject">
/// The subject of the message.
/// </param>
///
/// <param name="textBody">
/// The text body of the message.
/// </param>
///
/// <param name="htmlBody">
/// The HTML body of the message.
/// </param>
///
/// <remarks>
/// If both the <paramref name="textBody"/> and
/// <paramref name="htmlBody"/> of the message is specified then a
/// multi-part message will be sent so that the html body will be used
/// and fallback to text if not supported by the client.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// The <paramref name="mailRecipient"/> property is <b>null</b> or empty,
/// or the <paramref name="subject"/> parameter is <b>null</b> or empty, or
/// the <paramref name="textBody"/> and <paramref name="htmlBody"/>
/// parameters are both <b>null</b> or empty.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// The server returned a failure when making the request.
/// </exception>
///
public static void SendInsecureMessage(
HealthServiceConnection connection,
IList<MailRecipient> mailRecipient,
string subject,
string textBody,
string htmlBody)
{
HealthVaultPlatformMessage.Current.SendInsecureMessage(
connection,
mailRecipient,
null,
null,
true,
subject,
textBody,
htmlBody);
}
/// <summary>
/// Gets the application settings for the current application and
/// person.
/// </summary>
///
/// <param name="connection">The connection to use to perform the operation. This connection
/// must be authenticated. </param>
///
/// <returns>
/// The complete set application settings including the XML settings, selected record ID, etc.
/// </returns>
///
public static ApplicationSettings GetApplicationSettings(HealthServiceConnection connection)
{
return HealthVaultPlatformPerson.Current.GetApplicationSettings(connection);
}
/// <summary>
/// Sends an insecure message to the specified message recipients.
/// </summary>
///
/// <param name="personIds">
/// The unique identifiers of the people to which the message should be
/// sent.
/// </param>
///
/// <param name="addressMustBeValidated">
/// <b>true</b> if HealthVault ensures that the person has validated
/// their message address before sending the mail; <b>false</b> if the
/// message will be sent even if the person's address has not been
/// validated.
/// </param>
///
/// <param name="connection">
/// The connection to use for this operation. The connection must
/// have application capabilities.
/// </param>
///
/// <param name="subject">
/// The subject of the message.
/// </param>
///
/// <param name="textBody">
/// The text body of the message.
/// </param>
///
/// <param name="htmlBody">
/// The HTML body of the message.
/// </param>
///
/// <remarks>
/// If both the <paramref name="textBody"/> and
/// <paramref name="htmlBody"/> of the message is specified then a
/// multi-part message will be sent so that the html body will be used
/// and fallback to text if not supported by the client.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// The <paramref name="personIds"/> or <paramref name="subject"/>,
/// <paramref name="textBody"/> or <paramref name="htmlBody"/> parameters
/// are <b>null</b> or empty.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// The server returned a failure when making the request.
/// </exception>
///
public static void SendInsecureMessage(
HealthServiceConnection connection,
IList<Guid> personIds,
bool addressMustBeValidated,
string subject,
string textBody,
string htmlBody)
{
HealthVaultPlatformMessage.Current.SendInsecureMessage(
connection,
null,
personIds,
null,
addressMustBeValidated,
subject,
textBody,
htmlBody);
}
/// <summary>
/// Creates a new instance of the <see cref="HealthServiceRequest"/>
/// class for the specified method.
/// </summary>
///
/// <param name="connection">
/// The client-side representation of the HealthVault service.
/// </param>
///
/// <param name="methodName">
/// The name of the method to invoke on the service.
/// </param>
///
/// <param name="methodVersion">
/// The version of the method to invoke on the service.
/// </param>
///
/// <param name="record">
/// The record to use.
/// </param>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
///
/// <exception cref="ArgumentException">
/// The <paramref name="methodName"/> parameter is <b>null</b> or empty.
/// </exception>
///
public HealthServiceRequest(
HealthServiceConnection connection,
string methodName,
int methodVersion,
HealthRecordAccessor record)
: this(connection, methodName, methodVersion)
{
_recordId = record.Id;
}
/// <summary>
/// Sends an insecure message originating from the application to
/// the specified message recipients.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection must
/// have application capabilities.
/// </param>
///
/// <param name="mailRecipient">
/// The addresses and display names of the people to send the
/// message to.
/// </param>
///
/// <param name="senderMailboxName">
/// An application specified mailbox name that's sending the message.
/// The mailbox name is appended to the application's domain name to
/// form the From email address of the message. This parameter should
/// only contain the characters before the @ symbol of the email
/// address.
/// </param>
///
/// <param name="senderDisplayName">
/// The message sender's display name.
/// </param>
///
/// <param name="subject">
/// The subject of the message.
/// </param>
///
/// <param name="textBody">
/// The text body of the message.
/// </param>
///
/// <param name="htmlBody">
/// The HTML body of the message.
/// </param>
///
/// <remarks>
/// If both the <paramref name="textBody"/> and
/// <paramref name="htmlBody"/> of the message is specified then a
/// multi-part message will be sent so that the html body will be used
/// and fallback to text if not supported by the client.
///
/// If the domain name of the application has not been previously
/// set (usually through app registration), this method will throw
/// a <see cref="HealthServiceException"/>.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// If <paramref name="mailRecipient"/> is null or empty,
/// -or-
/// if <paramref name="senderMailboxName"/> is null or empty,
/// -or-
/// if <paramref name="senderDisplayName"/> is null or empty,
/// -or-
/// if <paramref name="subject"/> is null or empty,
/// -or-
/// if <paramref name="textBody"/> and <paramref name="htmlBody"/>
/// are both null or empty.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// If the server returned a failure when making the request.
/// </exception>
///
public static void SendInsecureMessageFromApplication(
HealthServiceConnection connection,
IList<MailRecipient> mailRecipient,
string senderMailboxName,
string senderDisplayName,
string subject,
string textBody,
string htmlBody)
{
HealthVaultPlatformMessage.Current.SendInsecureMessageFromApplication(
connection,
mailRecipient,
null,
null,
true,
senderMailboxName,
senderDisplayName,
subject,
textBody,
htmlBody);
}
/// <summary>
/// Gets the health record item type definition for the base item type.
/// </summary>
///
/// <param name="connection">
/// A connection to the HealthVault service.
/// </param>
///
/// <remarks>
/// The base item type is a constructed item type that contains
/// definitions of the standard item transforms that will work
/// for any item type. If a specific item type does not define a
/// standard transformation, the base item type transformation can
/// be used instead.
/// <br/><br/>
/// This method calls the HealthVault service if the type is not
/// already in the client-side cache.
/// </remarks>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
///
public static HealthRecordItemTypeDefinition GetBaseHealthRecordItemTypeDefinition(
HealthServiceConnection connection)
{
return GetHealthRecordItemTypeDefinition(_baseTypeId, connection);
}
/// <summary>
/// Sends an insecure message originating from the application
/// to the specified message recipients.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection must
/// have application capabilities.
/// </param>
///
/// <param name="recipientPersonIds">
/// The unique identifiers of the people to which the message should be
/// sent.
/// </param>
///
/// <param name="addressMustBeValidated">
/// If true, HealthVault will ensure that the person has validated
/// their message address before sending the mail. If false, the
/// message will be sent even if the person's address has not been
/// validated.
/// </param>
///
/// <param name="senderMailboxName">
/// An application specified mailbox name that's sending the message.
/// The mailbox name is appended to the application's domain name to
/// form the From email address of the message. This parameter should
/// only contain the characters before the @ symbol of the email
/// address.
/// </param>
///
/// <param name="senderDisplayName">
/// The message sender's display name.
/// </param>
///
/// <param name="subject">
/// The subject of the message.
/// </param>
///
/// <param name="textBody">
/// The text body of the message.
/// </param>
///
/// <param name="htmlBody">
/// The HTML body of the message.
/// </param>
///
/// <remarks>
/// If both the <paramref name="textBody"/> and
/// <paramref name="htmlBody"/> of the message is specified then a
/// multi-part message will be sent so that the html body will be used
/// and fallback to text if not supported by the client.
///
/// If the domain name of the application has not been previously
/// set (usually through app registration), this method will throw
/// a <see cref="HealthServiceException"/>.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// If <paramref name="recipientPersonIds"/> is null or empty,
/// -or-
/// if <paramref name="senderMailboxName"/> is null or empty,
/// -or-
/// if <paramref name="senderDisplayName"/> is null or empty,
/// -or-
/// if <paramref name="subject"/> is null or empty,
/// -or-
/// if <paramref name="textBody"/> and <paramref name="htmlBody"/>
/// are both null or empty.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// If the server returned a failure when making the request.
/// </exception>
///
public static void SendInsecureMessageFromApplication(
HealthServiceConnection connection,
IList<Guid> recipientPersonIds,
bool addressMustBeValidated,
string senderMailboxName,
string senderDisplayName,
string subject,
string textBody,
string htmlBody)
{
HealthVaultPlatformMessage.Current.SendInsecureMessageFromApplication(
connection,
null,
recipientPersonIds,
null,
addressMustBeValidated,
senderMailboxName,
senderDisplayName,
subject,
textBody,
htmlBody);
}
/// <summary>
/// Gets the definitions for all health record item type definitions
/// supported by HealthVault.
/// </summary>
///
/// <param name="sections">
/// A collection of HealthRecordItemTypeSections enumeration values that indicate the type of
/// details to be returned for the specified health item record(s).
/// </param>
///
/// <param name="connection">
/// A connection to the HealthVault service.
/// </param>
///
/// <returns>
/// The type definitions for all the health record item type definitions
/// supported by HealthVault.
/// </returns>
///
/// <remarks>
/// This method calls the HealthVault service if the types are not
/// already in the client-side cache.
/// </remarks>
///
/// <exception cref="ArgumentNullException">
/// If <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
///
public static IDictionary<Guid, HealthRecordItemTypeDefinition> GetHealthRecordItemTypeDefinition(
HealthRecordItemTypeSections sections,
HealthServiceConnection connection)
{
return GetHealthRecordItemTypeDefinition(null, sections, null, null, connection);
}
/// <summary>
/// Sends an insecure message to custodians of the specified health
/// record.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection must
/// have application capabilities.
/// </param>
///
/// <param name="recordId">
/// The unique identifier of the health record for which the
/// custodians should be sent the message.
/// </param>
///
/// <param name="addressMustBeValidated">
/// <b>true</b> if HealthVault ensures that the person has validated
/// their message address before sending the mail; <b>false</b> if the
/// message will be sent even if the person's address has not been
/// validated.
/// </param>
///
/// <param name="subject">
/// The subject of the message.
/// </param>
///
/// <param name="textBody">
/// The text body of the message.
/// </param>
///
/// <param name="htmlBody">
/// The HTML body of the message.
/// </param>
///
/// <remarks>
/// If both the <paramref name="textBody"/> and
/// <paramref name="htmlBody"/> of the message is specified, then a
/// multi-part message is sent so that the HTML body will be used
/// and falls back to text if not supported by the client.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// The <paramref name="recordId"/> parameter is <see cref="System.Guid.Empty"/>
/// -or-
/// The <paramref name="subject"/> parameter is <b>null</b> or empty,
/// -or-
/// The <paramref name="textBody"/> and <paramref name="htmlBody"/> parameters
/// are both <b>null</b> or empty.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// The server returned a failure when making the request.
/// </exception>
///
public static void SendInsecureMessageToCustodians(
HealthServiceConnection connection,
Guid recordId,
bool addressMustBeValidated,
string subject,
string textBody,
string htmlBody)
{
HealthVaultPlatformMessage.Current.SendInsecureMessage(
connection,
null,
null,
recordId,
addressMustBeValidated,
subject,
textBody,
htmlBody);
}
/// <summary>
/// Gets the definition for a health record item type.
/// </summary>
///
/// <param name="typeId">
/// The unique identifier for the type to get the definition of.
/// </param>
///
/// <param name="connection">
/// A connection to the HealthVault service.
/// </param>
///
/// <returns>
/// The type definition for the specified type, or <b>null</b> if the
/// <paramref name="typeId"/> parameter does not represent a known unique
/// type identifier.
/// </returns>
///
/// <remarks>
/// This method calls the HealthVault service if the type is not
/// already in the client-side cache.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// The <paramref name="typeId"/> parameter is Guid.Empty.
/// </exception>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
///
public static HealthRecordItemTypeDefinition GetHealthRecordItemTypeDefinition(
Guid typeId,
HealthServiceConnection connection)
{
IDictionary<Guid, HealthRecordItemTypeDefinition> typeDefs =
GetHealthRecordItemTypeDefinition(new Guid[] { typeId }, connection);
return typeDefs[typeId];
}
/// <summary>
/// Sends an insecure message originating from the application
/// to custodians of the specified health record.
/// </summary>
///
/// <param name="connection">
/// The connection to use for this operation. The connection must
/// have application capabilities.
/// </param>
///
/// <param name="recordId">
/// The unique identifier of the health record for which the
/// custodians should be sent the message.
/// </param>
///
/// <param name="addressMustBeValidated">
/// If true, HealthVault will only send the message to custodians with
/// validated e-mail addresses. If false, the message will
/// be sent even if the custodians' addresses have not been validated.
/// </param>
///
/// <param name="senderMailboxName">
/// An application specified mailbox name that's sending the message.
/// The mailbox name is appended to the application's domain name to
/// form the From email address of the message. This parameter should
/// only contain the characters before the @ symbol of the email
/// address.
/// </param>
///
/// <param name="senderDisplayName">
/// The message sender's display name.
/// </param>
///
/// <param name="subject">
/// The subject of the message.
/// </param>
///
/// <param name="textBody">
/// The text body of the message.
/// </param>
///
/// <param name="htmlBody">
/// The HTML body of the message.
/// </param>
///
/// <remarks>
/// If both the <paramref name="textBody"/> and
/// <paramref name="htmlBody"/> of the message is specified then a
/// multi-part message will be sent so that the html body will be used
/// and fallback to text if not supported by the client.
///
/// If the domain name of the application has not been previously
/// set (usually through app registration), this method will throw
/// a <see cref="HealthServiceException"/>.
///
/// The calling application and the person through which authorization to the
/// specified record was obtained must be authorized for the record.
/// The person must be either authenticated, or if the person is offline,
/// their person Id specified as the offline person Id.
/// See <see cref="Microsoft.Health.Web.OfflineWebApplicationConnection" />
/// for more information.
/// </remarks>
///
/// <exception cref="ArgumentException">
/// If <paramref name="recordId"/> is <see cref="System.Guid.Empty"/>
/// -or-
/// if <paramref name="senderMailboxName"/> is null or empty,
/// -or-
/// if <paramref name="senderDisplayName"/> is null or empty,
/// -or-
/// if <paramref name="subject"/> is null or empty,
/// -or-
/// if <paramref name="textBody"/> and <paramref name="htmlBody"/>
/// are both null or empty.
/// </exception>
///
/// <exception cref="HealthServiceException">
/// If the server returned a failure when making the request.
/// </exception>
///
public static void SendInsecureMessageToCustodiansFromApplication(
HealthServiceConnection connection,
Guid recordId,
bool addressMustBeValidated,
string senderMailboxName,
string senderDisplayName,
string subject,
string textBody,
string htmlBody)
{
HealthVaultPlatformMessage.Current.SendInsecureMessageFromApplication(
connection,
null,
null,
recordId,
addressMustBeValidated,
senderMailboxName,
senderDisplayName,
subject,
textBody,
htmlBody);
}
/// <summary>
/// Fetch the <see cref="HealthRecordItem" /> instances that are specified
/// in the ChangedItems collection.
/// </summary>
/// <remarks>
/// After the operation has completed, see <see cref="HealthRecordItemChangedItem.Item" />
/// to use the fetched <see cref="HealthRecordItem" />
///
/// Items that have been removed from a record or are otherwise inaccessible will
/// have a <see cref="HealthRecordItemChangedItem.Item" /> value of null.
/// </remarks>
/// <param name="connection">The connection to use to fetch the instances.</param>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
public void GetItems(HealthServiceConnection connection)
{
Validator.ThrowIfArgumentNull(connection, "connection", "ConnectionNull");
GetItems(connection.ApplicationId, connection.RequestUrl.OriginalString);
}
/// <summary>
/// Authenticate the keyset pair for the specified
/// <paramref name="applicationId"/> by calling to the Microsoft Health
/// Service to create a new authentication token.
/// </summary>
///
/// <remarks>
/// In order to avoid unnecessary authentication actions, it is
/// expected that the caller will first call
/// <cref name="IsAuthenticationExpired"/> before calling this.
/// </remarks>
///
/// <param name="keySetPairs">
/// The keyset pairs collection that will contain the newly
/// authenticated keyset pair.
/// </param>
///
/// <param name="connection">
/// The connection used to perform the authentication.
/// </param>
///
/// <param name="applicationId">
/// The application id of the keyset pair that will be authenticated.
/// </param>
///
/// <param name="certificate">
/// The application's certificate containing the application's private key.
/// </param>
///
private static void AuthenticateKeySetPair(
AuthSessionKeySetPairs keySetPairs,
HealthServiceConnection connection,
Guid applicationId,
X509Certificate2 certificate)
{
AuthenticationTokenKeySetPair pair =
keySetPairs.GetPair(applicationId);
if (pair == null)
{
pair = keySetPairs.CreatePair(applicationId);
}
if (!pair.IsAuthenticated())
{
lock (pair)
{
if (!pair.IsAuthenticated())
{
if (pair.IsAuthenticationResultExpired)
{
// the existing live pair is already authenticated
// so create a new one with a fresh keyset
pair.RefreshSharedSecret();
}
WebApplicationCredential cred =
new WebApplicationCredential(applicationId, certificate);
cred.KeySet = pair.KeySet.Clone();
// create the new token
// this will implicitly result in a call to
// UpdateAuthenticationResults
cred.CreateAuthenticatedSessionToken(
connection,
applicationId);
}
}
}
}
