/// <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; }