User API

Api for use by libscipaper users. More...

Data Structures
struct	VersionFixed
	This struct contains the version of libscipaper in use. More...
struct	BackendInfo
	Backend information struct. More...
struct	FillReqest
	This bitfield tells libscipaper what fields you require to have filled. More...
struct	DocumentMeta
	This struct contains the metadata of a paper, must be created via document_meta_new() and freed via document_meta_free() More...
struct	RequestReturn
	This struct is details the result of a metadata search. More...
struct	PdfData
	This struct contains the raw data of a PDF document. More...

Enumerations
enum	loglevel_t {   LL_NONE = 0 , LL_CRIT = 1 , LL_ERR = 2 , LL_WARN = 3 ,   LL_DEFAULT = LL_WARN , LL_INFO = 4 , LL_DEBUG = 5 }
	Severity of loglevels. More...
enum	capability_flags_t { SCI_CAP_FILL = 1 , SCI_CAP_GET_TEXT = (1<<1) , SCI_CAP_GET_PDF = (1<<2) }
	Flags that describe what a backend can do. More...

Functions
void	sci_log_set_verbosity (loglevel_t verbosity)
	Sets the verbosity of sicpaper output.
RequestReturn *	sci_fill_meta (const DocumentMeta *meta, const FillReqest *fill, size_t maxCount, size_t page)
	Takes a DocumentMeta and tries to find maxCount documents that match the fields set in the meta struct.
DocumentMeta *	sci_find_by_doi (const char *doi, int backendId)
	Tries to find the metadata of the document with the given DOI.
DocumentMeta *	sci_find_by_title (const char *title)
	Tries to find the metadata of the document with the given title.
RequestReturn *	sci_find_by_author (const char *author, size_t maxCount)
	Tries to find the documents by a certain author.
RequestReturn *	sci_find_by_journal (const char *journal, size_t maxCount)
	Tries to find the documents by in a certain journal.
char *	sci_get_document_text (const DocumentMeta *meta)
	Tries to get the full text of a certain document.
PdfData *	sci_get_document_pdf_data (const DocumentMeta *meta)
	Tries to get the PDF data of a certain document.
bool	sci_save_pdf_to_file (const PdfData *data, const char *fileName)
	Tries to get save the PDF of a certain document to disk.
bool	sci_save_document_to_file (const DocumentMeta *meta, const char *fileName)
	Saves the PDF of a certain document to disk.
const BackendInfo **	sci_get_all_backends (void)
	gives you an array describing each backend registered with libscipaper.
const BackendInfo *	sci_get_backend_info (int id)
	gives you a BackendInfo struct describing the backend with the id
int	sci_backend_get_id_by_name (const char *name)
	gives you the id of the backend with a given name
const char *	sci_get_backend_name (int id)
	gives you the name of the backend with id
size_t	sci_get_backend_count (void)
	gives you the number of backends currently registered
bool	sci_paper_init (const char *config_file, const char *data, size_t length)
	Inits libscipaper, this function must be your first call to libscipaper, besides sci_get_version() and sci_log_set_verbosity()
void	sci_paper_exit (void)
	Exits libscipaper, this function must be your final call to libscipaper, it is an error to reinit libscipaper sci_paper_init() after executing sci_paper_exit()
const VersionFixed *	sci_get_version (void)
	get the version of scipaper in use
char *	capability_flags_get_str (capability_flags_t capabilities)
	returns the capabilities flags as a human readable string.
DocumentMeta *	document_meta_new (void)
	Mallocs a DocumentMeta struct and initializes it.
DocumentMeta *	document_meta_copy (const DocumentMeta *meta)
	Dose a deep copy of a DocumentMeta struct.
void	document_meta_free (DocumentMeta *meta)
	Frees a document meta struct.
void	document_meta_combine (DocumentMeta *target, const DocumentMeta *source)
	Adds the fields set in source but not in target to target.
char *	document_meta_get_string (const DocumentMeta *meta)
	Creates a human readable string describing a DocumentMeta.
char *	document_meta_get_json (const DocumentMeta *meta, const char *fullText, size_t *length)
	Get string containing json data of the supplied DoucmentMeta.
