1.7.2.9
Prysm
cohtml::Library Class Referenceabstract

This class encapsulates the global Cohtml library. More...

Public Member Functions

virtual ~Library ()
 
virtual SystemCreateSystem (const SystemSettings &settings)=0
 Create a Cohtml System that can hold multiple Views. More...
 
virtual void StopWorkers ()=0
 Stops all work happening on auxiliary threads. The developer should call this to break the loops in ExecuteResourceWork and ExecuteLayoutWork and then eventually join the threads doing the HB work. More...
 
virtual void Uninitialize (bool freeGlobalSdkMemory=false)=0
 Uninitializes the Cohtml library. More...
 
virtual void * GetFeatureInterface (unsigned featureID)=0
 Used for acquiring specific feature objects. More...
 
virtual void ExecuteWork (WorkType type, WorkExecutionMode mode, TaskFamilyId family=COHTML_ANY_TASK_FAMILY_ID)=0
 Executes Cohtml tasks. Some work in Cohtml has to happen asynchronously which improves performance and the scalability of the solution. The type of work is either Resources (loading, parsing, GC) or Layout. When new work is available, the user is notified through the OnWorkAvailable callback and should make sure that at some point that work is executed. The mode parameter is important to decide if you'll only do some tasks (WEM_UntilQueueEmpty) or use it with a dedicated thread until the Library lives. Using a dedicated thread (WEM_UntilQuit) is simpler, but offers less control. This method can be called on any thread. More...
 

Static Public Member Functions

static LibraryInitialize (const char *licenseKey, const LibraryParams &params)
 Initializes the library. More...
 
static LibraryInitializeWithRenderingLibrary (const char *licenseKey, const LibraryParamsWithExternalRenderingLibrary &params, renoir::IRenderingLibrary *renderingLibrary)
 Initializes the library with an externally initialized rendering library. More...
 
static const char * GetDefaultUserAgent ()
 Get default User Agent string which can be used to reset view UA. More...
 
static void HintThreadUsage (WorkType type)
 This hints Cohtml that the calling thread will be used for certain work. The call is optional and used for profiling purposes only. It is not necessary to call it in a final shipping environment. More...
 
static void DecodeURLString (const char *url, unsigned urlLen, char *decoded, unsigned *decodedSize)
 Decodes a URL string substituting any URL-encoded characters (%20, %21 etc.) with their ASCII counterparts i.e. 'my%20url.html' -> 'my url.html'. More...
 

Detailed Description

This class encapsulates the global Cohtml library.

Constructor & Destructor Documentation

◆ ~Library()

virtual cohtml::Library::~Library ( )
virtual

Member Function Documentation

◆ CreateSystem()

virtual System* cohtml::Library::CreateSystem ( const SystemSettings settings)
pure virtual

Create a Cohtml System that can hold multiple Views.

Parameters
settingsthe system creation parameters
Returns
a Cohtml system object

◆ DecodeURLString()

static void cohtml::Library::DecodeURLString ( const char *  url,
unsigned  urlLen,
char *  decoded,
unsigned *  decodedSize 
)
static

Decodes a URL string substituting any URL-encoded characters (%20, %21 etc.) with their ASCII counterparts i.e. 'my%20url.html' -> 'my url.html'.

Parameters
urlthe url string to decode
urlLenthe number of characters in the url
decodedpointer to the buffer where to copy the decoded string. Can be nullptr in order to query the size of the output
decodedSizethe length of the decoded string, including the terminating null

◆ ExecuteWork()

virtual void cohtml::Library::ExecuteWork ( WorkType  type,
WorkExecutionMode  mode,
TaskFamilyId  family = COHTML_ANY_TASK_FAMILY_ID 
)
pure virtual

Executes Cohtml tasks. Some work in Cohtml has to happen asynchronously which improves performance and the scalability of the solution. The type of work is either Resources (loading, parsing, GC) or Layout. When new work is available, the user is notified through the OnWorkAvailable callback and should make sure that at some point that work is executed. The mode parameter is important to decide if you'll only do some tasks (WEM_UntilQueueEmpty) or use it with a dedicated thread until the Library lives. Using a dedicated thread (WEM_UntilQuit) is simpler, but offers less control. This method can be called on any thread.

Parameters
typeSets the work type to schedule. Layout work shouldn't be executed if the UseDedicatedLayoutThread parameter is false. In that case the Layout will happen in the View::Advance calls.
modeSets the mode to use in the Execution. Note that WEM_UntilQuit will not return until Cohtml itself is uninitialized.
familySets the task family Layout work to execute. Each View has a task family (work only for that) that can be retrieved through View::GetTaskFamilyId. The parameter allows executing work for a specific View, you can also pass COHTML_ANY_TASK_FAMILY_ID, which will execute any Layout work available for all Views.

◆ GetDefaultUserAgent()

static const char* cohtml::Library::GetDefaultUserAgent ( )
static

Get default User Agent string which can be used to reset view UA.

◆ GetFeatureInterface()

virtual void* cohtml::Library::GetFeatureInterface ( unsigned  featureID)
pure virtual

Used for acquiring specific feature objects.

◆ HintThreadUsage()

static void cohtml::Library::HintThreadUsage ( WorkType  type)
static

This hints Cohtml that the calling thread will be used for certain work. The call is optional and used for profiling purposes only. It is not necessary to call it in a final shipping environment.

Parameters
typeSets the work type of this thread.

◆ Initialize()

static Library* cohtml::Library::Initialize ( const char *  licenseKey,
const LibraryParams params 
)
static

Initializes the library.

Parameters
licenseKeylicense key provided by Coherent Labs
paramsthe initialization parameters of the library.
Returns
A library object
Note
you can have only one library active at a time

◆ InitializeWithRenderingLibrary()

static Library* cohtml::Library::InitializeWithRenderingLibrary ( const char *  licenseKey,
const LibraryParamsWithExternalRenderingLibrary params,
renoir::IRenderingLibrary *  renderingLibrary 
)
static

Initializes the library with an externally initialized rendering library.

Parameters
licenseKeylicense key provided by Coherent Labs
paramsthe initialization parameters of the library.
renderingLibraryinitialized Rendering library to use.
Returns
A library object
Note
you can have only one library active at a time
use this only when you need to reuse the rendering library.

◆ StopWorkers()

virtual void cohtml::Library::StopWorkers ( )
pure virtual

Stops all work happening on auxiliary threads. The developer should call this to break the loops in ExecuteResourceWork and ExecuteLayoutWork and then eventually join the threads doing the HB work.

◆ Uninitialize()

virtual void cohtml::Library::Uninitialize ( bool  freeGlobalSdkMemory = false)
pure virtual

Uninitializes the Cohtml library.

Parameters
freeGlobalSdkMemoryfrees any global SDK memory
Warning
The last time you call this function you must call it with freeGlobalSdkMemory = true. After freeing the global SDK memory, it won't be possible to reinitialize the Library. Freeing the memory is usually done on application exit so all user allocations are cleared.