Providers & Plugins

Note: Data here only applies to v3.0.0. Plugins are not supported on previous versions of aphrodite.

Plugin development

This application supports plugins for other boorus hosted with DanBooru or Philomena. This page should give a basic rundown on developing a plugin.

While plugin support is very initial, it may change per release. If any changes to the provider interfaces occur, the creator of the provider should be responsible for updating the provider.

Providers also have the option to create their own userscript for the booru of their choice. All arguments outlined in the arguments page will apply.

All providers are required to have a valid GUID associated with it, and that it is a unique GUID. GUIDs are used to identify providers, and if the GUID is invalid or not present, the provider will not be loaded.

The following GUIDs are not allowed to be used:

• 00000000-0000-0000-0000-000000000000 -> An invalid GUID, which is the default value. Defers to the internal e621 provider.
• 0fb5a737-ea09-4615-8048-0dc2bacede18 -> aphrodites GUID. Defers to the internal e621 provider.

Finally, your provider should be as hands-off to the main application as possible. The program will call the provider when it requires data, but the provider should only call the program for the tag filtering system and saving the infos.

You should create your own logic to parse & save. Although the internal e621 providers can be used as a reference for what you should do, do NOT use it as a copy/paste for your own provider.

IProvider

The default provider interface. It is not used generally for much, but every provider (aside from ICustomProvider) implement this interface, and it's methods and values.

Properties

• string Name
  The name of the provider. This will appear in the log and the drop-down buttons on the main form.
• string SiteAccessName
  The short and sweet URL to access the booru. An example would be e621.net. There is no https or subdomains, just the domain name and TLD.
• Image Icon
  The System.Drawing.Image object to represent the booru. This can be the favicon. If this value is NULL, it will use a grayed-out application icon.
• string BaseUrl
  The base URL that will be used to connect to the API, with format parameters following
  • {0} must be the tag or pool id or the image id, or whatever necessary identifier.
  • {1} should the the page number for page downloads, if applicable.
  • {2} should be the max amount of files displayed per page, if applicable.
• string FolderName
  The name of the output folder that the downloader will save the files to. I usually use acronyms for boorus that have words, like furbooru would become fb, but you can choose whatever.
• int PostsPerPage
  The amount of posts that will appear per-page on the API. Image downloads, and some pool boorus will not require this value.
• string DateTimeFormat
  If the booru has a DateTime object, this should be the format of that value. Unix epoch timestamps are not currently supported.
• bool SupportsFileSizes
  The flag for the downloader to display a total download size, if the API contains a value for the file size for each file.
• bool Available
  The flag that the provider is available to be loaded and used. This should not be true unless it's a release built library, and is finished and safe for using.

Methods

• void Initialize()
  Loads the provider instance, and runs any necessary code to make the provider work.
• void PrepareDownloadClient(HttpClientAddons)
  Occurs when the download client of the download instance is created. This will allow you to add required data to the client before it is used. It currently only allows cookies to be added.

ITagProvider

The provider that is used for downloading files using tags. It's the main attraction.

Properties

• BooruType BooruType
  This tells the program what kind of booru downloader to use, either DanBooru or Philomena. The choice here affects whether Explicit, Questionable, Safe are the only 3 or if Mature and Suggestive are additional columns on the downloader form. (They are separate forms, but you know.)
• bool SupportsPageDownload
  Whether the provider supports downloading single pages from the API. In general, most tag providers do have support for this, but the program does extra logic for page downloads to ensure it's successful.

Methods

• bool ValidPageUrl(string)
  Returns true if the input string is a valid page URL for the provider; otherwise, false. This is used for page downloading.
• bool ValidPageWithTagsUrl(string)
  Returns true if the input string is a valid page URL that contains tags; otherwise, false. This is used for extracting tags from page urls.
• Uri GetApiUrl(Uri)
  Returns a new Uri that converts the input Uri into an API Uri. This should not mess with important data, such as tags or page number, and should only change necessary data to access the API with the values in the input Uri.
• string ExtractTagsFromUri(Uri)
  Returns the tags extracted from the input Uri. They can be cleaned or just what is available in the Uri.