DocumentMeta *	document_meta_load_from_json (char *jsonFile)
	create a DocumentMeta from json data saved by document_meta_get_json()
DocumentMeta *	document_meta_load_from_json_file (const char *jsonFileName)
	create a DocumentMeta from json file saved by document_meta_save()
char *	document_meta_load_full_text_from_json_file (const char *jsonFileName)
	create a DocumentMeta from json file saved by document_meta_save()
char *	document_meta_get_biblatex (const DocumentMeta *meta, size_t *length, const char *type)
	Get string containing biblatex entry of the supplied DoucmentMeta.
bool	document_meta_save (const char *fileName, const DocumentMeta *meta, const char *fullText)
	Saves a DocumentMeta to disk.
void	document_meta_free_list (DocumentMeta **meta, size_t length)
	Frees a list/array of document metas.
bool	document_meta_is_equal (const DocumentMeta *a, const DocumentMeta *b)
	Compares to document metas and returns if they are equal.
RequestReturn *	request_return_new (size_t count, size_t maxCount)
	Allocates a empty RequestReturn struct.
void	request_return_free (RequestReturn *reqRet)
	Frees a RequestReturn struct.
void	pdf_data_free (PdfData *data)
	Frees a PdfData struct.

Detailed Description

Api for use by libscipaper users.

....

This API allows you to lookup documents, find their full texts and grab PDF files.

Enumeration Type Documentation

capability_flags_t

enum capability_flags_t

Flags that describe what a backend can do.

Enumerator
SCI_CAP_FILL	Backend can fill DocumentMeta structs.
SCI_CAP_GET_TEXT	Backend can get full text of documents.
SCI_CAP_GET_PDF	Backend can get pdfs of documents.

loglevel_t

enum loglevel_t

Severity of loglevels.

Enumerator
LL_NONE	No logging at all.
LL_CRIT	Critical error.
LL_ERR	Error.
LL_WARN	Warning.
LL_DEFAULT	Default log level.
LL_INFO	Informational message.
LL_DEBUG	Useful when debugging.

Function Documentation

capability_flags_get_str()

char * capability_flags_get_str

(

capability_flags_t

capabilities

)

returns the capabilities flags as a human readable string.

Parameters

capabilities

Print with INFO priority if true and DEBUG priority if false

Returns

A newly allocated string stating the flags

document_meta_combine()

void document_meta_combine	(	DocumentMeta *	target,
		const DocumentMeta *	source )

Adds the fields set in source but not in target to target.

Parameters

target	The DocumentMeta struct where the fields of source are to be added to
source	The DocumentMeta struct where to get the fields from

document_meta_copy()

DocumentMeta * document_meta_copy

(

const DocumentMeta *

meta

)

Dose a deep copy of a DocumentMeta struct.

Parameters

meta	The DocumentMeta struct to copy

Returns

A newly allocated copy of the meta struct

document_meta_free()

void document_meta_free

(

DocumentMeta *

meta

)

Frees a document meta struct.

Parameters

meta	The DocumentMeta struct to free, it is safe to pass NULL here

document_meta_free_list()

void document_meta_free_list	(	DocumentMeta **	meta,
		size_t	length )

Frees a list/array of document metas.

Parameters

meta	The DocumentMeta array to free, it is safe to pass NULL here

document_meta_get_biblatex()

char * document_meta_get_biblatex	(	const DocumentMeta *	meta,
		size_t *	length,
		const char *	type )

Get string containing biblatex entry of the supplied DoucmentMeta.

Parameters

meta	The DocumentMeta struct to save into the string
length	length of the returned string containing the biblatex data
type	string with type of biblatex entry or NULL for default/dont care

Returns

A newly allocated string containing the biblatex entry

document_meta_get_json()

char * document_meta_get_json	(	const DocumentMeta *	meta,
		const char *	fullText,
		size_t *	length )

Get string containing json data of the supplied DoucmentMeta.

Parameters

meta	The DocumentMeta struct to save into the string
fullText	Optionally the full text associated with the DocumentMeta
length	length of the returned string containing the json data

Returns

A newly allocated string containing the json data

document_meta_get_string()

char * document_meta_get_string

