/// <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="searchString"/> is a string of characters in the specified
/// culture.
/// </remarks>
///
/// <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="searchString">
/// 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="searchString"/> 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>
///
//[Obsolete("Use HealthServicePlatform.SearchVocabulary() instead.")]
public VocabularyItemCollection SearchVocabulary(
VocabularyKey vocabularyKey,
string searchString,
VocabularySearchType searchType,
int? maxResults)
{
return HealthVaultPlatform.SearchVocabulary(this, vocabularyKey, searchString, searchType, maxResults);
}
/// <summary>
/// Retrieves a list of vocabulary items for the specified vocabulary
/// and culture.
/// </summary>
///
/// <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>
///
//[Obsolete("Use HealthServicePlatform.GetVocabulary() instead.")]
public Vocabulary GetVocabulary(VocabularyKey vocabularyKey, bool cultureIsFixed)
{
return HealthVaultPlatform.GetVocabulary(this, vocabularyKey, cultureIsFixed);
}
/// <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 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>
/// Creates a vocabulary search parameter set with the <see cref="VocabularyKey"/> that is
/// used to identify the vocabulary to search.
/// </summary>
/// <param name="vocabulary">
/// A key to identify the vocabulary that is searched.
/// </param>
/// <exception cref="ArgumentNullException">
/// If <paramref name="vocabulary"/> is <b>null</b>.
/// </exception>
public VocabularySearchParameters(VocabularyKey vocabulary)
{
Validator.ThrowIfArgumentNull(vocabulary, "vocabulary", "VocabularyKeyNullOrEmpty");
_vocabulary = vocabulary;
}
