Introduction

Here's a quick guide to some of the relationships between the util tables that Yapeal or application developer should understand. I'm also going to cover how they relate to the API tables to determine which are active etc.

Content

• utilSections
• utilRegistered*
• utilRegisteredKey
• utilRegisteredCharacter
• utilRegisteredCorporation
• Summary

Util tables

The following describes the tables that need to be manage by any application that uses Yapeal and how they effect which APIs are fetched. This also gives a general overview to Yapeal developers where many of the parameters for the section and API classes come from and how they effect program flow, database changes, and error conditions in Yapeal.

The best way to view the activeAPIMask columns in the utilSections and utilRegistered* tables are they allow you to farther restrict what the accessMask returned by the APIKeyInfo API for a keyID/vCode pair would allow by default. The proxy columns allows using outside proxies or to redirect Yapeal to the test API servers etc. Finally isActive allows you to turning off a Key, Character, or Corporation or whole API sections without having to remove any rows from any of the tables.

utilSections

First for any of the APIs to be active there must be an entry for it in the utilSections table. What I call API sections are as follows: account, char, corp, eve, map, server, and is based on the first part of the URL path used when contacting the CCP API servers. Think of this table as the Yapeal or application wide control point for all the APIs. If you set isActive = 0 (FALSE) for all the sections Yapeal will not retrieve any of them. Setting a bit in ActiveAPIMask to 0 will deactivate that API no matter if the key itself or the utilRegistered* tables allow it. proxy works a little different in that it is basically used to override the hard coded default setting but it can be overridden by the optional settings in the utilRegistered* tables if set in them. The eve, map, and server sections have no other controls besides the ones provided in this table.

Back To Top | Back To Handling Sections Guide

utilRegistered*

To understand how the utilRegistered* tables work you have to understand the registered_mode setting from config/yapeal.ini. registered_mode has three allowed values: ignored, optional, and required. Each value can vastly change which of the utilRegistered* tables are used for the account, char, and corp section APIs and how some of the null-able columns work.

• required - This mode is similar to old legacy mode of Yapeal where a row was required in the utilRegisteredCharacter, utilRegisteredCorporation, and utilRegisterUser tables for any of the char, corp, or account APIs to be retrieved. With the new Custom API Key (CAK) system the utilRegisteredCharacter, utilRegisteredCorporation, and utilRegisterKey tables serve much the same functions. The account APIs are controlled by the *Key table and the null-able columns isActive and activeAPIMask can no longer be null but must have actual values or Yapeal will trigger errors and ignore the row. The proxy column remains optional but if set has priority over the setting in utilSections or the hard coded default in the code.
• ignored - This mode is much like required but instead of all the utilRegistered* tables being used only the utilRegisteredKey one is and it won't trigger errors for bad rows just ignore them.
• optional - This mode is the most complex in many ways but much easier to use as well. It is the default setting in config/yapeal-example.ini now. If your config/yapeal.ini file is from an older version of Yapeal and it doesn't have a registered_mode setting the default mode will be required to make things as backward compatible as possible with legacy code but this should not be counted on and the ini file updated at the same time application changes are made to work with CAK. (Note that it always defaults to optional now) So this mode can be used just like required with rows in all the utilRegistered* tables but where it will act differently is when any of the null-able columns are set to null. Describing how each of the tables acts when a column is null is different so will be done as part of the per table descriptions below.

Back To Top | Back To Starter Guide Settings

utilRegisteredKey

This table is the only required one to make the account, char, or corp APIs work. It is used to store the keyID and vCode pair that is required for all of the APIs in these sections. These columns can be compared to the old userID and *ApiKey columns but they aren't exactly the same. In the old system userID was basically the account ID and the two keys acted like both a password and a course grained access mask but in the new CAK system the keyID is just an ID and the vCode acts like a password or validation code and nothing else. There is an associated access mask, type and one or more characters or a corporation for each keyID but it can't be determined from the key or vCode directly but only via a new APIKeyInfo API call. This change allows each Eve account to have more than two keys and to separate the character and corporation access among other things which make it much more flexible.

Note that both 'Account' and 'Character' type keys are used for this table as they both can have account related APIs in the accessMask bitmap. This does mean that Yapeal can end up trying to get the same API multiple times, once for each registered key. Since the ownerID used in the utilCachedUntil table is the keyID there will be duplicate rows in it for what is really the same APIs since they belong to the same account. This can be somewhat limited by making sure only one key for each account is active that allows the accountStatus API in it's accessMask bitmap but there will still be some duplication that shouldn't cause any problems for anyone using it as long as they are aware that it happens.