• string ExtractPageNumberFromUri(Uri)
  Returns the current page number extracted from the input Uri. If no page number is present, it might be page 1. If a booru does not display that value, who knows what to do.
• string SanitizeTags(string, bool)
  Returns the input tags that get sanitized for use based on the Identifier bool value:
  • true -> The tags should appear as pretty as possible, to display to the user on the form.
  • false -> The tags should be as friendly as possible to the API, which may require encoding into HTML. It's up to the provider to format them.
• * void PreParse(DownloadInfo, TagList, Counts, TagData, ref bool)
  This will occur before the main API parsing begins.
• * void Parse(DownloadInfo, TagList, Counts, TagData, ref bool)
  The main parsing logic. Here you can serialize the DownloadInfo.CurrentJson string into an API object,using DownloadInfo.CurrentJson.JsonDeserialize<T>([string DateTimeFormat]). You are responsible for the loops through the pages' files, adding files to the lists, and incrementing required counts. This would be more automated, but each API is unique.
• * void SaveInfo(DownloadInfo, TagList, string)
  The pre-download step that saves the post infos. This is handled by the provider due to, again, each API being unique. You are responsible for using DownloadHelpers.SaveInfo(List.*) to save each info.

* - Multiple instances of this method exists within the provider interface. Choose the right method, and use ThrowException.ThrowNonXProvider(); on the non-matching booru type methods.

IPoolProvider

The provider that is used for downloading pools from boorus. The less used, but equally appreciated part.

Properties

• BooruType BooruType
  This tells the program what kind of booru downloader to use, either DanBooru or Philomena. The choice here affects whether Explicit, Questionable, Safe are the only 3 or if Mature and Suggestive are additional columns on the downloader form. (They are separate forms, but you know.)
• string BasePoolUrl
  The base URL for the Pool API. This should include data such as the pool name, pool description, pool post IDs, etc.

Methods

• bool ValidPoolUrl(string)
  Returns true if the input string is a valid pool URL for the provider; otherwise, false.
• bool ValidId(string)
  Returns true if the input string is a valid pool ID for the provider; otherwise, false.
• string ExtractPoolId(string)
  Returns the pool id that is extracted from the pool url in the string parameter.
• string CleanUrl(string)
  Returns the pool url from the string parameter that has any unnecessary data removed from it.
• * void PreExtract(DownloadInfo, PoolList, Counts, PoolData, ref bool)
  Occurs before the first API connection, allowing you to set anything required (if required).
