Documenting functions...

Docs/OTServiceCreatePlaylist.3

@@ -0,0 +1,24 @@
+.TH OTServiceCreatePlaylist 3 "11 Jan 2021" "libopenTIDAL 1.0.0" "libopenTIDAL Manual"
+.SH NAME
+OTServiceCreatePlaylist \- Create a new playlist
+.SH SYNOPSIS
+.B #include <openTIDAL/openTIDAL.h>
+
+.BI "struct OTContentContainer *OTServiceCreatePlaylist (struct OTSessionContainer *" session ", char *" title ", char *" description ", void *" threadHandle ");"
+.SH DESCRIPTION
+The OTServiceCreatePlaylist service function creates a new user playlist. The metadata of the newly created playlist will be returned.
+This service call \fBmust\fP have a corresponding call to \fIOTDeallocContainer(3)\fP when the operation is complete.
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
+.SH RETURN VALUE
+If no memory allocation error occurred in allocating the \fIOTContentContainer(7)\fP, a
+pointer to an \fIOTContentContainer(7)\fP will be returned.
+Otherwise a NULL pointer will be returned.
+.SH "SEE ALSO"
+.BR OTServiceGetPlaylistEntityTag "(3), " OTServiceDeletePlaylistItem "(3), " OTServiceMovePlaylistItem "(3), "
+.BR OTServiceAddPlaylistItem "(3), " OTServiceAddPlaylistItems "(3) "

Docs/OTServiceGetBearerToken.3

@@ -14,6 +14,13 @@ to request an access token.
 The application makes a POST request with the deviceCode at the rate specified by interval.
 The device should continue requesting an access token until the status in the OTContentContainer
 is SUCCESS. Remember to deallocate the OTContentContainer after each polling-cycle.
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
 .SH RETURN VALUE
 If no memory allocation error occurred in allocating the \fIOTContentContainer(7)\fP, a
 pointer to an \fIOTContentContainer(7)\fP will be returned.

Docs/OTServiceGetDeviceCode.3

@@ -28,6 +28,13 @@ Username/Password and third-party oAuth2.0 authorisation methods are supported.
 
 This call \fBmust\fP have a corresponding call to \fIOTDeallocContainer(3)\fP
 when the operation is complete.
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
 .SH RETURN VALUE
 If no memory allocation error occurred in allocating the \fIOTContentContainer(7)\fP, a
 pointer to an \fIOTContentContainer(7)\fP will be returned.

Docs/OTServiceGetFavorites.3

@@ -0,0 +1,41 @@
+.TH OTServiceGetFavorites 3 "11 Jan 2021" "libopenTIDAL 1.0.0" "libopenTIDAL Manual"
+.SH NAME
+OTServiceGetFavorites \- Request user-based metadata
+.SH SYNOPSIS
+.B #include <openTIDAL/openTIDAL.h>
+
+.BI "struct OTContentContainer *OTServiceGetFavorites (struct OTSessionContainer *" session ", const char *const " suffix ", const int " limit ", const int " offset ", const char *const " order ", const char *const " orderDirection ", void *threadHandle);"
+.SH DESCRIPTION
+The OTServiceGetFavorites service function requests TIDAL metadata.
+The prefix and suffix parameter are used to specify the endpoint of the request.
+This service call \fBmust\fP have a corresponding call to \fIOTDeallocContainer(3)\fP when the operation is complete.
+
+.nf
+.B Suffixes
+"ids", "albums", "tracks", "videos", "artists", "playlists", "mixes"
+
+.B Pagination
+.fi
+Use the limit and offset parameters to control metadata pagination.
+Keep in mind that the TIDAL API will error out on certain limits.
+
+.nf
+.B Sorting
+.fi
+order: "DATE", "NAME", "ARTIST", "RELEASE_DATE", "MIX_TYPE"
+
+orderDirection: "ASC", "DESC"
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
+.SH RETURN VALUE
+If no memory allocation error occurred in allocating the \fIOTContentContainer(7)\fP, a
+pointer to an \fIOTContentContainer(7)\fP will be returned.
+Otherwise a NULL pointer will be returned.
+.SH "SEE ALSO"
+.BR OTServiceGetStandard "(3), " OTServiceGetPage "(3), "
+.BR OTServiceSearch "(3), " OTServiceGetStream "(3), " OTServiceCreatePlaylist "(3) "

Docs/OTServiceGetPage.3