When the registered_mode is set to optional the isActive and activeAPIMask columns can be null just like proxy always can be and like proxy when they are null the columns from utilSections are used instead. The real interesting change though with the optional mode is that for keys without any rows in the utilRegisteredCharacter or utilRegisteredCorporation tables the columns from utilRegisteredKey are used and the APIs will still be retrieved. So to say it another way when registered_mode = optional in the config/yapeal.ini file having rows in the other utilRegistered tables become optional but any non-null columns from them will be used instead of the ones from this table. This allows for a very flexible system where you can have a set of per key defaults in the columns for a key that can be overridden on a per character/corporation basis. To better understand how the other tables work in optional mode read the follow sections for the other tables.

Note that unlike some past revisions of Yapeal where the columns in this table could have an effect on the working of the other utilRegistered* tables now the columns in the other tables totally override the columns here when in optional mode. The columns here are also totally ignored in required mode except for the account APIs. In ignored mode the columns in the other tables are totally ignored and only the columns in this table are used.

One additional note the account/APIKeyInfo API can't be deactivated by the activeAPIMask in this table because CCP doesn't allow it to be done. This is by design and not in error since it makes no sense to be able to block the same API you need to tell it is not available. By the off chance someone finds a need to turn off retrieving this API in their application you can do so with the mask in utilSections. Doing so is strongly discouraged as it can cause problems when keys are changed but was add just in case someone really thinks they need to shoot their selves in the foot.

Back To Top | Back To Using Yapeal Utils Guide

utilRegisteredCharacter

As stated in utilRegisteredKey above this table becomes optional when registered_mode = optional and for the one or more characters associated with a key you can farther restrict the column values from it or the utilSections table. Note that each of the null-able columns is independent of the others. For example the activeAPIMask column for a row in utilRegisteredCharacter can have a different value but for the same row proxy can still be null and the value from the other two tables would be used instead.

Note that both 'Account' and 'Character' type keys are used for this table as they are both character related. It is also possible to have a single character have more than one 'Account' and/or 'Character' type keys registered. This does mean that Yapeal can end up trying to get the same API multiple times, once for each registered key. This shouldn't actually result in the APIs being retrieved multiple times since the ownerID column = characterID in the utilCachedUntil table and any APIs that have already been updated by another key will be ignore by the current one because the time to retrieve it hasn't come up yet.

To keep this from happening the keys need to be filtered in some way by the application before or after being added to Yapeal. There are a couple of ways to handle this the first being allowing only one key per character but 'Account' type keys complicate this way of handling it. The other way is to ID overlapping keys and insure that none of the same APIs bits are set in the activeAPIMask columns for more than one of the keys. Once again 'Account' type keys can make this more difficult than wanted since they effect more than one character. In the end either way might be more work than it's worth since not filtering them only causes minimal additional work for Yapeal and the database and no addition load for the API servers I believe it can just be ignored in most cases.

Back To Top | Back To Using Yapeal Utils Guide

utilRegisteredCorporation

As stated in utilRegisteredKey above this table becomes optional when registered_mode = optional and for the corporation associated with a key you can farther restrict the column values from it or the utilSections table. Note that each of the null-able columns is independent of the others. For example the activeAPIMask column for a row in utilRegisteredCorporation can have a different value but for the same row proxy can still be null and the value from the other two tables would be used instead.

Note that only 'Corporation' type keys are used for this table. This doesn't mean that Yapeal can't end up trying to get the same API multiple times, once for each registered key since more than one character can have a corporation key even ones from characters on different accounts. A single character on the same account can also have more than one corporation key. This shouldn't actually result in the APIs being retrieved multiple times since the ownerID column = corporationID in the utilCachedUntil table and any APIs that have already been updated by another key will be ignore by the current one because the time to retrieve it hasn't come up yet. Like with the utilRegisteredCharacter table you could try filtering them in the application but it probably isn't worth the effort needed to do so.

Back To Top | Back To Using Yapeal Utils Guide

Summary

The above should give a good understand of how the tables work and interact. Looking at the actual code may help with understand how some of it works as well and you will find some comments in the code that might make things clearer as well for some people.

Classes used to manage tables

There is a group of classes available for Yapeal and application developers to manage the above tables in class/util/ and it is highly recommended they be use instead of directly making changes to these tables. Currently Yapeal does make few of its changes directly but most places it now used the classes. You can find more information about the classes in the UsingClassUtilClasses Wiki page. It includes an example for the RegisteredCharacter class which everyone should find useful in understanding how to use any of the classes.

Back To Top | Back To Using Yapeal Utils Guide