• * void ExtractInfo(DownloadInfo, PoolList, PoolData)
  This will extract information from the pool, such as the name, and the amount of pages to download (if it's possible to calculate).
• * void PreParse(DownloadInfo, PoolList, Counts, PoolData, ref bool)
  This will occur before the main API parsing begins.
• * void Parse(DownloadInfo, PoolList, Counts, PoolData, ref bool)
  The main parsing logic. Here you can serialize the DownloadInfo.CurrentJson string into an API object,using DownloadInfo.CurrentJson.JsonDeserialize<T>([string DateTimeFormat]). You are responsible for the loops through the pages' files, adding files to the lists, and incrementing required counts. This would be more automated, but each API is unique.
• * void SaveInfo(DownloadInfo, PoolList, PoolData, string)
  The pre-download step that saves the post infos as well as the main pool information in the Data.PoolInfo object. This is handled by the provider due to, again, each API being unique. You are responsible for using DownloadHelpers.SaveInfo(List.*) to save each info.

* - Multiple instances of this method exists within the provider interface. Choose the right method, and use ThrowException.ThrowNonXProvider(); on the non-matching booru type methods.

IImageProvider

The provider for downloading single images. This is a very simple provider and is 100% ambiguous when it comes to data. All of it is basically handled by the provider, which means any site is technically supported, if implemented properly.

Properties

There are no specific properties for the image provider.

Methods

• bool ValidImageLink(string)
  Returns true if the input string value is a valid post link for the provider; otherwise, false.
• bool ValidId(string)
  Returns true if the input string value is a valid post ID for the provider; otherwise, false.
• string ExtractImageId(string)
  Returns the image ID that gets extracted from the input string value.
• void PreParse(DownloadInfo, ImageData, ref bool)
  This will occur before the main API parsing begins.
• void Parse(DownloadInfo, ImageData, ref bool)
  The main parsing logic. Here you can serialize the DownloadInfo.CurrentJson string into an API object,using DownloadInfo.CurrentJson.JsonDeserialize<T>([string DateTimeFormat]). Here you are responsible for generating required data for the file.
• void SaveInfo(DownloadInfo, ImageData)
  The pre-download step that saves the post infos as well as the main pool information in the Data.PoolInfo object. This is handled by the provider due to, again, each API being unique. You are responsible for using DownloadHelpers.SaveInfo(Post) to save each info.

IOffendingTagProvider

This provider was created for a simple way to check individual posts that may have been filtered that the user wishes to NOT have lost. It doesn't overwrite the tag filters and it doesn't download the images, only the API data.

This interface is not required to implement everything, only the things below are used.

Properties

• string Name
  The name of the provider. This will appear in the log and the drop-down buttons on the main form.
• string SiteAccessName
  The short and sweet URL to access the booru. An example would be e621.net. There is no https or subdomains, just the domain name and TLD.
• Image Icon
  The System.Drawing.Image object to represent the booru. This can be the favicon. If this value is NULL, it will use a grayed-out application icon.
• bool Available
  The flag that the provider is available to be loaded and used. This should not be true unless it's a release built library, and is finished and safe for using.
• string SearchBaseUrl
  The base URL for a Search URL. This may not be implemented in the release build due to some concerns.

Methods

• string[] GetPostTags(string, IOffendingTagProvider.ApiDownload delegate string(string))
  The main method that is called for the provider to get the API data. The provider should only work with the tags from the API to return to the callee.
• GetPostId(string)
  The helper method to get the ID of the post for the main form to handle with. It's passed to GetPostTags(...).

Every other implemented field or function can be safely ignored as it is not used by the form.

ICustomProvider

Custom providers are not supported quite yet, due to concerns. I will hopefully find a way to solve those concerns, so I can remove the InkBunny and Imgur downloader from the main application and have them be their own custom provider. Until then, this section will remain as is.

IInvalidProvider

An empty interface that is used for testing. This should be ignored, if it is visible outside of the aphrodite application.

Tag filtering

aphrodite will handle tag filtering for your provider, using the tag filtering system.

Your provided booru must either conform to the DanBooru tagging style, or you must account for spaces in tags by replacing them with_underscores per file.

When you are ready to get the designation of the parsed post, use TagFilters.GetDesignation(...) to retrieve the designation.

Arguments

aphrodite will forward any arguments to your provider if the GUID is to the right of the argument id. Currently, tags, pages, pools, and image are supported for forwarding, while poolwishlist will continue to be handled by aphrodite.

When using arguments with providers, make sure users can access them by following the schema for the argument system: <argument>:<your GUID> .... An example of this would e tags:1234... "checkmark".

The pool wishlist is supported by using poolwl:<your GUID> <pool url> [pool name]. The pool URL is required, while the pool name is optional. If no pool name is given, the name will be saved as empty pool name.

Finally, arguments with spaces should be "in doubble-quotes". If you require using double-quotes, you can \"escape\" them or use the internal double-quote marker {{%DQ%}}. If you require that marker for other purposes, it is up to you to work around it.

Json and XML

aphrodite uses DataContractJsonSerializer to serialize and deserialize. If your provider uses XML, you can use the string.XmlToJsonDeserialize(string) method to convert it to a JSON object and then deserialize. You can use string XmlConversion.XmlToJson(string) to get a string version of the Json to paste as a json class.

Hosting your provider

aphrodite will host the provider, if you wish to push it to the repo. However, issues opened regarding your provider will be marked as invalid. If you wish to handle issues, you can open your own repo and either open a new issue asking to be added to the wiki, or if it's supported, open a wiki edit pull request to add yours to the list.

---

Available providers

No alternative providers are available at this time. FurBooru and FurryBooru will be moved to here as the first two providers, all in good time.