Document core API functions

src/libaacs/aacs.h

@@ -27,7 +27,9 @@
 #  define AACS_PUBLIC
 #endif
 
-/* aacs_open2() error codes */
+/**
+ * aacs_open_device() error codes
+ */
 #define AACS_SUCCESS               0 /* no errors */
 #define AACS_ERROR_CORRUPTED_DISC -1 /* opening or reading of AACS files failed */
 #define AACS_ERROR_NO_CONFIG      -2 /* missing config file */
@@ -38,22 +40,112 @@
 #define AACS_ERROR_MMC_FAILURE    -7 /* MMC failed */
 #define AACS_ERROR_NO_DK          -8 /* no matching device key */
 
+/**
+ * Opaque type for AACS object
+ */
 typedef struct aacs AACS;
 
+/**
+ * Get version of AACS library.
+ *
+ * @param major  where to store libaacs major version
+ * @param minor  where to store libaacs minor version
+ * @param micro  where to store libaacs micro version
+ */
 AACS_PUBLIC void aacs_get_version(int *major, int *minor, int *micro);
 
-AACS_PUBLIC AACS *aacs_init       (void);
-AACS_PUBLIC int   aacs_open_device(AACS *, const char *path, const char *keyfile_path);
+/*
+ * open / close a disc
+ */
+
+/**
+ * Initialize an AACS object.
+ *
+ * Disc must be opened with aacs_open_device().
+ *
+ * @return  AACS object, NULL on error
+ */
+AACS_PUBLIC AACS *aacs_init(void);
 
+/**
+ * Open AACS disc / device.
+ *
+ * If device is not accessible (reading from .iso file or network stream),
+ * path can be NULL.
+ *
+ * If files stored in AACS/ are not accessible from the file system (ex. unmounted disc),
+ * application should provide file system access for libaacs (see aacs_set_fopen()).
+ *
+ * @param  aacs  AACS object
+ * @param  path  path to device or disc root or NULL
+ * @param  keyfile_path  optional path to AACS key file
+ * @return  AACS_SUCCESS or ACS_ERROR_* error code
+ */
+AACS_PUBLIC int aacs_open_device(AACS *, const char *path, const char *keyfile_path);
+
+/* deprecated */
 AACS_PUBLIC AACS *aacs_open(const char *path, const char *keyfile_path);
+
+/* deprecated */
 AACS_PUBLIC AACS *aacs_open2(const char *path, const char *keyfile_path, int *error_code);
 
+/**
+ * Closes and cleans up the AACS object.
+ *
+ * @param aacs  AACS object
+ */
 AACS_PUBLIC void aacs_close(AACS *aacs);
-AACS_PUBLIC void aacs_select_title(AACS *aacs, uint32_t title); /* 0 - top menu, 0xffff - first play */
+
+/*
+ * decryption
+ */
+
+#define AACS_TITLE_FIRST_PLAY  0
+#define AACS_TITLE_TOP_MENU    0xffff
+
+/**
+ * Select title (optional).
+ *
+ * Titles can be stored in different CPS units and use different encryption key.
+ *
+ * If current title is not set, CPS unit is autodetected (with minor performance cost).
+ * If application does not provide current title to libaacs, current CPS unit
+ * should be reset by selecting First Play title (0xffff) when a new playlist is
+ * started.
+ *
+ * @param aacs  AACS object
+ * @param title  Current title from disc index
+ */
+AACS_PUBLIC void aacs_select_title(AACS *aacs, uint32_t title_number);
+
+/**
+ * Decrypt data unit
+ *
+ * Remove possible bus encryption and AACS encryption.
+ *
+ * NOTE: only units from the same CPS unit may be decrypted in paraller.
+ *
+ * @param aacs  AACS object
+ * @param buf  unit to decrypt
+ * @return  1 on success, 0 on error
+ */
 AACS_PUBLIC int  aacs_decrypt_unit(AACS *aacs, uint8_t *buf);
+
+/**
+ * Remove bus encryption.
+ *
+ * If bus encryption is used, remove bus encryption.
+ * Like aacs_decrypt_unit(), but does not perform AACS decryption.
+ *
+ * @param aacs  AACS object
+ * @param buf  unit to decrypt
+ * @return  1 on success, 0 on error
+ */
 AACS_PUBLIC int  aacs_decrypt_bus(AACS *aacs, uint8_t *buf);
 
-/* Disc information */
+/*
+ * Disc information
+ */
 AACS_PUBLIC int aacs_get_mkb_version(AACS *aacs);
 AACS_PUBLIC const uint8_t *aacs_get_disc_id(AACS *aacs);
 AACS_PUBLIC const uint8_t *aacs_get_vid(AACS *aacs);  /* may fail even if disc can be decrypted */
@@ -62,11 +154,15 @@ AACS_PUBLIC const uint8_t *aacs_get_mk(AACS *aacs);   /* may fail even if disc c
 AACS_PUBLIC const uint8_t *aacs_get_content_cert_id(AACS *aacs);
 AACS_PUBLIC const uint8_t *aacs_get_bdj_root_cert_hash(AACS *aacs);
 
-/* AACS Online */
+/*
+ * AACS Online
+ */
 AACS_PUBLIC const uint8_t *aacs_get_device_binding_id(AACS *aacs);
 AACS_PUBLIC const uint8_t *aacs_get_device_nonce(AACS *aacs);
 
-/* revocation lists */
+/*
+ * Revocation lists
+ */
 typedef struct {
     uint16_t  range;
     uint8_t   id[6];
@@ -76,14 +172,18 @@ AACS_PUBLIC AACS_RL_ENTRY *aacs_get_hrl(int *num_entries, int *mkb_version);
 AACS_PUBLIC AACS_RL_ENTRY *aacs_get_drl(int *num_entries, int *mkb_version);
 AACS_PUBLIC void           aacs_free_rl(AACS_RL_ENTRY **rl);
 
-/* bus encryption info */
+/*
+ * Bus encryption information
+ */
 
 #define AACS_BUS_ENCRYPTION_ENABLED  0x01  /* Bus encryption enabled in the media */
 #define AACS_BUS_ENCRYPTION_CAPABLE  0x02  /* Bus encryption capable drive */
 
 AACS_PUBLIC uint32_t aacs_get_bus_encryption(AACS *);
 
-/* Copy Control Information */
+/*
+ * Copy Control Information
+ */
 
 struct aacs_basic_cci;