(

const DocumentMeta *

meta

)

Creates a human readable string describing a DocumentMeta.

Parameters

meta	The DocumentMeta struct to print

Returns

a newly allocated string containing the description

document_meta_is_equal()

bool document_meta_is_equal	(	const DocumentMeta *	a,
		const DocumentMeta *	b )

Compares to document metas and returns if they are equal.

This function doesn't tell you if a and b refer to the same document, it only tells you if the DocumentMetas are bitwise the same

Parameters

a	A DocumentMeta struct
b	Another DocumentMeta struct to compare to a

Returns

true if a and b are equal, false otherwise

document_meta_load_from_json()

DocumentMeta * document_meta_load_from_json

(

char *

jsonFile

)

create a DocumentMeta from json data saved by document_meta_get_json()

Parameters

jsonFile

a c string containing the json data

Returns

A newly allocated DocumentMeta containing metadata contained in the file, or NULL if invalid

document_meta_load_from_json_file()

DocumentMeta * document_meta_load_from_json_file

(

const char *

jsonFileName

)

create a DocumentMeta from json file saved by document_meta_save()

Parameters

jsonFileName

a filename of a json file to load

Returns

A newly allocated DocumentMeta containing metadata contained in the file, or NULL if invalid

document_meta_load_full_text_from_json_file()

char * document_meta_load_full_text_from_json_file

(

const char *

jsonFileName

)

create a DocumentMeta from json file saved by document_meta_save()

Parameters

jsonFileName

a filename of a json file to load

Returns

A newly allocated string with the text in the given file, or NULL if invalid

document_meta_new()

DocumentMeta * document_meta_new

(

void

)

Mallocs a DocumentMeta struct and initializes it.

Returns

A newly allocated DocumentMeta struct

document_meta_save()

bool document_meta_save	(	const char *	fileName,
		const DocumentMeta *	meta,
		const char *	fullText )

Saves a DocumentMeta to disk.

Parameters

fileName	The file name under which to save the DocumentMeta
meta	The DocumentMeta struct to save to disk
fullText	Optionally the full text associated with the DocumentMeta

Returns

true on success false on failure

pdf_data_free()

void pdf_data_free

(

PdfData *

data

)

Frees a PdfData struct.

Parameters

data	The PdfData struct to free, it is safe to pass NULL here

request_return_free()

void request_return_free

(

RequestReturn *

reqRet

)

Frees a RequestReturn struct.

Parameters

reqRet

The RequestReturn to free, it is safe to pass NULL here

request_return_new()

RequestReturn * request_return_new	(	size_t	count,
		size_t	maxCount )

Allocates a empty RequestReturn struct.

Parameters

count	number of DocumentMeta structs this struct contains
maxCount	maximum number of DocumentMeta structs requested by interface user

Returns

a newly allocated RequestReturn struct, to be freed with request_return_free()

sci_backend_get_id_by_name()

int sci_backend_get_id_by_name

(

const char *

name

)

gives you the id of the backend with a given name

Parameters

name	the name of the backend

Returns

the id of the backend or 0 if it is not available

sci_fill_meta()

RequestReturn * sci_fill_meta	(	const DocumentMeta *	meta,
		const FillReqest *	fill,
		size_t	maxCount,
		size_t	page )

Takes a DocumentMeta and tries to find maxCount documents that match the fields set in the meta struct.

Parameters

meta	A DocumentMeta struct with at least one value set. If backendId == 0 all backends will be checked until one can identify the document otherwise the backend with the id backendId will be used
fill	A pointer to a FillReqest struct that describes what fields are required by user, can be NULL for "don't care"
maxCount	maximum number of documents to match
page	if page is set > 0, the first page*maxCount entries are skipped and the subsequent results are returned instead

Returns

A RequestReturn, to be freed with request_return_free(), or NULL if none could be found

sci_find_by_author()

RequestReturn * sci_find_by_author	(	const char *	author,
		size_t	maxCount )

Tries to find the documents by a certain author.

Parameters

author	Author to search for
maxCount	maximum number of documents to match

Returns

A RequestReturn, to be freed with request_return_free(), or NULL if none could be found

sci_find_by_doi()