@@ -0,0 +1,35 @@
+.TH OTServiceGetPage 3 "11 Jan 2021" "libopenTIDAL 1.0.0" "libopenTIDAL Manual"
+.SH NAME
+OTServiceGetPage \- Request dynamic page metadata
+.SH SYNOPSIS
+.B #include <openTIDAL/openTIDAL.h>
+
+.BI "struct OTContentContainer *OTServiceGetPage (struct OTSessionContainer *" session ", const char *const " suffix ", const char * const " id ", const int " limit ", const int " offset ", void *" threadHandle ");"
+.SH DESCRIPTION
+The OTServiceGetPage service function requests TIDAL dynamic page metadata.
+The suffix parameter is used to specify the endpoint of the request.
+This service call \fBmust\fP have a corresponding call to \fIOTDeallocContainer(3)\fP when the operation is complete.
+
+The id parameter is only used with the following suffixes ("album", "artist", "mix").
+Other suffixes: "home", "explore", "videos", "my_collection_my_mixes".
+Other dynamic pages can be requested. Seperate the path from the url ("pages/data/xxxxxxxxx" (Remove "pages/")).
+
+.nf
+.B Pagination
+.fi
+Use the limit and offset parameters to control metadata pagination.
+Keep in mind that the TIDAL API will error out on certain limits.
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
+.SH RETURN VALUE
+If no memory allocation error occurred in allocating the \fIOTContentContainer(7)\fP, a
+pointer to an \fIOTContentContainer(7)\fP will be returned.
+Otherwise a NULL pointer will be returned.
+.SH "SEE ALSO"
+.BR OTServiceGetStandard "(3), " OTServiceGetFavorites "(3), "
+.BR OTServiceSearch "(3), " OTServiceGetStream "(3), " OTServiceCreatePlaylist "(3) "

Docs/OTServiceGetPlaylistEntityTag.3

@@ -0,0 +1,29 @@
+.TH OTServiceGetPlaylistEntityTag 3 "11 Jan 2021" "libopenTIDAL 1.0.0" "libopenTIDAL Manual"
+.SH NAME
+OTServiceGetPlaylistEntityTag \- Request the playlist entity tag
+.SH SYNOPSIS
+.B #include <openTIDAL/openTIDAL.h>
+
+.BI "char *OTServiceGetPlaylistEntityTag (struct OTSessionContainer *session, const char *const id, void *threadHandle);"
+.SH DESCRIPTION
+The OTServiceGetPlaylistEntityTag service function requests the http header and parses the entity-tag key
+of the playlist. This entity-tag is used for optimistic concurrency control, as a way to help prevent simultaneous updates of
+a resource from overwriting each other. Applied with the http header key "If-None-Match".
+\fBOTServiceGetPlaylistEntityTag\fP() allocates an ASCII String with the http entity-tag value. You need to free the 
+allocated memory after use. Entity-tag handling is integrated into all \fBlibopenTIDAL\fP() resource manipulation service functions.
+
+This service call \fBmust\fP have a corresponding call to \fIOTDeallocContainer(3)\fP when the operation is complete.
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
+.SH RETURN VALUE
+If no memory allocation error occurred in allocating the \fIOTContentContainer(7)\fP, a
+pointer to an \fIOTContentContainer(7)\fP will be returned.
+Otherwise a NULL pointer will be returned.
+.SH "SEE ALSO"
+.BR OTServiceCreatePlaylist "(3), " OTServiceDeletePlaylistItem "(3), " OTServiceMovePlaylistItem "(3), "
+.BR OTServiceAddPlaylistItem "(3), " OTServiceAddPlaylistItems "(3) "

Docs/OTServiceGetStandard.3

@@ -4,17 +4,36 @@ OTServiceGetStandard \- Request standard metadata
 .SH SYNOPSIS
 .B #include <openTIDAL/openTIDAL.h>
 
-.BI "struct OTContentContainer *OTServiceGetStandard (struct OTSessionContainer *session, const char *const prefix, const char *const suffix, const char *const id, const int limit, const int offset, void *threadHandle);"
+.BI "struct OTContentContainer *OTServiceGetStandard (struct OTSessionContainer *" session ", const char *const " prefix ", const char *const " suffix ", const char *const " id ", const int " limit ", const int " offset ", void * "threadHandle ");"
 .SH DESCRIPTION
 The OTServiceGetStandard service function requests TIDAL metadata.
 The prefix and suffix parameter are used to specify the endpoint of the request.
 This service call \fBmust\fP have a corresponding call to \fIOTDeallocContainer(3)\fP when the operation is complete.
 
+.nf
+.B Prefixes & Suffixes (NULL = No Suffix)
+"albums" - NULL (ALL), "items", "items/credits", "review"
+"tracks" - NULL, "contributors", "credits", "mix", "recommendations"
+"videos" - NULL, "contributors", "credits", "recommendations"
+"artist" - NULL, "bio", "links", "mix", "toptracks", "videos"
+"playlists" - NULL, "items", "recommendations/items"
+"mixes" - "items"
 
+.B Pagination
+.fi
+Use the limit and offset parameters to control metadata pagination.
+Keep in mind that the TIDAL API will error out on certain limits.
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
 .SH RETURN VALUE
 If no memory allocation error occurred in allocating the \fIOTContentContainer(7)\fP, a
 pointer to an \fIOTContentContainer(7)\fP will be returned.
 Otherwise a NULL pointer will be returned.
 .SH "SEE ALSO"
