.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "WebService::ILS::OverDrive::Patron 3pm" .TH WebService::ILS::OverDrive::Patron 3pm "2018-10-11" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" WebService::ILS::OverDrive::Patron \- WebService::ILS module for OverDrive circulation services .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use WebService::ILS::OverDrive::Patron; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" These services require individual user credentials. See \*(L"WebService::ILS \s-1INDIVIDUAL USER AUTHENTICATION AND METHODS\*(R"\s0 .PP See WebService::ILS::OverDrive .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .ie n .SS "new (%params_hash or $params_hashref)" .el .SS "new (%params_hash or \f(CW$params_hashref\fP)" .IX Subsection "new (%params_hash or $params_hashref)" \fIAdditional constructor params:\fR .IX Subsection "Additional constructor params:" .ie n .IP """auth_token"" => auth token as previously obtained" 16 .el .IP "\f(CWauth_token\fR => auth token as previously obtained" 16 .IX Item "auth_token => auth token as previously obtained" .SH "INDIVIDUAL USER AUTHENTICATION METHODS" .IX Header "INDIVIDUAL USER AUTHENTICATION METHODS" .ie n .SS "auth_by_user_id ($user_id, $password, $website_id, $authorization_name)" .el .SS "auth_by_user_id ($user_id, \f(CW$password\fP, \f(CW$website_id\fP, \f(CW$authorization_name\fP)" .IX Subsection "auth_by_user_id ($user_id, $password, $website_id, $authorization_name)" \&\f(CW\*(C`website_id\*(C'\fR and \f(CW\*(C`authorization_name\*(C'\fR (domain) are provided by OverDrive .PP \fIReturns (access_token, access_token_type) or access_token\fR .IX Subsection "Returns (access_token, access_token_type) or access_token" .ie n .SS "Authentication at OverDrive \- Granted or ""3\-Legged"" Authorization" .el .SS "Authentication at OverDrive \- Granted or ``3\-Legged'' Authorization" .IX Subsection "Authentication at OverDrive - Granted or 3-Legged Authorization" With OverDrive there's an extra step \- an auth code is returned to the redirect back handler that needs to make an \s-1API\s0 call to convert it into a auth token. .PP An example: .PP .Vb 10 \& my $overdrive = WebService::ILS::OverDrive::Patron({ \& client_id => $client_id, \& client_secret => $client_secret, \& library_id => $library_id, \& }); \& my $redirect_url = $overdrive\->auth_url("http://myapp.com/overdrive\-auth"); \& $response\->redirect($redirect_url); \& ... \& /overdrive\-auth handler: \& my $auth_code = $req\->param( $overdrive\->auth_code_param_name ) \& or some_error_handling(), return; \& # my $state = $req\->param( $overdrive\->state_token_param_name )... \& local $@; \& eval { $overdrive\->auth_by_code( $auth_code ) }; \& if ($@) { some_error_handling(); return; } \& $session{overdrive_access_token} = $access_token; \& $session{overdrive_access_token_type} = $access_token_type; \& $session{overdrive_auth_token} = $auth_token; \& ... \& Somewhere else in your app: \& my $ils = WebService::ILS::Provider({ \& client_id => $client_id, \& client_secret => $client_secret, \& access_token => $session{overdrive_access_token}, \& access_token_type => $session{overdrive_access_token_type}, \& auth_token = $session{overdrive_auth_token} \& }); \& my $checkouts = $overdrive\->checkouts; .Ve .ie n .SS "auth_url ($redirect_uri, $state_token)" .el .SS "auth_url ($redirect_uri, \f(CW$state_token\fP)" .IX Subsection "auth_url ($redirect_uri, $state_token)" \fIInput params:\fR .IX Subsection "Input params:" .ie n .IP """redirect_uri"" => return url which will handle redirect back after auth" 18 .el .IP "\f(CWredirect_uri\fR => return url which will handle redirect back after auth" 18 .IX Item "redirect_uri => return url which will handle redirect back after auth" .PD 0 .ie n .IP """state_token"" => a token that is returned back unchanged;" 18 .el .IP "\f(CWstate_token\fR => a token that is returned back unchanged;" 18 .IX Item "state_token => a token that is returned back unchanged;" .PD for additional security; not required .SS "auth_code_param_name ()" .IX Subsection "auth_code_param_name ()" .SS "state_token_param_name ()" .IX Subsection "state_token_param_name ()" .ie n .SS "auth_by_code ($provider_code, $redirect_uri)" .el .SS "auth_by_code ($provider_code, \f(CW$redirect_uri\fP)" .IX Subsection "auth_by_code ($provider_code, $redirect_uri)" \fIReturns (access_token, access_token_type, auth_token) or access_token\fR .IX Subsection "Returns (access_token, access_token_type, auth_token) or access_token" .SS "auth_by_token ($provider_token)" .IX Subsection "auth_by_token ($provider_token)" \fIReturns (access_token, access_token_type, auth_token) or access_token\fR .IX Subsection "Returns (access_token, access_token_type, auth_token) or access_token" .SH "CIRCULATION METHOD SPECIFICS" .IX Header "CIRCULATION METHOD SPECIFICS" Differences to general WebService::ILS interface .ie n .SS "place_hold ($item_id, $notification_email_address, $auto_checkout)" .el .SS "place_hold ($item_id, \f(CW$notification_email_address\fP, \f(CW$auto_checkout\fP)" .IX Subsection "place_hold ($item_id, $notification_email_address, $auto_checkout)" \&\f(CW$notification_email_address\fR and \f(CW$auto_checkout\fR are optional. \&\f(CW$auto_checkout\fR defaults to false. .PP \fIReturns holds item record\fR .IX Subsection "Returns holds item record" .PP It is preferred that the \f(CW$notification_email_address\fR is specified. .PP If \f(CW$auto_checkout\fR is set to true, the item will be checked out as soon as it becomes available. .SS "checkouts ()" .IX Subsection "checkouts ()" For formats see \f(CW\*(C`checkout_formats()\*(C'\fR below .ie n .SS "checkout ($item_id, $format, $allow_multiple_format_checkouts)" .el .SS "checkout ($item_id, \f(CW$format\fP, \f(CW$allow_multiple_format_checkouts\fP)" .IX Subsection "checkout ($item_id, $format, $allow_multiple_format_checkouts)" \&\f(CW$format\fR and \f(CW$allow_multiple_format_checkouts\fR are optional. \&\f(CW$allow_multiple_format_checkouts\fR defaults to false. .PP \fIReturns checkout item record\fR .IX Subsection "Returns checkout item record" .PP An item can be available in multiple formats. Checkout is complete only when the format is specified. .PP Checkout can be actioned without format being specified. In that case an early return can be actioned. To complete checkout format must be locked later (see \fIlock_format()\fR below). That would be the case with \&\fIplace_hold()\fR with \f(CW$auto_checkout\fR set to true. Once format is locked, an early return is not possible. .PP If \f(CW$allow_multiple_format_checkouts\fR flag is set to true, multiple formats of the same item can be acioned. If it is false (default) and the item was already checked out, the checked out item record will be returned regardless of the format. .PP Checkout record will have an extra field \f(CW\*(C`format\*(C'\fR if format is locked in. .SS "checkout_formats ($item_id)" .IX Subsection "checkout_formats ($item_id)" \fIReturns a hashref of available title formats and immediate availability\fR .IX Subsection "Returns a hashref of available title formats and immediate availability" .PP .Vb 1 \& { format => available, ... } .Ve .PP If format is not immediately available it must be locked first .ie n .SS "lock_format ($item_id, $format)" .el .SS "lock_format ($item_id, \f(CW$format\fP)" .IX Subsection "lock_format ($item_id, $format)" \fIReturns locked format (should be the same as the input value)\fR .IX Subsection "Returns locked format (should be the same as the input value)" .ie n .SS "checkout_download_url ($item_id, $format, $error_url, $success_url)" .el .SS "checkout_download_url ($item_id, \f(CW$format\fP, \f(CW$error_url\fP, \f(CW$success_url\fP)" .IX Subsection "checkout_download_url ($item_id, $format, $error_url, $success_url)" \fIReturns OverDrive download url\fR .IX Subsection "Returns OverDrive download url" .PP Checked out items must be downloaded by users on the OverDrive site. This method returns the url where the user should be sent to (redirected). Once the download is complete, user will be redirected back to \&\f(CW$error_url\fR in case of an error, otherwise to optional \f(CW$success_url\fR if specified. .PP See .SH "NATIVE METHODS" .IX Header "NATIVE METHODS" .SS "native_patron ()" .IX Subsection "native_patron ()" See .SS "native_holds ()" .IX Subsection "native_holds ()" .ie n .SS "native_place_hold ($item_id, $notification_email_address, $auto_checkout)" .el .SS "native_place_hold ($item_id, \f(CW$notification_email_address\fP, \f(CW$auto_checkout\fP)" .IX Subsection "native_place_hold ($item_id, $notification_email_address, $auto_checkout)" See .SS "native_checkouts ()" .IX Subsection "native_checkouts ()" .SS "native_checkout_info ($item_id)" .IX Subsection "native_checkout_info ($item_id)" .ie n .SS "native_checkout ($item_id, $format, $allow_multiple_format_checkouts)" .el .SS "native_checkout ($item_id, \f(CW$format\fP, \f(CW$allow_multiple_format_checkouts\fP)" .IX Subsection "native_checkout ($item_id, $format, $allow_multiple_format_checkouts)" .SS "native_checkout_formats ($item_id)" .IX Subsection "native_checkout_formats ($item_id)" .ie n .SS "native_lock_format ($item_id, $format)" .el .SS "native_lock_format ($item_id, \f(CW$format\fP)" .IX Subsection "native_lock_format ($item_id, $format)" See .SH "LICENSE" .IX Header "LICENSE" Copyright (C) Catalyst \s-1IT NZ\s0 Ltd Copyright (C) Bywater Solutions .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "AUTHOR" .IX Header "AUTHOR" Srdjan JankoviX