API

1. Searching for dictionaries

URL schemes of all Paragon dictionaries are defined by the following template:
com.slovoed.api.NNN, where NNN is int number in [0, 999] range.
Therefore [UIApplication canOpenURL:] method allows a user to check whether any dictionaries are installed on the device.
Example:
for(int i = 0; i < 999; i++)
    {
    //build URL scheme
    NSString * scheme = [NSString stringWithFormat:@"com.slovoed.api.%d://", i];
    //check
    NSURL * url = [NSURL URLWithString:scheme];
    if ([[UIApplication sharedApplication] canOpenURL:url])
    {
        ...
    }
}

2. Requests

Requests are composed of key-value pairs. Key and value are separated by '=' symbol, while pairs themselves are separated by '|' symbol (0x7C).

The list of possible keys:

info
The "info" key is used to receive detailed information about a dictionary. It's corresponding key-value pair looks like info=PasteboardName, where PasteboardName is a name of UIPasteboard object, where requested dictionary information should be written.
Example:
com.slovoed.api.1://info=PasteboardForInfo
return
The "return" key is used to return to the requesting application. It's corresponding key-value pair looks like return=Scheme, where Scheme is a URL scheme of the requesting application. If both "return" AND "info" keys have been used in the same request, right after dumping information into specified UIPasteboard object, the dictionary will try to open the requesting application using the specified URL scheme. Otherwise (if "return" key was not used), all articles in the dictionary will include "Go back" button. Tapping on this button will switch a user to the requesting application.
Examples:
com.slovoed.api.1://return=com.company.MyTestApp
com.slovoed.api.1://return=com.company.MyTestApp/info=PasteboardForInfo
Example of a request creation:
NSString * buildInfoRequest(NSString * aDictionaryScheme, NSString * aPasteboardName, NSString * aOwnScheme)
{
    NSString * request = [NSString stringWithFormat:@"%@info=%@|return=%@", aDictionaryScheme, aPasteboardName, aOwnScheme];
    return [request stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
}
show
The "show" key is used to switch the dictionary to a certain article. It's corresponding key-value pair looks like show=word, where word is a title of required article. When such request is received, the dictionary will try to open a "word" article (if such article is available in the dictionary).
Example:
com.slovoed.api.1://show=test
Example of request creation:
NSString * buildShowRequest(NSString * aDictionaryScheme, NSString * aWord, NSString * aOwnScheme)
{
    NSString * request = [NSString stringWithFormat:@"%@show=%@|return=%@", aDictionaryScheme, aWord, aOwnScheme];
    return [request stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
}
language
The "language" key is used in conjunction with "show" key to switch the dictionary to a certain article of a specific language. It's corresponding key-value pair looks like language=code, where code is a four-letter code of a required language. All (either one or two) language codes supported by the dictionary can be received with "info" request along with other information.
Example:
com.slovoed.api.1://show=test|language=engl
Example of request creation:
NSString * buildShowRequest(NSString * aDictionaryScheme, NSString * aWord, NSString * aOwnScheme, NSString * aLanguage)
{
    NSString * request = [NSString stringWithFormat:@"%@show=%@|return=%@|language=%@", aDictionaryScheme, aWord, aOwnScheme, aLanguage];
    return [request stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
}
Entire request string should be encoded with [NSString stringByAddingPercentEscapesUsingEncoding] method. Use [UIApplication openURL:] method to send a request to the dictionary.
Examples:
-(void)requestInfo:(NSString * )aScheme ownScheme:(NSString *)aOwnScheme
{
    //get an unique name for pasteboard
    UIPasteboard * pasteboard = [UIPasteboard pasteboardWithUniqueName];
    //build request URL
    NSString * request = buildInfoRequest(aScheme, pasteboard.name, aOwnScheme);
    NSURL * url = [NSURL URLWithString:request];
    [[UIApplication sharedApplication] openURL:url];
}
//build "show" request
-(void)requestShow:(NSString * )aScheme ownScheme:(NSString *)aOwnScheme text:(NSString *)aText
{
    //build request URL
    NSString * request = buildShowRequest(aScheme, aText, aOwnScheme);
    NSURL * url = [NSURL URLWithString:request];
    [[UIApplication sharedApplication] openURL:url];
}

3. Obtaining dictionary information

When the dictionary receives a request and this request includes the "info" key, it writes information string to the specified UIPasteboard object. This information is composed of key-value pairs. Key and value are separated by '=' symbol, while pairs themselves are separated by '|' symbol (0x7C). Entire text is encoded with [NSString stringByAddingPercentEscapesUsingEncoding] method.

Possible keys:

KeyKey explanationKey-value pair formatValue explanationValue type
ProtocolVersion version of the information format ProtocolVersion=Value protocol version number float number
WordsCount number of dictionary articles WordsCount=Value number of articles int number
ProductName dictionary name ProductName=Value name of the dictionary UTF-8 string
LanguagePair language pair name LanguagePair=Value language pair name (the dictionary provides translations from the first of these two languages to the second one) UTF-8 string
ReverseLanguagePair reverse language pair name ReverseLanguagePair=Value reverse language pair name. This parameter may be empty if the dictionary is mono-directorial. UTF-8 string
LanguageCodeFrom primary language code LanguageCodeFrom=Value four-letter code of the primary language. The dictionary always provides translations from LanguageCodeFrom to LanguageCodeTo (but not necessary in the opposite direction). This code can be specified in request to show an article of a specific language. UTF-8 string
LanguageCodeTo secondary language code LanguageCodeTo=Value four-letter code of the secondary language. The dictionary always provides translations from LanguageCodeFrom to LanguageCodeTo (but not necessary in the opposite direction) UTF-8 string
Author dictionary author name Author=Value the name of dictionary's author (creator of dictionary database) UTF-8 string
AuthorWeb web-site of the dictionary author AuthorWeb=Value The WWW address of author's site. This parameter may be empty. UTF-8 string

Example:

ProtocolVersion=0.100000%7CWordsCount=101292%7CProductName=Oxford%20Advanced%20Learner's%20Dictionary%7CLanguagePair=English-English%7CReverseLanguagePair=%7CLanguageCodeFrom=engl%7CLanguageCodeTo=engl%7CAuthor=Oxford%7CAuthorWeb=www.oup.com