-.BR OTServiceGetStandard "(3), " OTServiceGetFavorites "(3), " OTServiceGetPage "(3), "
+.BR OTServiceGetFavorites "(3), " OTServiceGetPage "(3), "
 .BR OTServiceSearch "(3), " OTServiceGetStream "(3), " OTServiceCreatePlaylist "(3) "

Docs/OTServiceGetStream.3

@@ -0,0 +1,39 @@
+.TH OTServiceGetStream 3 "11 Jan 2021" "libopenTIDAL 1.0.0" "libopenTIDAL Manual"
+.SH NAME
+OTServiceGetStream \- Request a track/video stream
+.SH SYNOPSIS
+.B #include <openTIDAL/openTIDAL.h>
+
+.BI "struct OTContentStreamContainer *OTServiceGetStream (struct OTSessionContainer *" session ", const char *const " prefix ", const char *const " id ", const int " isPreview ", void *" threadHandle ");"
+.SH DESCRIPTION
+The OTServiceStream service function requests TIDAL http streams.
+This service call \fBmust\fP have a corresponding call to \fIOTDeallocContainer(3)\fP when the operation is complete.
+
+The audio-quality is specified in the session configuration file but can be changed. Depending on the subscription type four
+different audio-quality presets are available. With the \fBAUDIO_LOW\fP preset, tracks are encoded in 96kbps AAC. \fBAUDIO_HIGH\fP
+preset tracks are encoded in 320kbps AAC. If the user has an active hifi subscription two additional modes are available.
+\fBAUDIO_LOSSLESS\fP preset tracks are encoded in 1411kbps 16bit/44.1kHz FLAC. \fBAUDIO_HI_RES\fP preset tracks are encoded in 24bit/96kHz
+MQA FLAC. \fIOTQuality(7)\fP.
+
+.nf
+.B Prefixes
+"tracks", "videos"
+
+.B Restricted Preview
+.fi
+With isPreview enabled, 30s previews of a track (64kbps 22.05kHz MP3) or a video (640x360 1116kbps MP4)
+are available. Keep in mind that this endpoint is enabled on a few clientIds. 
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
+.SH RETURN VALUE
+If no memory allocation error occurred in allocating the \fIOTContentStreamContainer(7)\fP, a
+pointer to an \fIOTContentStreamContainer(7)\fP will be returned.
+Otherwise a NULL pointer will be returned.
+.SH "SEE ALSO"
+.BR OTServiceGetStandard "(3), " OTServiceGetPage "(3), "
+.BR OTServiceFavorites "(3), " OTServiceSearch "(3), " OTServiceCreatePlaylist "(3) "

Docs/OTServiceLogout.3

@@ -15,6 +15,13 @@ authorization server get invalidated.
 Further interaction with the API is not possible without reauthenticating. 
 
 The restricted client-id based authorisation method will not be effected by this call.
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
 .SH RETURN VALUE
 \fIOTStatus(7)\fP
 .SH "SEE ALSO"

Docs/OTServiceRefreshBearerToken.3

@@ -15,6 +15,13 @@ the http-connector.
 
 This call \fBmust\fP have a corresponding call to \fIOTDeallocContainer(3)\fP
 when the operation is complete.
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
 .SH RETURN VALUE
 If no memory allocation error occurred in allocating the \fIOTContentContainer(7)\fP, a
 pointer to an \fIOTContentContainer(7)\fP will be returned.

Docs/OTServiceSearch.3

@@ -0,0 +1,34 @@
+.TH OTServiceSearch 3 "11 Jan 2021" "libopenTIDAL 1.0.0" "libopenTIDAL Manual"
+.SH NAME
+OTServiceSearch \- metadata search
+.SH SYNOPSIS
+.B #include <openTIDAL/openTIDAL.h>
+
+.BI "struct OTContentContainer *OTServiceSearch (struct OTSessionContainer *" session ", const char *const " suffix ", char *" query ", const int " limit ", const int " offset ", void *" threadHandle ");"
+.SH DESCRIPTION
+The OTServiceSearch service function requests TIDAL metadata.
+The suffix parameter is used to specify the endpoint of the request.
+This service call \fBmust\fP have a corresponding call to \fIOTDeallocContainer(3)\fP when the operation is complete.
+
+.nf
+.B Suffixes (NULL = ALL)
+NULL, "albums", "tracks", "videos", "artists", "playlists", "top-hits"
+
+.B Pagination
+.fi
+Use the limit and offset parameters to control metadata pagination.
+Keep in mind that the TIDAL API will error out on certain limits.
+
+.nf
+.B Thread Handle
+.fi
+You must never share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time.
+
+Use the session main handle by parsing a NULL pointer.
+.SH RETURN VALUE
+If no memory allocation error occurred in allocating the \fIOTContentContainer(7)\fP, a
+pointer to an \fIOTContentContainer(7)\fP will be returned.
+Otherwise a NULL pointer will be returned.
+.SH "SEE ALSO"
+.BR OTServiceGetStandard "(3), " OTServiceGetPage "(3), "
+.BR OTServiceFavorites "(3), " OTServiceGetStream "(3), " OTServiceCreatePlaylist "(3) "