/// <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 virtual ReadOnlyCollection<VocabularyKey> GetVocabularyKeys(HealthServiceConnection connection)
{
string methodName = "GetVocabulary";
HealthServiceRequest request = new HealthServiceRequest(connection, methodName, 1);
request.Execute();
ReadOnlyCollection<VocabularyKey> keys
= CreateVocabularyKeysFromResponse(methodName, request.Response);
return keys;
}
/// <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>
///
/// <param name="matchingVocabulary">
/// A <see cref="VocabularyItemCollection"/> populated with entries matching
/// the search criteria.
/// </param>
///
/// <param name="matchingKeys">
/// A <b>ReadOnlyCollection</b> of <see cref="VocabularyKey"/> with entries
/// matching the search criteria.
/// </param>
///
/// <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 virtual void SearchVocabulary(
HealthServiceConnection connection,
VocabularyKey vocabularyKey,
string searchValue,
VocabularySearchType searchType,
int? maxResults,
out VocabularyItemCollection matchingVocabulary,
out ReadOnlyCollection<VocabularyKey> matchingKeys)
{
Validator.ThrowArgumentExceptionIf(
String.IsNullOrEmpty(searchValue) || searchValue.Length > 255,
"searchString",
"VocabularySearchStringInvalid");
Validator.ThrowArgumentExceptionIf(
!Enum.IsDefined(typeof(VocabularySearchType), searchType),
"searchType",
"VocabularySearchTypeUnknown");
Validator.ThrowArgumentExceptionIf(
maxResults.HasValue && maxResults.Value < 1,
"maxResults",
"VocabularySearchMaxResultsInvalid");
matchingVocabulary = null;
matchingKeys = null;
string methodName = "SearchVocabulary";
HealthServiceRequest request = new HealthServiceRequest(connection, methodName, 1);
StringBuilder requestParameters = new StringBuilder(256);
XmlWriterSettings settings = SDKHelper.XmlUnicodeWriterSettings;
settings.OmitXmlDeclaration = true;
settings.ConformanceLevel = ConformanceLevel.Fragment;
using (XmlWriter writer = XmlWriter.Create(requestParameters, settings))
{
if (vocabularyKey != null)
{
vocabularyKey.WriteXml(writer);
}
writer.WriteStartElement("text-search-parameters");
writer.WriteStartElement("search-string");
writer.WriteAttributeString("search-mode", searchType.ToString());
writer.WriteString(searchValue);
writer.WriteEndElement(); // <search-string>
if (maxResults.HasValue)
{
writer.WriteElementString("max-results", maxResults.Value.ToString(CultureInfo.InvariantCulture));
}
writer.WriteEndElement(); //<text-search-parameters>
writer.Flush();
}
request.Parameters = requestParameters.ToString();
request.Execute();
if (vocabularyKey != null)
{
matchingVocabulary = CreateVocabularyItemCollectionFromResponse(
methodName, request.Response);
}
else
{
matchingKeys = CreateVocabularyKeysFromResponse(methodName, request.Response);
}
}
/// <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="requestParameters">
/// The request parameters.
/// </param>
///
/// <remarks>
/// This may be <b>null</b> if no application settings have been
/// stored for the application or user.
/// </remarks>
///
public virtual void SetApplicationSettings(
HealthServiceConnection connection,
string requestParameters)
{
HealthServiceRequest request =
new HealthServiceRequest(connection, "SetApplicationSettings", 1);
request.Parameters = requestParameters;
request.Execute();
}
/// <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 virtual ReadOnlyCollection<Vocabulary> GetVocabulary(
HealthServiceConnection connection,
IList<VocabularyKey> vocabularyKeys,
bool cultureIsFixed)
{
Validator.ThrowIfArgumentNull(vocabularyKeys, "vocabularyKeys", "VocabularyKeysNullOrEmpty");
Validator.ThrowArgumentExceptionIf(
vocabularyKeys.Count == 0,
"vocabularyKeys",
"VocabularyKeysNullOrEmpty");
string methodName = "GetVocabulary";
HealthServiceRequest request = new HealthServiceRequest(connection, methodName, 2);
StringBuilder requestParameters = new StringBuilder(256);
XmlWriterSettings settings = SDKHelper.XmlUnicodeWriterSettings;
settings.OmitXmlDeclaration = true;
settings.ConformanceLevel = ConformanceLevel.Fragment;
using (XmlWriter writer = XmlWriter.Create(requestParameters, settings))
{
writer.WriteStartElement("vocabulary-parameters");
for (int i = 0; i < vocabularyKeys.Count; i++)
{
Validator.ThrowIfArgumentNull(vocabularyKeys[i], "vocabularyKeys[i]", "VocabularyKeysNullOrEmpty");
vocabularyKeys[i].WriteXml(writer);
}
writer.WriteElementString(
"fixed-culture",
SDKHelper.XmlFromBool(cultureIsFixed));
writer.WriteEndElement(); //<vocabulary-parameters>
writer.Flush();
}
request.Parameters = requestParameters.ToString();
request.Execute();
ReadOnlyCollection<Vocabulary> vocabularies
= CreateVocabulariesFromResponse(methodName, request.Response);
return vocabularies;
}
/// <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 virtual ApplicationSettings GetApplicationSettings(HealthServiceConnection connection)
{
HealthServiceRequest request =
new HealthServiceRequest(connection, "GetApplicationSettings", 1);
request.Execute();
XPathExpression xPathExpression
= GetPersonAppSettingsXPathExpression(
request.Response.InfoNavigator);
XPathNavigator appSettingsNav
= request.Response.InfoNavigator
.SelectSingleNode(xPathExpression);
ApplicationSettings settings = null;
if (appSettingsNav != null)
{
settings = new ApplicationSettings();
settings.ParseXml(appSettingsNav);
}
return settings;
}
/// <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 virtual void SetApplicationSettings(
HealthServiceConnection connection,
IXPathNavigable applicationSettings)
{
string requestParameters =
GetSetApplicationSettingsParameters(applicationSettings);
SetApplicationSettings(connection, requestParameters);
}
/// <summary>
/// Create authentication tokens and absence reasons for user
/// credentials, given the specified method, connection, and multiple
/// application ID's.
/// </summary>
///
/// <remarks>
/// The Shell primarily uses multiple application ID's when
/// constructing simple credential tokens: One each for the Shell and
/// for the target application.
/// </remarks>
///
/// <param name="methodName">
/// The HealthVault service method name to call.
/// </param>
///
/// <param name="version">
/// The version of the service method to call.
/// </param>
///
/// <param name="connection">
/// The <see cref="HealthServiceConnection"/> instance.
/// </param>
///
/// <param name="applicationTokenCreationInfo">
/// The application token creation information.
/// </param>
///
/// <param name="stsOriginalUrl">
/// The original url from the STS request.
/// </param>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="methodName"/>
/// parameter is <b>null</b> or empty.
/// </exception>
///
internal void MakeCreateTokenCall(
string methodName,
int version,
HealthServiceConnection connection,
ApplicationTokenCreationInfo applicationTokenCreationInfo,
string stsOriginalUrl)
{
Validator.ThrowIfStringNullOrEmpty(methodName, "CreateTokenMethodNameIsNullOrEmpty");
Validator.ThrowArgumentExceptionIf(
applicationTokenCreationInfo == null,
"appTokenCreationInfo",
"AuthenticationAppIDCollectionNullOrEmpty");
if (IsTokenCached(applicationTokenCreationInfo))
{
return;
}
AuthenticationMethodName = methodName;
HealthServiceRequest request =
new HealthServiceRequest(connection, AuthenticationMethodName, version);
request.Parameters =
ConstructCreateTokenInfoXml(applicationTokenCreationInfo, stsOriginalUrl);
request.Execute();
CreateAuthenticationTokenResult createAuthTokenResult =
GetAuthTokenAndAbsenceReasons(
request.Response.InfoNavigator);
ParseExtendedElements(request.Response.InfoNavigator);
UpdateAuthenticationResults(createAuthTokenResult);
}
/// <summary>
/// Authenticates or re-authenticates the credential.
/// </summary>
///
private void Authenticate(
HealthServiceConnection connection,
Guid appId)
{
if (AuthenticationResults != null)
{
AuthenticationResults.Remove(appId);
}
CreateAuthenticatedSessionToken(connection, appId);
}
/// <summary>
/// Authenticates an <paramref name="applicationId"/> if none exists.
/// </summary>
///
/// <param name="connection">
/// The connection to use for reauthentication, if necessary.
/// </param>
///
/// <param name="applicationId">
/// The application ID to verify if authentication is required.
/// </param>
///
internal virtual void AuthenticateIfRequired(
HealthServiceConnection connection,
Guid applicationId)
{
if (GetAuthenticationResult(applicationId) == null)
{
Authenticate(connection, applicationId);
}
}
/// <summary>
/// Creates authentication tokens and absence reasons for user credentials.
/// </summary>
///
/// <remarks>
/// This method takes only one application ID, which is the typical case.
/// </remarks>
///
/// <param name="methodName">
/// The HealthVault service method name to call.
/// </param>
///
/// <param name="version">
/// The version of the service method to call.
/// </param>
///
/// <param name="connection">
/// The <see cref="HealthServiceConnection"/> instance.
/// </param>
///
/// <param name="appId">
/// The application ID to create a token for.
/// </param>
///
/// <param name="isMra">
/// The application is a multi-record app.
/// </param>
///
/// <param name="stsOriginalUrl">
/// The original url from the STS request.
/// </param>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="methodName"/>
/// parameter is <b>null</b> or empty.
/// </exception>
///
internal void MakeCreateTokenCall(
string methodName,
int version,
HealthServiceConnection connection,
Guid appId,
bool isMra,
string stsOriginalUrl)
{
MakeCreateTokenCall(
methodName,
version,
connection,
new ApplicationTokenCreationInfo(appId, isMra),
stsOriginalUrl);
}
/// <summary>
/// Gets an authentication token in the context of the credential.
/// </summary>
///
/// <remarks>
/// The resulting authentication result is inserted into
/// <see cref="GetAuthenticationResult"/>.
/// This method accesses the HealthVault service across the network.
/// If the application ID specified is already in the dictionary,
/// then the authentication attempt is not made and the cached
/// authentication result is used.
/// </remarks>
///
/// <param name="connection">
/// The client-side representation of the HealthVault service.
/// </param>
///
/// <param name="appId">
/// The HealthVault application identifier for which the request is
/// made.
/// </param>
///
/// <exception cref="ArgumentNullException">
/// The <paramref name="connection"/> parameter is <b>null</b>.
/// </exception>
///
/// <exception cref="ArgumentException">
/// The <paramref name="appId"/> parameter is <b>null</b> or empty.
/// </exception>
///
/// <seealso cref="Microsoft.Health.HealthServiceConnection"/>
///
public void CreateAuthenticatedSessionToken(
HealthServiceConnection connection,
Guid appId)
{
Validator.ThrowIfArgumentNull(connection, "connection", "AuthenticatedConnectionNull");
Validator.ThrowArgumentExceptionIf(
appId == null || appId == Guid.Empty,
"appId",
"AuthenticationAppIDNullOrEmpty");
AnonymousConnection anonConn =
new AnonymousConnection(connection.ApplicationId, connection.RequestUrl);
if (connection.WebProxy != null)
{
anonConn.WebProxy = connection.WebProxy;
}
MakeCreateTokenCall(
"CreateAuthenticatedSessionToken",
2,
anonConn,
appId,
false);
}
private static HealthServiceRequest CreateGetUpdateRecordsForApplicationRequest(
HealthServiceConnection connection,
DateTime? updateDate)
{
HealthServiceRequest request =
new HealthServiceRequest(connection, "GetUpdatedRecordsForApplication", 1);
StringBuilder parameters = new StringBuilder();
if (updateDate != null)
{
parameters.Append("<update-date>");
parameters.Append(SDKHelper.XmlFromDateTime(updateDate.Value));
parameters.Append("</update-date>");
}
request.Parameters = parameters.ToString();
return request;
}
/// <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 virtual string NewSignupCode(HealthServiceConnection connection)
{
HealthServiceRequest request =
new HealthServiceRequest(connection, "NewSignupCode", 1);
request.Execute();
XPathExpression infoPath =
SDKHelper.GetInfoXPathExpressionForMethod(
request.Response.InfoNavigator,
"NewSignupCode");
XPathNavigator infoNav = request.Response.InfoNavigator.SelectSingleNode(infoPath);
return infoNav.SelectSingleNode("signup-code").Value;
}
/// <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 virtual IList<Guid> GetUpdatedRecordsForApplication(
HealthServiceConnection connection,
DateTime? updatedDate)
{
HealthServiceRequest request =
CreateGetUpdateRecordsForApplicationRequest(connection, updatedDate);
request.Execute();
IList<Guid> results;
ParseGetUpdatedRecordsForApplicationResponse(request.Response, out results);
return results;
}
/// <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 virtual ApplicationInfo GetApplicationInfo(
HealthServiceConnection connection,
Boolean allLanguages)
{
HealthServiceRequest request =
new HealthServiceRequest(connection, "GetApplicationInfo", 2);
if (allLanguages)
{
request.Parameters += "<all-languages>true</all-languages>";
}
request.Execute();
XPathExpression xPathExpression = SDKHelper.GetInfoXPathExpressionForMethod(
request.Response.InfoNavigator, "GetApplicationInfo");
XPathNavigator infoNav
= request.Response.InfoNavigator
.SelectSingleNode(xPathExpression);
XPathNavigator appInfoNav = infoNav.SelectSingleNode("application");
ApplicationInfo appInfo = null;
if (appInfoNav != null)
{
appInfo = ApplicationInfo.CreateFromInfoXml(appInfoNav);
}
return appInfo;
}