DocumentMeta * sci_find_by_doi	(	const char *	doi,
		int	backendId )

Tries to find the metadata of the document with the given DOI.

Parameters

doi	DOI to search for
backendId	The backend to use to find the DOI, or 0 for "any"

Returns

A filled DocumentMeta struct, to be freed with document_meta_free(), or NULL if none could be found

sci_find_by_journal()

RequestReturn * sci_find_by_journal	(	const char *	journal,
		size_t	maxCount )

Tries to find the documents by in a certain journal.

Parameters

journal	journal to search for
maxCount	maximum number of documents to match

Returns

A list of filled RequestReturn, to be freed with request_return_free(), or NULL if none could be found

sci_find_by_title()

DocumentMeta * sci_find_by_title

(

const char *

title

)

Tries to find the metadata of the document with the given title.

Parameters

title

Title to search for

Returns

A filled DocumentMeta struct, to be freed with document_meta_free(), or NULL if none could be found

sci_get_all_backends()

const BackendInfo ** sci_get_all_backends

(

void

)

gives you an array describing each backend registered with libscipaper.

Returns

a NULL terminated array of BackendInfo structs describing each backend, owned by libscipaper, do not free

sci_get_backend_count()

size_t sci_get_backend_count

(

void

)

gives you the number of backends currently registered

Returns

the number of backends currently registered

sci_get_backend_info()

const BackendInfo * sci_get_backend_info

(

int

id

)

gives you a BackendInfo struct describing the backend with the id

Parameters

id	the id of the backend you want information on

Returns

a const BackendInfo struct containing information on the requested backend, owned by libscipaper, do not free

sci_get_backend_name()

const char * sci_get_backend_name

(

int

id

)

gives you the name of the backend with id

Parameters

id	the id of the backend you want the name for

Returns

a const string with the name of the backend, or "Invalid" if not valid, has static lifetime and shall not be freed.

sci_get_document_pdf_data()

PdfData * sci_get_document_pdf_data

(

const DocumentMeta *

meta

)

Tries to get the PDF data of a certain document.

Will give only the PDF of the first document that matches meta

Parameters

meta	A DocumentMeta struct with at least one value set if backendId == 0 all backends will be checked until one can identify the document otherwise the backend with the id backendId will be used

Returns

Raw data of the PDF document

sci_get_document_text()

char * sci_get_document_text

(

const DocumentMeta *

meta

)

Tries to get the full text of a certain document.

Parameters

meta	A DocumentMeta struct with at least one value set if backendId == 0 all backends will be checked until one can identify the document otherwise the backend with the id backendId will be used

Returns

The full text of the document or NULL if the text is not available.

sci_get_version()

const VersionFixed * sci_get_version

(

void

)

get the version of scipaper in use

Returns

a const struct containing the version of scipaper in use. owned by libscipaper do not free

sci_log_set_verbosity()

void sci_log_set_verbosity

(

loglevel_t

verbosity

)

Sets the verbosity of sicpaper output.

Parameters

verbosity

The verbosity to set

sci_paper_init()

bool sci_paper_init	(	const char *	config_file,
		const char *	data,
		size_t	length )

Inits libscipaper, this function must be your first call to libscipaper, besides sci_get_version() and sci_log_set_verbosity()

Parameters

config_file	An optional file name to a config ini file for libscipaper, or NULL
data	An optional pointer to a keyfile in ram
length	The length of the data at data

Returns

true on success false on failure

sci_save_document_to_file()

bool sci_save_document_to_file	(	const DocumentMeta *	meta,
		const char *	fileName )

Saves the PDF of a certain document to disk.

Will only save the first document that matches meta

Parameters

meta	A DocumentMeta struct with at least one value set if backendId == 0 all backends will be checked until one can identify the document otherwise the backend with the id backendId will be used

Returns

true on success, false on failure

sci_save_pdf_to_file()

bool sci_save_pdf_to_file	(	const PdfData *	data,
		const char *	fileName )

Tries to get save the PDF of a certain document to disk.

Will only save the first document that matches meta

Parameters

data	A PdfData struct filled by sci_get_document_pdf_data

Returns

Raw data of the PDF document