Google Cloud Print सेवा 31 दिसंबर, 2020 के बाद काम नहीं करेगी. माइग्रेट करने में मदद के लिए, कृपया सहायता लेख पढ़ें.

इस पेज का अनुवाद Cloud Translation API से किया गया है.

प्रिवेट

Privet, क्लाउड डिवाइस लोकल डिस्कवरी एपीआई है. इसका इस्तेमाल क्लाउड सेवाएं करती हैं. इस दस्तावेज़ को इन सेक्शन में बांटा गया है:

परिचय: Privet के बारे में जानकारी
डिस्कवरी: स्थानीय डिस्कवरी के तरीके
एलान: स्थानीय खोज के लिए एलान
एपीआई: सामान्य क्लाउड डिवाइसों के लिए निजी एपीआई
Printer API: Privet APIs का इस्तेमाल प्रिंटर करते हैं
कुछ और जानकारी: अन्य डायग्राम

1. परिचय

क्लाउड से कनेक्ट किए गए डिवाइसों के कई फ़ायदे हैं. ये ऑनलाइन कन्वर्ज़न सेवाओं का इस्तेमाल कर सकते हैं. साथ ही, डिवाइस के ऑफ़लाइन होने पर भी जॉब की कतारें होस्ट कर सकते हैं. इसके अलावा, इन्हें दुनिया में कहीं से भी ऐक्सेस किया जा सकता है. हालांकि, किसी उपयोगकर्ता के पास कई क्लाउड डिवाइसों का ऐक्सेस होता है. इसलिए, हमें जगह के हिसाब से सबसे नज़दीकी डिवाइस ढूंढने का तरीका उपलब्ध कराना होगा. Privet प्रोटोकॉल का मकसद, क्लाउड डिवाइसों को स्थानीय डिवाइसों को खोजने के लिए उपलब्ध किसी सही तरीके से जोड़ना है, ताकि नए एनवायरमेंट में डिवाइसों को आसानी से खोजा जा सके.

इस प्रोटोकॉल के ये लक्ष्य हैं:

क्लाउड डिवाइसों को स्थानीय तौर पर खोजे जाने लायक बनाना
क्लाउड डिवाइसों को किसी क्लाउड सेवा के साथ रजिस्टर करना
रजिस्टर किए गए डिवाइसों को उनके क्लाउड वर्शन से जोड़ना
ऑफ़लाइन मोड चालू करना
इसे लागू करने की प्रोसेस को आसान बनाया गया है, ताकि छोटे डिवाइस इसका इस्तेमाल कर सकें

Privet प्रोटोकॉल के दो मुख्य हिस्से होते हैं: डिस्कवरी और एपीआई. डिस्कवरी का इस्तेमाल, लोकल नेटवर्क पर डिवाइस ढूंढने के लिए किया जाता है. साथ ही, एपीआई का इस्तेमाल डिवाइस के बारे में जानकारी पाने और कुछ कार्रवाइयां करने के लिए किया जाता है. इस पूरे दस्तावेज़ में, डिवाइस का मतलब क्लाउड से कनेक्ट किए गए ऐसे डिवाइस से है जो Privet प्रोटोकॉल लागू करता है.

2. डिस्कवरी

डिस्कवरी, ज़ीरो कॉन्फ़िगरेशन पर आधारित (mDNS + DNS-SD) प्रोटोकॉल है. डिवाइस में IPv4 लिंक-लोकल एड्रेसिंग लागू होनी चाहिए. डिवाइस को mDNS और DNS-SD की शर्तों का पालन करना होगा.

http://www.rfc-editor.org/rfc/rfc3927.txt (IPv4 लिंक-लोकल)
http://www.rfc-editor.org/rfc/rfc4862.txt (IPv6 Link-local)
http://www.rfc-editor.org/rfc/rfc6762.txt (mDNS)
http://www.rfc-editor.org/rfc/rfc6763.txt (DNS-SD)

डिवाइस को ऊपर दी गई खास बातों के मुताबिक, नाम के टकराव को हल करना होगा.

2.1. सेवा प्रकार

डीएनएस सेवा की खोज, सेवा के टाइप के लिए इस फ़ॉर्मैट का इस्तेमाल करती है: _applicationprotocol._transportprotocol. Privet प्रोटोकॉल के मामले में, DNS-SD के लिए सेवा का टाइप यह होना चाहिए: _privet._tcp

यह डिवाइस, अन्य तरह की सेवाएं भी लागू कर सकता है. हमारा सुझाव है कि डिवाइस पर लागू की गई सभी सेवाओं के लिए, एक ही सेवा के इंस्टेंस के नाम का इस्तेमाल करें. उदाहरण के लिए: कोई प्रिंटर, "Printer XYZ._privet._tcp" और "Printer XYZ._printer._tcp" सेवाओं को लागू कर सकता है. इससे उपयोगकर्ता के लिए सेटअप करना आसान हो जाएगा. हालांकि, Privet क्लाइंट सिर्फ़ "_privet._tcp" को खोजेंगे.

मुख्य सेवा टाइप के अलावा, डिवाइस को अपने संबंधित सबटाइप के लिए पीटीआर रिकॉर्ड का विज्ञापन दिखाना होगा (डीएनएस-एसडी स्पेसिफ़िकेशन: "7.1. चुनिंदा इंस्टेंस की गिनती (सबटाइप)" सेक्शन में जाकर देखें. फ़ॉर्मैट ऐसा होना चाहिए: _<subtype>._sub._privet._tcp

फ़िलहाल, सिर्फ़ प्रिंटर डिवाइस सबटाइप काम करता है. इसलिए, सभी प्रिंटर को दो पीटीआर रिकॉर्ड का विज्ञापन दिखाना होगा:

_privet._tcp.local.
_printer._sub._privet._tcp.local.

2.2. TXT रिकॉर्ड

डीएनएस सेवा की खोज, TXT रिकॉर्ड में किसी सेवा के बारे में वैकल्पिक जानकारी जोड़ने के लिए फ़ील्ड तय करती है. TXT रिकॉर्ड में की/वैल्यू पेयर होते हैं. हर कुंजी/वैल्यू पेयर, लंबाई वाले बाइट से शुरू होता है. इसके बाद, ज़्यादा से ज़्यादा 255 बाइट का टेक्स्ट होता है. कुंजी, पहले ‘=’ वर्ण से पहले का टेक्स्ट होती है. वहीं, वैल्यू, पहले ‘=’ वर्ण के बाद से लेकर आखिर तक का टेक्स्ट होती है. इस स्पेसिफ़िकेशन के मुताबिक, रिकॉर्ड में कोई वैल्यू नहीं हो सकती. ऐसे मामले में, कोई ‘=’ वर्ण नहीं होगा या ‘=’ वर्ण के बाद कोई टेक्स्ट नहीं होगा. (डीएनएस-एसडी की खास जानकारी देखें: "6.1. डीएनएस TXT रिकॉर्ड फ़ॉर्मैट के लिए, "डीएनएस TXT रिकॉर्ड के लिए सामान्य फ़ॉर्मैट के नियम" और "6.2. DNS-SD TXT Record Size" for the recommended length).

Privet को TXT रिकॉर्ड में, डिवाइस से यहां दिए गए की/वैल्यू पेयर भेजने की ज़रूरत होती है. कुंजी/वैल्यू स्ट्रिंग केस-इनसेंसिटिव होती हैं. उदाहरण के लिए, "CS=online" और "cs=ONLINE" एक ही हैं. TXT रिकॉर्ड में मौजूद जानकारी, /info API के ज़रिए ऐक्सेस की जा सकने वाली जानकारी के जैसी होनी चाहिए. इसके बारे में 4.1 में बताया गया है. एपीआई सेक्शन में जाकर देखें.

हमारा सुझाव है कि TXT रिकॉर्ड का साइज़ 512 बाइट से कम रखें.

2.2.1. txtvers

TXT स्ट्रक्चर का वर्शन. txtvers, TXT स्ट्रक्चर का पहला रिकॉर्ड होना चाहिए. फ़िलहाल, सिर्फ़ वर्शन 1 काम करता है.

txtvers=1

2.2.2. ty

इससे डिवाइस का ऐसा नाम मिलता है जिसे उपयोगकर्ता पढ़ सकता है. उदाहरण के लिए:

ty=Google Cloud Ready Printer Model XYZ

2.2.3. note (ज़रूरी नहीं)

इससे डिवाइस का ऐसा नाम मिलता है जिसे उपयोगकर्ता पढ़ सकता है. उदाहरण के लिए:

note=1st floor lobby printer

ध्यान दें: यह एक ज़रूरी नहीं है और इसे छोड़ा जा सकता है. हालांकि, अगर यह मौजूद है, तो उपयोगकर्ता को इस वैल्यू में बदलाव करने की अनुमति होनी चाहिए. डिवाइस रजिस्टर करते समय, इसी ब्यौरे का इस्तेमाल करना ज़रूरी है.

2.2.4. url

यह डिवाइस जिस सर्वर यूआरएल से कनेक्ट है (प्रोटोकॉल के साथ). उदाहरण के लिए:

url=https://www.google.com/cloudprint

2.2.5. टाइप

इस डिवाइस के साथ काम करने वाले डिवाइस के सबटाइप की कॉमा लगाकर अलग की गई सूची. इसका फ़ॉर्मैट यह है: "type=_subtype1,_subtype2". फ़िलहाल, डिवाइस का सिर्फ़ यह सबटाइप इस्तेमाल किया जा सकता है: printer.

type=printer

सूची में शामिल हर सबटाइप का विज्ञापन, उससे जुड़े पीटीआर रिकॉर्ड का इस्तेमाल करके किया जाना चाहिए. सेवा के हर उपलब्ध सबटाइप के लिए, एक आइटम होना चाहिए. सेवा के सबटाइप का नाम (<subtype>._sub._privet._tcp) यहां डिवाइस टाइप के बराबर होना चाहिए.

2.2.6. id

डिवाइस आईडी. अगर डिवाइस को अब तक रजिस्टर नहीं किया गया है, तो यह कुंजी मौजूद होनी चाहिए. हालांकि, वैल्यू खाली होनी चाहिए. उदाहरण के लिए:

  id=11111111-2222-3333-4444-555555555555
  id=

2.2.7. cs

इससे डिवाइस के मौजूदा कनेक्शन की स्थिति के बारे में पता चलता है. इस स्पेसिफ़िकेशन में, चार संभावित वैल्यू तय की गई हैं.

"ऑनलाइन" का मतलब है कि डिवाइस फ़िलहाल क्लाउड से कनेक्ट है.
"ऑफ़लाइन" का मतलब है कि डिवाइस लोकल नेटवर्क पर उपलब्ध है, लेकिन सर्वर से कनेक्ट नहीं हो सकता.
"कनेक्ट किया जा रहा है" का मतलब है कि डिवाइस चालू हो रहा है और अभी पूरी तरह से ऑनलाइन नहीं हुआ है.
"not-configured" से पता चलता है कि डिवाइस के इंटरनेट ऐक्सेस को अब तक कॉन्फ़िगर नहीं किया गया है. फ़िलहाल, इस वैल्यू का इस्तेमाल नहीं किया जाता. हालांकि, आने वाले समय में स्पेसिफ़िकेशन के वर्शन में यह काम आ सकती है.

उदाहरण के लिए:

cs=online
cs=offline
cs=connecting

अगर डिवाइस को किसी क्लाउड से रजिस्टर किया गया है, तो चालू होने पर उसे सर्वर से कनेक्टिविटी की जांच करनी चाहिए, ताकि कनेक्शन की स्थिति का पता लगाया जा सके. उदाहरण के लिए, डिवाइस की सेटिंग पाने के लिए क्लाउड एपीआई को कॉल करना. डिवाइस, इस वैल्यू की जानकारी देने के लिए, सूचनाओं के चैनल (जैसे, XMPP) की कनेक्शन स्थिति का इस्तेमाल कर सकता है. स्टार्टअप पर, बिना रजिस्टर किए गए डिवाइस किसी डोमेन को पिंग कर सकते हैं, ताकि वे अपने कनेक्शन की स्थिति का पता लगा सकें. उदाहरण के लिए, क्लाउड प्रिंट डिवाइसों के लिए www.google.com को पिंग करें.

3. घोषणाएं

डिवाइस के चालू, बंद या स्थिति बदलने पर, डिवाइस को mDNS स्पेसिफ़िकेशन में बताए गए तरीके से सूचना देनी होगी. इसे कम से कम दो बार सूचना भेजनी चाहिए. साथ ही, दोनों सूचनाओं के बीच कम से कम एक सेकंड का अंतराल होना चाहिए.

3.1. स्टार्टअप

डिवाइस के चालू होने पर, उसे mDNS स्पेसिफ़िकेशन में बताए गए तरीके के मुताबिक, जांच और सूचना देने के चरण पूरे करने होंगे. इस मामले में, SRV, PTR, और TXT रिकॉर्ड भेजे जाने चाहिए. हमारा सुझाव है कि अगर हो सके, तो सभी रिकॉर्ड को एक डीएनएस जवाब में ग्रुप करें. अगर ऐसा नहीं है, तो हम यह क्रम इस्तेमाल करने का सुझाव देते हैं: SRV, PTR, TXT रिकॉर्ड.

3.2. बंद करें

डिवाइस बंद होने पर, इसे दिलचस्पी रखने वाले सभी पक्षों को इसकी सूचना देनी चाहिए. इसके लिए, इसे TTL=0 वाला "गुडबाय पैकेट" भेजना चाहिए. इसके बारे में mDNS के दस्तावेज़ में बताया गया है.

3.3. अपडेट करें

अगर TXT में दी गई किसी भी जानकारी में बदलाव होता है, तो डिवाइस को अपडेट की सूचना भेजनी होगी. इस मामले में, सिर्फ़ नया TXT रिकॉर्ड भेजना काफ़ी है. उदाहरण के लिए, किसी डिवाइस के रजिस्टर होने के बाद, उसे अपडेट की सूचना भेजनी होगी. इसमें नए डिवाइस का आईडी शामिल होना चाहिए.

4. एपीआई

क्लाउड डिवाइस का पता चलने के बाद, क्लाइंट सीधे लोकल नेटवर्क पर डिवाइस से कम्यूनिकेट कर सकता है. सभी एपीआई, एचटीटीपी 1.1 पर आधारित हैं. डेटा फ़ॉर्मैट, JSON पर आधारित होते हैं. एपीआई अनुरोध, GET या POST अनुरोध हो सकते हैं.

हर अनुरोध में, "X-Privet-Token" हेडर होना ज़रूरी है. सिर्फ़ /privet/info अनुरोध में "X-Privet-Token" हेडर को खाली रखने की अनुमति है. ध्यान दें कि हेडर अब भी मौजूद होना चाहिए. अगर "X-Privet-Token" हेडर मौजूद नहीं है, तो डिवाइस को यह एचटीटीपी 400 गड़बड़ी वाला जवाब देना होगा:

HTTP/1.1 400 Missing X-Privet-Token header.

अगर "X-Privet-Token" हेडर खाली है या अमान्य है, तो डिवाइस को "invalid X-Privet-Token error" (invalid_x_privet_token) के साथ जवाब देना होगा. ज़्यादा जानकारी के लिए, गड़बड़ियों वाला सेक्शन देखें. इसका अपवाद सिर्फ़ /info API है. ऐसा क्यों किया जाता है और टोकन कैसे जनरेट किए जाने चाहिए, इस बारे में ज़्यादा जानने के लिए, परिशिष्ट A: XSSI और XSRF हमलों और उनसे बचाव देखें.

अगर अनुरोध किया गया एपीआई मौजूद नहीं है या काम नहीं करता है, तो डिवाइस को एचटीटीपी 404 गड़बड़ी का मैसेज दिखाना होगा.

4.1. एपीआई की उपलब्धता

किसी भी एपीआई (इसमें /info एपीआई भी शामिल है) को ऐक्सेस करने से पहले, डिवाइस को सर्वर से संपर्क करके स्थानीय सेटिंग की जांच करनी होगी. रीस्टार्ट करने के दौरान, स्थानीय सेटिंग को बनाए रखना ज़रूरी है. अगर सर्वर उपलब्ध नहीं है, तो आखिरी बार इस्तेमाल की गई स्थानीय सेटिंग का इस्तेमाल किया जाना चाहिए. अगर डिवाइस को अभी तक रजिस्टर नहीं किया गया है, तो इस पर डिफ़ॉल्ट सेटिंग लागू होनी चाहिए.

Cloud Print डिवाइसों को रजिस्टर करने, स्थानीय सेटिंग पाने, और उन्हें अपडेट करने के लिए, यह तरीका अपनाना होगा.

4.1.1. रजिस्ट्रेशन

डिवाइस रजिस्टर करते समय, उसे "local_settings" पैरामीटर की जानकारी देनी होगी. यह जानकारी इस तरह दी जाएगी:

{
       "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
        }
}

ये सेटिंग सेट की जा सकती हैं:

वैल्यू का नाम	वैल्यू टाइप	ब्यौरा
local_discovery	बूलियन	इससे पता चलता है कि लोकल डिस्कवरी की सुविधा इस्तेमाल करने की अनुमति है या नहीं. अगर वैल्यू "false" है, तो सभी लोकल एपीआई (इसमें /info भी शामिल है) और DNS-SD डिस्कवरी को बंद करना होगा. डिफ़ॉल्ट रूप से, नए डिवाइसों को रजिस्टर करने के लिए "true" पास करना होगा.
access_token_enabled	बूलियन (ज़रूरी नहीं)	इससे पता चलता है कि /accesstoken API को लोकल नेटवर्क पर दिखाना चाहिए या नहीं. डिफ़ॉल्ट रूप से, इसे "true" पर सेट होना चाहिए.
printer/local_printing_enabled	बूलियन (ज़रूरी नहीं)	इससे पता चलता है कि लोकल नेटवर्क पर, लोकल प्रिंटिंग की सुविधा (/printer/createjob, /printer/submitdoc, /printer/jobstate) उपलब्ध कराई जानी चाहिए या नहीं. डिफ़ॉल्ट रूप से, इसे "true" पर सेट होना चाहिए.
printer/conversion_printing_enabled	बूलियन (ज़रूरी नहीं)	इससे पता चलता है कि लोकल प्रिंटिंग, कन्वर्ज़न के लिए सर्वर को जॉब भेज सकती है या नहीं. यह विकल्प सिर्फ़ तब काम करता है, जब स्थानीय प्रिंटिंग की सुविधा चालू हो.
xmpp_timeout_value	int (ज़रूरी नहीं)	इससे XMPP चैनल के पिंग के बीच का समय (सेकंड में) पता चलता है. डिफ़ॉल्ट रूप से, यह वैल्यू 300 (5 मिनट) या इससे ज़्यादा होनी चाहिए.

अहम जानकारी: किसी भी वैकल्पिक वैल्यू के न होने का मतलब है कि डिवाइस पर, इससे जुड़ी सुविधा काम नहीं करती.

4.1.2. स्टार्टअप

डिवाइस के चालू होने पर, इसे सर्वर से संपर्क करना चाहिए. इससे यह पता चलेगा कि लोकल नेटवर्क में कौनसे एपीआई उपलब्ध हैं. Cloud Print से कनेक्ट किए गए प्रिंटर के लिए, उन्हें इस नंबर पर कॉल करना चाहिए:

/cloudprint/printer?printerid=<printer_id>

या

/cloudprint/list

/cloudprint/list के बजाय /cloudprint/printer को प्राथमिकता दी जाती है. हालांकि, दोनों काम करेंगे.

यह एपीआई, डिवाइस के मौजूदा पैरामीटर दिखाता है. इनमें लोकल एपीआई की सेटिंग भी शामिल हैं. सर्वर से मिलने वाला जवाब इस फ़ॉर्मैट में होगा:

"local_settings": {
        "current": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": true,
                "printer/conversion_printing_enabled": true,
                "xmpp_timeout_value": 300
         },
         "pending": {
                "local_discovery": true,
                "access_token_enabled": true,
                "printer/local_printing_enabled": false,
                "printer/conversion_printing_enabled": false,
                "xmpp_timeout_value": 500
         }
}

"current" ऑब्जेक्ट से पता चलता है कि फ़िलहाल कौनसी सेटिंग लागू हैं.

"pending" ऑब्जेक्ट, उन सेटिंग के बारे में बताता है जिन्हें डिवाइस पर लागू किया जाना चाहिए. ऐसा हो सकता है कि यह ऑब्जेक्ट मौजूद न हो.

जब डिवाइस को "लंबित है" सेटिंग दिखती हैं, तो उसे अपनी स्थिति अपडेट करनी होगी (नीचे देखें).

4.1.3. अपडेट करें

अगर सेटिंग अपडेट करने की ज़रूरत होगी, तो डिवाइस को XMPP सूचना भेजी जाएगी. सूचना इस फ़ॉर्मैट में होगी:

<device_id>/update_settings

इस तरह की सूचना मिलने पर, डिवाइस को सर्वर से क्वेरी करनी होगी, ताकि वह नई सेटिंग पा सके. Cloud Print की सुविधा वाले डिवाइसों के लिए, इनका इस्तेमाल करना ज़रूरी है:

/cloudprint/printer?printerid=<printer_id>

जब डिवाइस को /cloudprint/printer API के नतीजे के तौर पर "वे कार्रवाइयां जिनकी मंज़ूरी बाकी है" सेक्शन दिखता है (स्टार्टअप के समय या सूचना की वजह से), तो उसे नई सेटिंग याद रखने के लिए, अपनी इंटरनल स्थिति को अपडेट करना होगा. नई सेटिंग की पुष्टि करने के लिए, इसे सर्वर एपीआई को कॉल करना होगा. क्लाउड प्रिंटर के लिए, डिवाइस को /cloudprint/update API को कॉल करना होगा. साथ ही, "local_settings" पैरामीटर का इस्तेमाल करना होगा. ऐसा रजिस्ट्रेशन के दौरान किया जाता है.

XMPP चैनल से फिर से कनेक्ट करने पर, डिवाइस को /cloudprint/printer API को कॉल करना होगा. इससे यह पता चलेगा कि पिछली बार से लोकल सेटिंग में कोई बदलाव हुआ है या नहीं.

4.1.3.1. स्थानीय सेटिंग को मंज़ूरी मिलना बाकी है

डिवाइस, सर्वर एपीआई को कॉल करने के लिए "local_settings" पैरामीटर का इस्तेमाल करता है. इसमें "pending" सेक्शन कभी नहीं होना चाहिए.

4.1.3.2. Local Settings Current

सिर्फ़ डिवाइस, "local_settings" के "current" सेक्शन में बदलाव कर सकता है. बाकी सभी लोग "लंबित" सेक्शन में बदलाव करेंगे और डिवाइस के "मौजूदा" सेक्शन में बदलाव दिखने तक इंतज़ार करेंगे.

4.1.4. ऑफ़लाइन

स्टार्टअप के दौरान सर्वर से संपर्क न हो पाने पर, सूचना मिलने के बाद डिवाइस को आखिरी बार इस्तेमाल की गई लोकल सेटिंग का इस्तेमाल करना होगा.

4.1.5. डिवाइस को सेवा से मिटाना

अगर डिवाइस को सेवा (जैसे, GCP) से मिटा दिया गया है, तो डिवाइस को XMPP सूचना भेजी जाएगी. सूचना इस फ़ॉर्मैट में होगी:

<device_id>/delete

इस तरह की सूचना मिलने पर, डिवाइस को सर्वर पर जाकर यह देखना होगा कि वह किस स्थिति में है. Cloud Print डिवाइसों को इनका इस्तेमाल करना होगा:

/cloudprint/printer?printerid=<printer_id>

डिवाइस को एचटीटीपी का जवाब मिलना चाहिए, जिसमें success=false और डिवाइस/प्रिंटर की जानकारी नहीं होनी चाहिए. इसका मतलब है कि डिवाइस को सर्वर से हटा दिया गया है. डिवाइस को अपने क्रेडेंशियल मिटाने होंगे और डिफ़ॉल्ट फ़ैक्ट्री सेटिंग मोड पर जाना होगा.

जब भी डिवाइस को यह जवाब मिलता है कि उसे /cloudprint/printer API (स्टार्टअप, सेटिंग अपडेट करने की सूचना, रोज़ाना पिंग) की वजह से मिटा दिया गया है, तो उसे अपने क्रेडेंशियल मिटाने होंगे और डिफ़ॉल्ट मोड पर जाना होगा.

4.2. /privet/info API

Info API का इस्तेमाल करना ज़रूरी है. इसे हर डिवाइस पर लागू करना होगा. यह "/privet/info" यूआरएल के लिए एचटीटीपी GET अनुरोध है: GET /privet/info HTTP/1.1

जानकारी देने वाला एपीआई, डिवाइस और उस पर काम करने वाली सुविधाओं के बारे में बुनियादी जानकारी देता है. इस एपीआई को डिवाइस की स्थिति में कभी भी बदलाव नहीं करना चाहिए और न ही कोई कार्रवाई करनी चाहिए, क्योंकि यह XSRF हमलों के लिए असुरक्षित है. सिर्फ़ इस एपीआई को "X-Privet-Token" हेडर को खाली रखने की अनुमति है. क्लाइंट को /privet/info API को कॉल करना चाहिए. साथ ही, "X-Privet-Token" हेडर को X-Privet-Token पर सेट करना चाहिए: ""

जानकारी देने वाले एपीआई को, खोज के दौरान TXT रिकॉर्ड में मौजूद डेटा के मुताबिक डेटा दिखाना होगा.

4.2.1. इनपुट

/privet/info API में कोई इनपुट पैरामीटर नहीं है.

4.2.2. वापसी का टिकट

/privet/info API, डिवाइस और काम करने वाली सुविधाओं के बारे में बुनियादी जानकारी दिखाता है.

TXT कॉलम, DNS-SD TXT रिकॉर्ड में मौजूद फ़ील्ड को दिखाता है.

वैल्यू का नाम	वैल्यू टाइप	ब्यौरा	TXT
वर्शन	स्ट्रिंग	एपीआई का सबसे नया वर्शन (major.minor), फ़िलहाल 1.0
नाम	स्ट्रिंग	डिवाइस का ऐसा नाम जिसे आसानी से पढ़ा जा सकता है.	ty
ब्यौरा	स्ट्रिंग	(ज़रूरी नहीं) डिवाइस की जानकारी. उपयोगकर्ता के पास इसे बदलने का विकल्प होना चाहिए.	ध्यान दें
url	स्ट्रिंग	यह उस सर्वर का यूआरएल है जिससे यह डिवाइस कम्यूनिकेट कर रहा है. यूआरएल में प्रोटोकॉल की जानकारी शामिल होनी चाहिए. उदाहरण के लिए: https://www.google.com/cloudprint.	url
टाइप	स्ट्रिंग की सूची	साथ काम करने वाले डिवाइस टाइप की सूची.	टाइप
आईडी	स्ट्रिंग	डिवाइस आईडी. अगर डिवाइस को अब तक रजिस्टर नहीं किया गया है, तो यह खाली होता है.	आईडी
device_state	स्ट्रिंग	डिवाइस की स्थिति. idle का मतलब है कि डिवाइस तैयार है processing का मतलब है कि डिवाइस व्यस्त है और कुछ समय के लिए इसकी सुविधाएं सीमित हो सकती हैं stopped का मतलब है कि डिवाइस काम नहीं कर रहा है और उपयोगकर्ता को कार्रवाई करनी होगी
connection_state	स्ट्रिंग	सर्वर (base_url) से कनेक्शन की स्थिति online - कनेक्शन उपलब्ध है offline - कोई कनेक्शन नहीं है connecting - स्टार्टअप के चरण पूरे किए जा रहे हैं not-configured - कनेक्शन को अभी तक कॉन्फ़िगर नहीं किया गया है पंजीकृत डिवाइस, सूचना चैनल (जैसे कि XMPP कनेक्शन की स्थिति) की स्थिति के आधार पर, कनेक्शन की स्थिति की जानकारी दे सकता है.	cs
निर्माता	स्ट्रिंग	डिवाइस बनाने वाली कंपनी का नाम
मॉडल	स्ट्रिंग	डिवाइस का मॉडल
serial_number	स्ट्रिंग	डिवाइस का यूनीक आइडेंटिफ़ायर. इस स्पेसिफ़िकेशन में, यह एक यूयूआईडी होना चाहिए. (GCP 1.1 स्पेसिफ़िकेशन) (ज़रूरी नहीं) हमारा सुझाव है कि आप हर जगह एक ही सीरियल नंबर आईडी का इस्तेमाल करें, ताकि अलग-अलग क्लाइंट एक ही डिवाइस की पहचान कर सकें. उदाहरण के लिए, आईपीपी लागू करने वाले प्रिंटर, "printer-device-id" फ़ील्ड में इस सीरियल नंबर आईडी का इस्तेमाल कर सकते हैं.
फ़र्मवेयर	स्ट्रिंग	डिवाइस के फ़र्मवेयर का वर्शन
अपटाइम	int	डिवाइस बूट होने के बाद से बीता समय (सेकंड में).
setup_url	स्ट्रिंग	(ज़रूरी नहीं) सेटअप करने के निर्देशों वाले पेज का यूआरएल (प्रोटोकॉल के साथ)
support_url	स्ट्रिंग	(वैकल्पिक) सहायता, अक्सर पूछे जाने वाले सवालों की जानकारी देने वाले पेज का यूआरएल (प्रोटोकॉल के साथ)
update_url	स्ट्रिंग	(ज़रूरी नहीं) फ़र्मवेयर अपडेट करने के निर्देशों वाले पेज का यूआरएल (प्रोटोकॉल के साथ)
x-privet-token	स्ट्रिंग	X-Privet-Token हेडर की वैल्यू, जिसे XSSI और XSRF हमलों को रोकने के लिए सभी एपीआई को पास करना होता है. ज़्यादा जानकारी के लिए, 6.1. देखें.
api	एपीआई की जानकारी	इस्तेमाल किए जा सकने वाले एपीआई की सूची (नीचे दी गई है)
semantic_state	JSON	(ज़रूरी नहीं) डिवाइस की सिमैंटिक स्थिति, CloudDeviceState फ़ॉर्मैट में.

api - यह एक JSON सूची है. इसमें लोकल नेटवर्क के ज़रिए उपलब्ध एपीआई की सूची होती है. ध्यान दें कि ऐसा हो सकता है कि स्थानीय नेटवर्क पर, सभी एपीआई एक साथ उपलब्ध न हों. उदाहरण के लिए, हाल ही में कनेक्ट किए गए डिवाइस को सिर्फ़ /register एपीआई के साथ काम करना चाहिए:

"api": [
        "/privet/register",
]

डिवाइस रजिस्टर हो जाने के बाद, डिवाइस को /register API का इस्तेमाल बंद कर देना चाहिए. डिवाइस को सेवा से यह भी पता लगाना चाहिए कि लोकल नेटवर्क पर कौनसे एपीआई दिखाए जा सकते हैं. उदाहरण के लिए:

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

फ़िलहाल, ये एपीआई उपलब्ध हैं:

/privet/register - यह एपीआई, डिवाइस को लोकल नेटवर्क पर रजिस्टर करने के लिए है. (ज़्यादा जानकारी के लिए, /privet/register API देखें). डिवाइस के क्लाउड में रजिस्टर हो जाने के बाद, इस एपीआई को छिपाना ज़रूरी है.
/privet/accesstoken - डिवाइस से ऐक्सेस टोकन का अनुरोध करने के लिए एपीआई (ज़्यादा जानकारी के लिए, /privet/accesstoken एपीआई देखें).
/privet/capabilities - डिवाइस की सुविधाओं को वापस पाने के लिए एपीआई (ज़्यादा जानकारी के लिए, /privet/capabilities एपीआई देखें).
/privet/printer/* - यह एपीआई, "प्रिंटर" डिवाइस टाइप के लिए खास है. ज़्यादा जानकारी के लिए, प्रिंटर से जुड़े एपीआई देखें.

यहां /privet/info के जवाब का एक उदाहरण दिया गया है. (ध्यान दें कि /privet/register API मौजूद नहीं है, क्योंकि यह डिवाइस पहले से रजिस्टर है):

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "idle",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ]
}

यहां स्याही खत्म हो चुके प्रिंटर के लिए, /privet/info रिस्पॉन्स का उदाहरण दिया गया है. इसमें semantic_state फ़ील्ड पर ध्यान दें:

{
        "version": "1.0",
        "name": "Gene’s printer",
        "description": "Printer connected through Chrome connector",
        "url": "https://www.google.com/cloudprint",
        "type": [
                "printer"
        ],
        "id": "11111111-2222-3333-4444-555555555555",
        "device_state": "stopped",
        "connection_state": "online",
        "manufacturer": "Google",
        "model": "Google Chrome",
        "serial_number": "1111-22222-33333-4444",
        "firmware": "24.0.1312.52",
        "uptime": 600,
        "setup_url": "http://support.google.com/cloudprint/answer/1686197/?hl=en",
        "support_url": "http://support.google.com/cloudprint/?hl=en",
        "update_url": "http://support.google.com/cloudprint/?hl=en",
        "x-privet-token": "AIp06DjQd80yMoGYuGmT_VDAApuBZbInsQ:1358377509659",
        "api": [
                "/privet/accesstoken",
                "/privet/capabilities",
                "/privet/printer/submitdoc",
        ],
        "semantic_state": {
                "version": "1.0",
                "printer": {
                        "state": "STOPPED",
                        "marker_state": {
                                "item": [
                                        {
                                                "vendor_id": "ink",
                                                "state": "EXHAUSTED",
                                                "level_percent": 0
                                        }
                                ]
                        }
                }
        }
}

4.2.3. गड़बड़ियां

/privet/info API को सिर्फ़ तब गड़बड़ी दिखानी चाहिए, जब X-Privet-Token हेडर मौजूद न हो. यह एचटीटीपी 400 के लेवल वाली गड़बड़ी होनी चाहिए:

HTTP/1.1 400 Missing X-Privet-Token header.

4.3. /privet/register API

/privet/register API का इस्तेमाल करना ज़रूरी नहीं है. यह एक एचटीटीपी पोस्ट अनुरोध है. /privet/register API को, मान्य X-Privet-Token हेडर की जांच करनी चाहिए. डिवाइस को इस एपीआई को "/privet/register" यूआरएल पर लागू करना होगा:

POST /privet/register?action=start&user=user@domain.com HTTP/1.1
POST /privet/register?action=complete&user=user@domain.com HTTP/1.1

डिवाइस को /privet/register API सिर्फ़ तब दिखाना चाहिए, जब वह उस समय पहचान छिपाकर रजिस्ट्रेशन करने की अनुमति देता हो. उदाहरण के लिए:

जब डिवाइस चालू हो जाता है (या डिवाइस पर मौजूद किसी खास बटन पर क्लिक करने के बाद) और उसे अब तक रजिस्टर नहीं किया गया है, तो उसे /privet/register API को ऐक्सेस करने की अनुमति देनी चाहिए, ताकि लोकल नेटवर्क का कोई उपयोगकर्ता प्रिंटर को रजिस्टर कर सके.
रजिस्ट्रेशन पूरा होने के बाद, डिवाइस को /privet/register API को ऐक्सेस करने से रोकना चाहिए. इससे लोकल नेटवर्क पर मौजूद कोई दूसरा व्यक्ति, डिवाइस को फिर से रजिस्टर नहीं कर पाएगा.
कुछ डिवाइसों को रजिस्टर करने के अलग-अलग तरीके हो सकते हैं. साथ ही, उन्हें /privet/register API को बिल्कुल भी ऐक्सेस नहीं करना चाहिए. उदाहरण के लिए, Chrome Cloud Print कनेक्टर.

रजिस्ट्रेशन की प्रोसेस में तीन चरण होते हैं. Cloud Print के लिए, बिना पहचान ज़ाहिर किए रजिस्ट्रेशन करने के बारे में जानें.

पहचान छिपाकर रजिस्ट्रेशन करने की प्रोसेस शुरू करना.
क्लाइंट, /privet/register API को कॉल करके इस प्रोसेस को शुरू करता है. इस दौरान, डिवाइस उपयोगकर्ता से पुष्टि करने के लिए कह सकता है.
दावा टोकन पाएं.

क्लाइंट यह पता लगाने के लिए पोल करता है कि डिवाइस कब इस्तेमाल के लिए तैयार है. डिवाइस तैयार होने के बाद, वह सर्वर को रजिस्ट्रेशन टोकन और रजिस्ट्रेशन यूआरएल पाने का अनुरोध भेजता है. क्लाइंट को टोकन और यूआरएल वापस भेजना चाहिए. इस चरण के दौरान, अगर डिवाइस को रजिस्ट्रेशन शुरू करने के लिए कोई और कॉल मिलता है, तो उसे यह काम करना चाहिए:

अगर यह वही उपयोगकर्ता है जिसने रजिस्ट्रेशन शुरू किया था, तो पिछले सभी डेटा (अगर कोई है) को हटा दें और रजिस्ट्रेशन की नई प्रोसेस शुरू करें.
अगर यह कोई दूसरा उपयोगकर्ता है, तो device_busy गड़बड़ी और 30 सेकंड का टाइमआउट दिखाएं.

रजिस्ट्रेशन की प्रोसेस पूरी करें.

क्लाइंट के डिवाइस पर दावा करने के बाद, उसे डिवाइस को सूचना देनी चाहिए, ताकि रजिस्ट्रेशन पूरा किया जा सके. रजिस्ट्रेशन की प्रोसेस पूरी होने के बाद, डिवाइस को अपडेट की सूचना भेजनी चाहिए. इसमें नया डिवाइस आईडी भी शामिल होना चाहिए.

ध्यान दें: जब डिवाइस /privet/register एपीआई कॉल को प्रोसेस कर रहा हो, तब एक साथ अन्य /privet/register एपीआई कॉल प्रोसेस नहीं किए जा सकते. डिवाइस को device_busy गड़बड़ी और 30 सेकंड का टाइम आउट दिखाना होगा.

हमारा सुझाव है कि डिवाइस पर रजिस्ट्रेशन के लिए, उपयोगकर्ता की पुष्टि करना ज़रूरी है. अगर इसे लागू किया जाता है, तो डिवाइस को /privet/register?action=start API कॉल मिलने के बाद, उपयोगकर्ता की पुष्टि होने तक इंतज़ार करना होगा. क्लाइंट, /privet/register?action=getClaimToken API को कॉल करेगा. इससे यह पता चलेगा कि उपयोगकर्ता की पुष्टि कब पूरी हुई और दावा करने वाला टोकन कब उपलब्ध है. अगर उपयोगकर्ता डिवाइस पर रजिस्ट्रेशन रद्द करता है (जैसे, 'रद्द करें' बटन दबाता है), तो user_cancel गड़बड़ी का मैसेज दिखाना ज़रूरी है. अगर उपयोगकर्ता ने तय समयसीमा के अंदर रजिस्ट्रेशन की पुष्टि नहीं की है, तो confirmation_timeout गड़बड़ी का मैसेज दिखाना ज़रूरी है. ज़्यादा जानकारी के लिए, डिफ़ॉल्ट सेक्शन देखें.

4.3.1. इनपुट

/privet/register API के ये इनपुट पैरामीटर हैं:

नाम	मान
ऐक्शन गेम	यह इनमें से कोई एक हो सकता है: start - रजिस्ट्रेशन की प्रोसेस शुरू करने के लिए getClaimToken - डिवाइस के लिए दावा टोकन वापस पाने के लिए cancel - रजिस्ट्रेशन की प्रोसेस रद्द करने के लिए complete - रजिस्ट्रेशन की प्रोसेस पूरी करने के लिए
उपयोगकर्ता	उस उपयोगकर्ता का ईमेल पता जो इस डिवाइस पर दावा करेगा.

नाम

मान

ऐक्शन गेम

यह इनमें से कोई एक हो सकता है:
start - रजिस्ट्रेशन की प्रोसेस शुरू करने के लिए
getClaimToken - डिवाइस के लिए दावा टोकन वापस पाने के लिए
cancel - रजिस्ट्रेशन की प्रोसेस रद्द करने के लिए
complete - रजिस्ट्रेशन की प्रोसेस पूरी करने के लिए

उपयोगकर्ता

उस उपयोगकर्ता का ईमेल पता जो इस डिवाइस पर दावा करेगा.

डिवाइस को यह जांच करनी होगी कि सभी कार्रवाइयों (शुरू करें, getClaimToken, रद्द करें, पूरा करें) के लिए इस्तेमाल किया गया ईमेल पता एक जैसा हो.

4.3.2. वापसी का टिकट

/privet/register API यह डेटा दिखाता है:

वैल्यू का नाम	वैल्यू टाइप	ब्यौरा
ऐक्शन गेम	स्ट्रिंग	इनपुट पैरामीटर में दी गई कार्रवाई के जैसी कार्रवाई.
उपयोगकर्ता	स्ट्रिंग (ज़रूरी नहीं)	यह इनपुट पैरामीटर में मौजूद उपयोगकर्ता ही होता है. अगर इनपुट में इसे शामिल नहीं किया गया है, तो यह मौजूद नहीं हो सकता.
टोकन	स्ट्रिंग (ज़रूरी नहीं)	रजिस्ट्रेशन टोकन. "getClaimToken" के जवाब के लिए यह ज़रूरी है. "start", "complete", और "cancel" के लिए इसे शामिल नहीं किया जाता.
claim_url	स्ट्रिंग (ज़रूरी नहीं)	रजिस्ट्रेशन यूआरएल ("getClaimToken" रिस्पॉन्स के लिए ज़रूरी है. "start", "complete", "cancel" के लिए इसे शामिल नहीं किया जाता). क्लाउड प्रिंटर के लिए, यह सर्वर से मिला "complete_invite_url" होना चाहिए.
automated_claim_url	स्ट्रिंग (ज़रूरी नहीं)	रजिस्ट्रेशन यूआरएल ("getClaimToken" रिस्पॉन्स के लिए ज़रूरी है. "start", "complete", "cancel" के लिए इसे शामिल नहीं किया जाता). क्लाउड प्रिंटर के लिए, यह सर्वर से मिला "automated_invite_url" होना चाहिए.
device_id	स्ट्रिंग (ज़रूरी नहीं)	नया डिवाइस आईडी ("start" रिस्पॉन्स के लिए नहीं दिया गया है, लेकिन "complete" के लिए ज़रूरी है).

डिवाइस को /privet/info API के जवाब में अपना डिवाइस आईडी तब तक नहीं भेजना चाहिए, जब तक रजिस्ट्रेशन पूरा न हो जाए.

उदाहरण 1:

{
        "action": "start",
        "user": "user@domain.com",
}

उदाहरण 2:

{
        "action": "getClaimToken",
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "claim_url": "https://domain.com/SoMeUrL",
}

उदाहरण 3:

{
        "action": "complete",
        "user": "user@domain.com",
        "device_id": "11111111-2222-3333-4444-555555555555",
}

4.3.3. गड़बड़ियां

/privet/register API से ये गड़बड़ियां मिल सकती हैं. ज़्यादा जानकारी के लिए, गड़बड़ियां सेक्शन देखें:

गड़बड़ी	ब्यौरा
device_busy	डिवाइस व्यस्त है और अनुरोध की गई कार्रवाई को पूरा नहीं कर सकता. टाइम आउट होने के बाद, फिर से कोशिश करें.
pending_user_action	"getClaimToken" के जवाब में यह गड़बड़ी तब दिखती है, जब डिवाइस पर उपयोगकर्ता की पुष्टि होना बाकी हो. साथ ही, "getClaimToken" अनुरोध को टाइम आउट के बाद फिर से आज़माना चाहिए.
user_cancel	उपयोगकर्ता ने डिवाइस से रजिस्ट्रेशन की प्रोसेस को साफ़ तौर पर रद्द कर दिया है.
confirmation_timeout	उपयोगकर्ता की पुष्टि करने का समय खत्म हो जाता है.
invalid_action	अमान्य कार्रवाई को कॉल किया गया है. उदाहरण के लिए, अगर क्लाइंट ने action=start और action=getClaimToken को कॉल करने से पहले action=complete को कॉल किया.
invalid_params	अनुरोध में अमान्य पैरामीटर दिए गए हैं. (भविष्य में काम करने के लिए, अज्ञात पैरामीटर को अनदेखा किया जाना चाहिए). उदाहरण के लिए, अगर क्लाइंट ने action=unknown या user= को कॉल किया है, तो इसे दिखाएं.
device_config_error	डिवाइस पर तारीख/समय (या कुछ अन्य सेटिंग) गलत है. उपयोगकर्ता को डिवाइस की इंटरनल वेबसाइट पर जाकर, डिवाइस की सेटिंग कॉन्फ़िगर करनी होगी.
अॉफ़लाइन	फ़िलहाल, डिवाइस ऑफ़लाइन है और सर्वर से कनेक्ट नहीं हो सकता.
server_error	रजिस्ट्रेशन प्रोसेस के दौरान सर्वर में कोई गड़बड़ी हुई.
invalid_x_privet_token	अनुरोध में X-Privet-Token अमान्य है या खाली है.

रजिस्ट्रेशन पूरा होने के बाद, डिवाइस को /privet/register API को ऐक्सेस करने की अनुमति नहीं देनी चाहिए. अगर डिवाइस /privet/register एपीआई को ऐक्सेस करने की अनुमति नहीं देता है, तो उसे एचटीटीपी 404 गड़बड़ी का मैसेज दिखाना होगा. इसलिए, अगर कोई डिवाइस पहले से रजिस्टर है, तो इस एपीआई को कॉल करने पर 404 कोड मिलना चाहिए. अगर X-Privet-Token हेडर मौजूद नहीं है, तो डिवाइस को एचटीटीपी 400 गड़बड़ी का मैसेज दिखाना होगा.

4.4. /privet/accesstoken API

/privet/accesstoken API का इस्तेमाल करना ज़रूरी नहीं है. यह एक एचटीटीपी GET अनुरोध है. /privet/accesstoken API को "X-Privet-Token" हेडर की पुष्टि करनी होगी. डिवाइस को इस एपीआई को "/privet/accesstoken" यूआरएल पर लागू करना होगा:

GET /privet/accesstoken HTTP/1.1

जब डिवाइस को /accesstoken एपीआई कॉल मिलता है, तो उसे सर्वर को कॉल करना चाहिए, ताकि वह दिए गए उपयोगकर्ता के लिए ऐक्सेस टोकन वापस पा सके. इसके बाद, उसे क्लाइंट को टोकन वापस भेजना चाहिए. इसके बाद, क्लाइंट इस डिवाइस को क्लाउड के ज़रिए ऐक्सेस करने के लिए, ऐक्सेस टोकन का इस्तेमाल करेगा.

क्लाउड प्रिंट डिवाइसों को यह एपीआई कॉल करना होगा:

/cloudprint/proximitytoken

और लोकल एपीआई से "printerid=<printer_id>" और "user" पैरामीटर पास करें. अगर अनुरोध पूरा हो जाता है, तो सर्वर के जवाब में यह ऑब्जेक्ट शामिल होगा:

"proximity_token": {
        "user": "user@domain.com",
        "token": "AAA111222333444555666777",
        "expires_in": 600
}

Cloud Print की सुविधा वाले डिवाइसों को, स्थानीय /privet/accesstoken API कॉल के जवाब में "proximity_token" ऑब्जेक्ट की वैल्यू पास करनी होगी. अगर डिवाइस सभी पैरामीटर (उन पैरामीटर को भी शामिल करके जिनके बारे में इस स्पेसिफ़िकेशन में नहीं बताया गया है) को पूरा करता है, तो यह ज़्यादा फ़ायदेमंद (भविष्य के लिए बेहतर) होता है.

4.4.1. इनपुट

/privet/accesstoken API में ये इनपुट पैरामीटर होते हैं:

नाम	मान
उपयोगकर्ता	उस उपयोगकर्ता का ईमेल पता जिसने इस ऐक्सेस टोकन का इस्तेमाल किया. अनुरोध में यह खाली हो सकता है.

4.4.2. वापसी का टिकट

/privet/accesstoken API, यह डेटा दिखाता है:

वैल्यू का नाम	वैल्यू टाइप	ब्यौरा
टोकन	स्ट्रिंग	सर्वर से मिला ऐक्सेस टोकन
उपयोगकर्ता	स्ट्रिंग	इनपुट पैरामीटर में मौजूद उपयोगकर्ता.
expires_in	int	इस टोकन की समयसीमा खत्म होने में बचे हुए सेकंड की संख्या. यह कुकी सर्वर से मिली है और इस रिस्पॉन्स में पास की गई है.

उदाहरण:

{
        "token": "AAA111222333444555666777",
        "user": "user@domain.com",
        "expires_in": 600
}

4.4.3. गड़बड़ियां

/privet/accesstoken API, ये गड़बड़ियां दिखा सकता है. ज़्यादा जानकारी के लिए, गड़बड़ियां सेक्शन देखें:

गड़बड़ी	ब्यौरा
अॉफ़लाइन	फ़िलहाल, डिवाइस ऑफ़लाइन है और सर्वर से कनेक्ट नहीं हो सकता.
access_denied	ज़रूरी अधिकार नहीं हैं. पहुंच नामंजूर. अगर सर्वर ने अनुरोध को साफ़ तौर पर अस्वीकार कर दिया है, तो डिवाइस को यह गड़बड़ी दिखानी चाहिए.
invalid_params	अनुरोध में अमान्य पैरामीटर दिए गए हैं. (भविष्य में काम करने के लिए, अज्ञात पैरामीटर को अनदेखा किया जाना चाहिए). उदाहरण के लिए, अगर क्लाइंट ने /accesstoken?user= या /accesstoken को कॉल किया है.
server_error	सर्वर त्रुटि.
invalid_x_privet_token	अनुरोध में X-Privet-Token अमान्य है या खाली है.

अगर डिवाइस /privet/accesstoken API को ऐक्सेस करने की अनुमति नहीं देता है, तो उसे एचटीटीपी 404 गड़बड़ी का मैसेज दिखाना होगा. अगर X-Privet-Token हेडर मौजूद नहीं है, तो डिवाइस को एचटीटीपी 400 गड़बड़ी का मैसेज दिखाना होगा.

4.5. /privet/capabilities API

/privet/capabilities API का इस्तेमाल करना ज़रूरी नहीं है. यह एक एचटीटीपी GET अनुरोध है. /privet/capabilities API को "X-Privet-Token" हेडर की पुष्टि करनी होगी. डिवाइस को इस एपीआई को "/privet/capabilities" यूआरएल पर लागू करना होगा:

GET /privet/capabilities HTTP/1.1

जब डिवाइस को /capabilities API कॉल मिलता है, तो अगर डिवाइस में यह सुविधा उपलब्ध है, तो उसे सर्वर से संपर्क करना चाहिए, ताकि अपडेट की गई सुविधाएं मिल सकें. उदाहरण के लिए, अगर कोई प्रिंटर, Cloud Print सेवा के ज़रिए प्रिंट जॉब (स्थानीय तौर पर मिला) को खुद पर पोस्ट करने की सुविधा देता है, तो उसे वे सुविधाएं दिखानी चाहिए जो Cloud Print सेवा दिखाती है. इस मामले में, Cloud Print, प्रिंटर की मूल क्षमताओं में बदलाव कर सकता है. इसके लिए, वह नई सुविधाएं जोड़ता है. इन सुविधाओं का इस्तेमाल, प्रिंटर को जॉब भेजने से पहले किया जा सकता है. सबसे आम मामला, इस्तेमाल किए जा सकने वाले दस्तावेज़ों के टाइप की सूची है. अगर प्रिंटर ऑफ़लाइन है, तो उसे उन दस्तावेज़ों के टाइप की जानकारी देनी चाहिए जिन्हें वह प्रिंट कर सकता है. हालांकि, अगर प्रिंटर ऑनलाइन है और Cloud Print में रजिस्टर है, तो उसे "*/*" को काम करने वाले टाइप में से एक के तौर पर दिखाना होगा. इस मामले में, Cloud Print सेवा ज़रूरी कन्वर्ज़न करेगी. ऑफ़लाइन प्रिंटिंग के लिए, प्रिंटर को कम से कम "image/pwg-raster" फ़ॉर्मैट के साथ काम करना ज़रूरी है.

4.5.1. इनपुट

/privet/capabilities API में ये इनपुट पैरामीटर होते हैं:

नाम	मान
अॉफ़लाइन	(ज़रूरी नहीं) इसकी वैल्यू सिर्फ़ "offline=1" हो सकती है. इस मामले में, डिवाइस को ऑफ़लाइन इस्तेमाल करने की सुविधाएं वापस मिलनी चाहिए. हालांकि, ऐसा तब होना चाहिए, जब ये सुविधाएं "ऑनलाइन" सुविधाओं से अलग हों.

नाम

मान

अॉफ़लाइन

(ज़रूरी नहीं) इसकी वैल्यू सिर्फ़ "offline=1" हो सकती है. इस मामले में, डिवाइस को ऑफ़लाइन इस्तेमाल करने की सुविधाएं वापस मिलनी चाहिए. हालांकि, ऐसा तब होना चाहिए, जब ये सुविधाएं "ऑनलाइन" सुविधाओं से अलग हों.

4.5.2. वापसी का टिकट

/privet/capabilities API, डिवाइस की क्षमताओं को Cloud Device Description (CDD) JSON फ़ॉर्मैट में दिखाता है. ज़्यादा जानकारी के लिए, CDD दस्तावेज़ देखें. प्रिंटर को यहां कम से कम, इस्तेमाल किए जा सकने वाले टाइप की सूची दिखानी होगी. उदाहरण के लिए, फ़िलहाल ऑनलाइन मौजूद Cloud के लिए सेट अप किए गए प्रिंटर से, कम से कम इस तरह की जानकारी मिल सकती है:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" },
                        { "content_type": "*/*" }
                ]
        }
}

और जब यह सर्वर से डिसकनेक्ट हो जाता है, तो यह ये वैल्यू दिखा सकता है:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        {
                                "content_type": "application/pdf",
                                "min_version": "1.4"
                        },
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

ध्यान दें: प्रिंटर, ऑर्डर का इस्तेमाल करके, प्रिंट किए जा सकने वाले कॉन्टेंट टाइप की प्राथमिकता तय करते हैं. उदाहरण के लिए, ऊपर दिए गए सैंपल में, प्रिंटर यह बताता है कि वह "image/pwg-raster" और "image/jpeg" के बजाय "application/pdf" डेटा को प्राथमिकता देता है. अगर मुमकिन हो, तो क्लाइंट को प्रिंटर की प्राथमिकता का पालन करना चाहिए (ज़्यादा जानकारी के लिए, CDD दस्तावेज़ देखें).

4.5.3. गड़बड़ियां

/privet/capabilities API, ये गड़बड़ियां दिखा सकता है. ज़्यादा जानकारी के लिए, गड़बड़ियां सेक्शन देखें:

गड़बड़ी	ब्यौरा
invalid_x_privet_token	अनुरोध में X-Privet-Token अमान्य है या खाली है.

अगर डिवाइस, /privet/capabilities एपीआई को ऐक्सेस करने की अनुमति नहीं देता है, तो उसे HTTP 404 गड़बड़ी का मैसेज दिखाना होगा. अगर X-Privet-Token हेडर मौजूद नहीं है, तो डिवाइस को एचटीटीपी 400 गड़बड़ी का मैसेज दिखाना होगा.

4.6. गड़बड़ियां

ऊपर दिए गए एपीआई से गड़बड़ियां इस फ़ॉर्मैट में दिखती हैं:

वैल्यू का नाम	वैल्यू टाइप	ब्यौरा
गड़बड़ी	स्ट्रिंग	गड़बड़ी का टाइप (हर एपीआई के लिए तय किया जाता है)
ब्यौरा	स्ट्रिंग (ज़रूरी नहीं)	गड़बड़ी के बारे में ऐसी जानकारी जिसे कोई भी व्यक्ति आसानी से पढ़ सके.
server_api	स्ट्रिंग (ज़रूरी नहीं)	सर्वर की गड़बड़ी होने पर, इस फ़ील्ड में उस सर्वर एपीआई की जानकारी होती है जो काम नहीं कर सका.
server_code	int (ज़रूरी नहीं)	सर्वर की गड़बड़ी होने पर, इस फ़ील्ड में वह गड़बड़ी कोड होता है जो सर्वर ने दिखाया था.
server_http_code	int (ज़रूरी नहीं)	अगर सर्वर में एचटीटीपी गड़बड़ी होती है, तो इस फ़ील्ड में, सर्वर से मिला एचटीटीपी गड़बड़ी कोड होता है.
टाइम आउट	int (ज़रूरी नहीं)	क्लाइंट को फिर से कोशिश करने से पहले कितने सेकंड इंतज़ार करना चाहिए (सिर्फ़ ठीक की जा सकने वाली गड़बड़ियों के लिए). क्लाइंट को इस वैल्यू से लेकर + 20% तक की वैल्यू के बीच, टाइम आउट की असल वैल्यू को रैंडमाइज़ करना होगा.

अगर X-Privet-Token हेडर मौजूद नहीं है, तो सभी एपीआई को एचटीटीपी 400 गड़बड़ी का मैसेज दिखाना होगा.

HTTP/1.1 400 Missing X-Privet-Token header.

उदाहरण 1:

{
        "error": "server_error",
        "description": "Service unavailable",
        "server_api": "/submit",
        "server_http_code": 503
}

उदाहरण 2:

{
        "error": "printer_busy",
        "description": "Printer is currently printing other job",
        "timeout": 15
}

5. Printer API

यह प्रोटोकॉल, प्रिंटर जैसे डिवाइसों के साथ काम करता है. इस तरह के डिवाइस, प्रिंटर से जुड़ी कुछ खास सुविधाएं लागू कर सकते हैं. क्लाउड के लिए तैयार प्रिंटर से प्रिंट करने पर, प्रिंटिंग की प्रोसेस Cloud Print सर्वर से होती है:

कुछ मामलों में, क्लाइंट को स्थानीय तौर पर कोई दस्तावेज़ भेजना पड़ सकता है. इसकी ज़रूरत तब पड़ सकती है, जब क्लाइंट के पास Google आईडी न हो या वह Cloud Print सर्वर से कनेक्ट न हो पा रहा हो. ऐसे मामले में, प्रिंट जॉब को प्रिंटर पर स्थानीय तौर पर सबमिट किया जाएगा. इसके बाद, प्रिंटर क्लाउड प्रिंट सेवा का इस्तेमाल करके, प्रिंट जॉब को लाइन में लगाएगा और उन्हें बदलेगा. प्रिंटर, स्थानीय तौर पर सबमिट किए गए जॉब को Cloud Print सेवा पर फिर से पोस्ट करेगा. इसके बाद, वह इसके लिए अनुरोध करेगा, क्योंकि इसे क्लाउड के ज़रिए सबमिट किया गया था. इस प्रोसेस से, सेवा (कन्वर्ज़न) और प्रिंट जॉब मैनेजमेंट/ट्रैकिंग के मामले में उपयोगकर्ता को बेहतर अनुभव मिलेगा.

Cloud Print सेवा, कन्वर्ज़न लागू करती है. इसलिए, प्रिंटर को इस्तेमाल किए जा सकने वाले कॉन्टेंट टाइप की सूची में, सभी इनपुट फ़ॉर्मैट ("*/*") के साथ काम करने वाले विज्ञापन दिखाने चाहिए:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "*/*" }
                ]
        }
}

कुछ मामलों में, पूरी तरह से ऑफ़लाइन समाधान की ज़रूरत होती है. प्रिंटर में इनपुट के लिए सीमित फ़ॉर्मैट इस्तेमाल किए जा सकते हैं. इसलिए, क्लाइंट को दस्तावेज़ों को प्रिंटर के कुछ ऐसे फ़ॉर्मैट में बदलना होगा जो प्रिंटर के साथ काम करते हैं.

इस स्पेसिफ़िकेशन के मुताबिक, ऑफ़लाइन प्रिंटिंग के लिए सभी प्रिंटर को कम से कम PWG रास्टर ("image/pwg-raster") फ़ॉर्मैट के साथ काम करना ज़रूरी है. प्रिंटर, अन्य फ़ॉर्मैट (जैसे कि JPEG) के साथ काम कर सकता है. अगर क्लाइंट इसका इस्तेमाल कर सकता है, तो वह दस्तावेज़ों को उस फ़ॉर्मैट में भेज सकता है. प्रिंटर को /capabilities API के ज़रिए, इस्तेमाल किए जा सकने वाले टाइप दिखाने होंगे. उदाहरण के लिए:

{
        "version": "1.0",
        "printer": {
                "supported_content_type": [
                        { "content_type": "image/pwg-raster" },
                        { "content_type": "image/jpeg" }
                ]
        }
}

क्लाइंट, लोकल नेटवर्क पर प्रिंटिंग शुरू करने के लिए दो तरीकों का इस्तेमाल कर सकता है.

सिंपल प्रिंटिंग - क्लाइंट, दस्तावेज़ को लोकल नेटवर्क पर /submitdoc API को भेजता है. इसमें job_id पैरामीटर के बारे में नहीं बताया जाता. सबमिट किए गए दस्तावेज़ को डिफ़ॉल्ट प्रिंट टिकट सेटिंग का इस्तेमाल करके प्रिंट किया जाएगा. इसके लिए, प्रिंट जॉब की स्थिति की जानकारी की ज़रूरत नहीं है. अगर प्रिंटर सिर्फ़ इस तरह की प्रिंटिंग की सुविधा देता है, तो उसे /privet /info API के रिस्पॉन्स में सिर्फ़/submitdoc API का विज्ञापन दिखाना होगा.

"api": [
        "/privet/accesstoken",
        "/privet/capabilities",
        "/privet/printer/submitdoc",
]

ऐडवांस प्रिंटिंग - क्लाइंट को सबसे पहले प्रिंटर पर प्रिंट जॉब बनाना होगा. इसके लिए, उसे /privet/printer/createjob एपीआई को कॉल करना होगा. साथ ही, अनुरोध में मान्य CJT जॉब टिकट शामिल करना होगा. प्रिंटर को प्रिंट टिकट को मेमोरी में सेव करना होगा. साथ ही, क्लाइंट को job_id वापस भेजना होगा. इसके बाद, क्लाइंट /printer/submitdoc API को कॉल करेगा और पहले से मिला job_id तय करेगा. इसके बाद, प्रिंटर प्रिंट करना शुरू कर देगा. क्लाइंट, प्रिंट जॉब की स्थिति के बारे में जानकारी पाने के लिए, प्रिंटर को पोल करेगा. इसके लिए, वह /privet/printer/jobstate API को कॉल करेगा.

एक से ज़्यादा क्लाइंट वाले एनवायरमेंट में, इस बात की कोई गारंटी नहीं होती कि इस एपीआई को कैसे कॉल किया जाता है. ऐसा हो सकता है कि एक क्लाइंट, दूसरे क्लाइंट के/createjob->/submitdoc कॉल के बीच में /createjob को कॉल करे. प्रिंटर पर प्रिंट होने के लिए इंतज़ार कर रहे जॉब की एक छोटी सूची (कम से कम 3 से 5) रखने का सुझाव दिया जाता है, ताकि संभावित डेडलॉक को खत्म किया जा सके और इस्तेमाल करने में आसानी हो:

/createjob कमांड, उपलब्ध पहली जगह पर काम शुरू कर देती है.
जॉब को कम से कम पांच मिनट तक कतार में रखा गया हो.
अगर प्रिंट करने के लिए तैयार फ़ाइलों की सूची में सभी स्लॉट भरे हुए हैं, तो सबसे पुरानी फ़ाइल हटा दी जाएगी. इसके बाद, नई फ़ाइल को उस जगह पर रख दिया जाएगा.
अगर डिवाइस पर फ़िलहाल कोई प्रिंट जॉब प्रिंट हो रहा है (सामान्य या ऐडवांस प्रिंटिंग), तो /submitdoc को 'व्यस्त है' स्टेटस दिखाना चाहिए. साथ ही, इस प्रिंट जॉब को फिर से आज़माने के लिए टाइम आउट का सुझाव देना चाहिए.
अगर /submitdoc, ऐसे जॉब को रेफ़र करता है जिसे कतार से हटा दिया गया है (बदलाव या टाइम आउट की वजह से), तो प्रिंटर को invalid_print_job गड़बड़ी का मैसेज दिखाना चाहिए. साथ ही, क्लाइंट /createjob चरण से प्रोसेस को फिर से शुरू करेगा. क्लाइंट को फिर से कोशिश करने से पहले, पांच सेकंड तक के रैंडम टाइमआउट पीरियड का इंतज़ार करना होगा.

अगर मेमोरी की कमी की वजह से, डिवाइस पर कई प्रिंट जॉब सेव नहीं किए जा सकते, तो प्रिंट जॉब की एक ही लाइन हो सकती है. हालांकि, इसे ऊपर दिए गए प्रोटोकॉल का पालन करना होगा. जब कोई प्रिंट जॉब पूरा हो जाता है या किसी गड़बड़ी की वजह से पूरा नहीं हो पाता है, तो प्रिंटर को कम से कम पांच मिनट तक जॉब की स्थिति की जानकारी सेव करनी चाहिए. पूरे हो चुके जॉब के स्टेटस सेव करने के लिए, क्यू का साइज़ कम से कम 10 होना चाहिए. अगर सेव किए जाने वाले जॉब स्टेटस की संख्या ज़्यादा है, तो हो सकता है कि सबसे पुराने जॉब स्टेटस को पांच मिनट के टाइम आउट से पहले ही, कतार से हटा दिया जाए.

ध्यान दें: फ़िलहाल, क्लाइंट नौकरी की स्थिति के लिए पोल करेंगे. आने वाले समय में, हम प्रिंटर से यह अनुरोध कर सकते हैं कि जब किसी प्रिंट जॉब की स्थिति में बदलाव हो, तब वह टीएक्सटी डीएनएस सूचना भेजे.

5.1. /privet/printer/createjob API

/privet/printer/createjob एपीआई का इस्तेमाल करना ज़रूरी नहीं है. इसके बारे में ऊपर 'आसान प्रिंटिंग' सेक्शन में बताया गया है. यह एक एचटीटीपी पोस्ट अनुरोध है. /privet/printer/createjob API को "X-Privet-Token" हेडर की पुष्टि करनी होगी. डिवाइस को इस एपीआई को "/privet/printer/createjob" यूआरएल पर लागू करना होगा:

POST /privet/printer/createjob HTTP/1.1

/privet/printer/createjob API कॉल मिलने पर, प्रिंटर को नया प्रिंट जॉब आईडी बनाना होगा. साथ ही, मिले हुए प्रिंट टिकट को CJT फ़ॉर्मैट में सेव करना होगा और प्रिंट जॉब आईडी को वापस क्लाइंट को भेजना होगा.

5.1.1. इनपुट

/privet/printer/createjob API के यूआरएल में कोई इनपुट पैरामीटर नहीं है. अनुरोध के मुख्य भाग में, CJT फ़ॉर्मैट में प्रिंट जॉब टिकट का डेटा होना चाहिए.

5.1.2. वापसी का टिकट

/privet/printer/createjob API यह डेटा दिखाता है:

वैल्यू का नाम	वैल्यू टाइप	ब्यौरा
job_id	स्ट्रिंग	नए प्रिंट जॉब का आईडी.
expires_in	int	यह प्रिंट जॉब कितने सेकंड तक मान्य है.

उदाहरण:

{
        "job_id": "123",
        "expires_in": 600
}

5.1.3. गड़बड़ियां

/privet/printer/createjob API से ये गड़बड़ियां दिख सकती हैं. ज़्यादा जानकारी के लिए, गड़बड़ियां सेक्शन देखें:

गड़बड़ी	ब्यौरा
invalid_ticket	सबमिट किया गया प्रिंट टिकट अमान्य है.
printer_busy	प्रिंटर व्यस्त है और फ़िलहाल /createjob को प्रोसेस नहीं कर सकता. टाइम आउट होने के बाद, फिर से कोशिश करें.
printer_error	प्रिंटर में कोई गड़बड़ी है और इसे ठीक करने के लिए उपयोगकर्ता के इंटरैक्शन की ज़रूरत है. ब्यौरे में समस्या के बारे में ज़्यादा जानकारी होनी चाहिए. उदाहरण के लिए, "ट्रे 1 में पेपर फंस गया है".
invalid_x_privet_token	अनुरोध में X-Privet-Token अमान्य है या खाली है.

अगर डिवाइस /privet/printer/createjob को ऐक्सेस करने की अनुमति नहीं देता है, तो उसे एचटीटीपी 404 गड़बड़ी का मैसेज दिखाना होगा. अगर X-Privet-Token हेडर मौजूद नहीं है, तो डिवाइस को एचटीटीपी 400 गड़बड़ी का मैसेज दिखाना होगा.

5.2. /privet/printer/submitdoc API

लोकल नेटवर्क (ऑफ़लाइन या Cloud Print पर फिर से पोस्ट करने) पर प्रिंटिंग की सुविधा लागू करने के लिए, /privet/printer/submitdoc API का इस्तेमाल करना ज़रूरी है. यह एक एचटीटीपी पोस्ट अनुरोध है. /privet/printer/submitdoc API को "X-Privet-Token" हेडर की पुष्टि करनी होगी. डिवाइस को इस एपीआई को "/privet/printer/submitdoc" यूआरएल पर लागू करना होगा:

POST /privet/printer/submitdoc HTTP/1.1

/privet/printer/submitdoc API कॉल मिलने पर, प्रिंटर को प्रिंटिंग शुरू कर देनी चाहिए. अगर प्रिंटिंग शुरू नहीं हो पाती है, तो इसे printer_busy गड़बड़ी का मैसेज दिखाना होगा. साथ ही, क्लाइंट को यह भी बताना होगा कि उसे कितने समय तक इंतज़ार करना चाहिए, ताकि वह फिर से प्रिंटिंग शुरू कर सके.

अगर प्रिंटर, अपने इंटरनल बफ़र में पूरा डेटा सेव नहीं कर पाता है, तो उसे टीसीपी के तरीकों का इस्तेमाल करके, डेटा ट्रांसफ़र की स्पीड कम करनी चाहिए. ऐसा तब तक करना चाहिए, जब तक वह दस्तावेज़ का कुछ हिस्सा प्रिंट न कर ले. इससे बफ़र का कुछ हिस्सा फिर से उपलब्ध हो जाएगा. (उदाहरण के लिए, प्रिंटर टीसीपी लेयर पर windowsize=0 सेट कर सकता है. इससे क्लाइंट को इंतज़ार करना पड़ेगा.)

प्रिंटर को कोई दस्तावेज़ सबमिट करने में ज़्यादा समय लग सकता है. प्रिंटिंग के दौरान, क्लाइंट को प्रिंटर और जॉब (ऐडवांस प्रिंटिंग) की स्थिति की जांच करने की सुविधा मिलनी चाहिए. इसके लिए, प्रिंटर को क्लाइंट को /privet/info और /privet/printer/jobstate API को कॉल करने की अनुमति देनी होगी. ऐसा /privet/printer/submitdoc API कॉल को प्रोसेस करते समय करना होगा. हम सभी क्लाइंट को यह सुझाव देते हैं कि वे /privet/printer/submitdoc API कॉल को लागू करने के लिए, नया थ्रेड शुरू करें. इससे मुख्य थ्रेड, प्रिंटर और जॉब की स्थितियों की जांच करने के लिए /privet/info और /privet/printer/jobstate API का इस्तेमाल कर सकता है.

ध्यान दें: लोकल प्रिंट जॉब पूरा होने या रद्द होने पर, हमारा सुझाव है कि आप /cloudprint/submit इंटरफ़ेस को जॉब की फ़ाइनल स्थिति की जानकारी दें. ऐसा करना, हिसाब रखने और उपयोगकर्ता अनुभव को बेहतर बनाने के लिए ज़रूरी है. यह जानकारी देना, इस स्पेसिफ़िकेशन के आने वाले वर्शन में ज़रूरी होगा. "printerid", "title", "contentType", और "final_semantic_state" (PrintJobState फ़ॉर्मैट में) पैरामीटर ज़रूरी हैं. साथ ही, "tag" (दोहराया गया पैरामीटर) और "ticket" (CloudJobTicket फ़ॉर्मैट में जॉब का टिकट) पैरामीटर भी ज़रूरी हैं. ध्यान दें कि PrintJobState की दी गई वैल्यू, फ़ाइनल होनी चाहिए. इसका मतलब है कि इसकी वैल्यू DONE या ABORTED होनी चाहिए. अगर इसकी वैल्यू ABORTED है, तो इसकी वजह भी बताई जानी चाहिए. ज़्यादा जानकारी के लिए, JobState देखें. यह भी ध्यान दें कि लोकल प्रिंट जॉब की जानकारी देने के लिए, /cloudprint/submit इंटरफ़ेस के इस्तेमाल के बारे में इसके स्पेसिफ़िकेशन में नहीं बताया गया है. ऐसा इसलिए है, क्योंकि इस सेक्शन में इंटरफ़ेस के मुख्य इस्तेमाल के बारे में बताया गया है. जैसे, "content" पैरामीटर में दिए गए दस्तावेज़ को प्रिंट करने के लिए प्रिंट जॉब सबमिट करना.

5.2.1. इनपुट

/privet/printer/submitdoc API के ये इनपुट पैरामीटर होते हैं:

नाम	मान
job_id	(ज़रूरी नहीं) प्रिंट जॉब आईडी. आसान प्रिंटिंग के मामले में इसे हटाया जा सकता है (ऊपर देखें). यह वैल्यू, प्रिंटर से मिली वैल्यू से मेल खानी चाहिए.
user_name	(ज़रूरी नहीं) ऐसा उपयोगकर्ता नाम जिसे कोई व्यक्ति आसानी से पढ़ सके. यह पक्का नहीं है कि यह जानकारी सही है. इसका इस्तेमाल सिर्फ़ प्रिंट जॉब के एनोटेशन के लिए किया जाना चाहिए. अगर जॉब को Cloud Print सेवा पर फिर से पोस्ट किया जाता है, तो इस स्ट्रिंग को Cloud Print जॉब से अटैच किया जाना चाहिए.
client_name	(ज़रूरी नहीं) इस अनुरोध को करने वाले क्लाइंट ऐप्लिकेशन का नाम. यह सिर्फ़ डिसप्ले के लिए है. अगर जॉब को Cloud Print सेवा पर फिर से पोस्ट किया जाता है, तो इस स्ट्रिंग को Cloud Print जॉब से अटैच किया जाना चाहिए.
job_name	(ज़रूरी नहीं) रिकॉर्ड किए जाने वाले प्रिंट जॉब का नाम. अगर जॉब को Cloud Print सेवा पर फिर से पोस्ट किया जाता है, तो इस स्ट्रिंग को Cloud Print जॉब से अटैच किया जाना चाहिए.
अॉफ़लाइन	(ज़रूरी नहीं) इसकी वैल्यू सिर्फ़ "offline=1" हो सकती है. इस मामले में, प्रिंटर को सिर्फ़ ऑफ़लाइन प्रिंट करने की कोशिश करनी चाहिए. उसे Cloud Print सर्वर पर दोबारा पोस्ट नहीं करना चाहिए.

अनुरोध के मुख्य भाग में, प्रिंट करने के लिए मान्य दस्तावेज़ होना चाहिए. "Content-Length" में, अनुरोध की सही लंबाई शामिल होनी चाहिए. "Content-Type" हेडर को दस्तावेज़ के एमआईएमई टाइप पर सेट किया जाना चाहिए. साथ ही, यह सीडीडी में दिए गए टाइप में से किसी एक से मेल खाना चाहिए. हालांकि, अगर सीडीडी में "*/*" दिया गया है, तो ऐसा करना ज़रूरी नहीं है.

हमारा सुझाव है कि क्लाइंट इस अनुरोध के साथ, मान्य उपयोगकर्ता नाम (या ईमेल), क्लाइंट का नाम, और नौकरी का नाम दें. इन फ़ील्ड का इस्तेमाल सिर्फ़ यूज़र इंटरफ़ेस (यूआई) में किया जाता है, ताकि उपयोगकर्ता अनुभव को बेहतर बनाया जा सके.

5.2.2. वापसी का टिकट

/privet/printer/submitdoc API, यह डेटा दिखाता है:

वैल्यू का नाम	वैल्यू टाइप	ब्यौरा
job_id	स्ट्रिंग	नए प्रिंट जॉब का आईडी (सिंपल प्रिंटिंग) या अनुरोध में दिया गया job_id (ऐडवांस प्रिंटिंग).
expires_in	int	यह प्रिंट जॉब कितने सेकंड तक मान्य है.
job_type	स्ट्रिंग	सबमिट किए गए दस्तावेज़ का कॉन्टेंट टाइप.
job_size	int 64 बिट	प्रिंट किए जाने वाले डेटा का साइज़, बाइट में.
job_name	स्ट्रिंग	(ज़रूरी नहीं) अगर कोई इनपुट दिया गया है, तो उसमें मौजूद नौकरी का नाम.

उदाहरण:

{
        "job_id": "123",
        "expires_in": 500,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

5.2.3. गड़बड़ियां

/privet/printer/submitdoc API, ये गड़बड़ियां दिखा सकता है. ज़्यादा जानकारी के लिए, गड़बड़ियां सेक्शन देखें:

गड़बड़ी	ब्यौरा
invalid_print_job	अनुरोध में अमान्य/समयसीमा खत्म हो चुका जॉब आईडी दिया गया है. टाइम आउट होने के बाद, फिर से कोशिश करें.
invalid_document_type	दस्तावेज़ का MIME-टाइप, प्रिंटर के साथ काम नहीं करता.
invalid_document	सबमिट किया गया दस्तावेज़ अमान्य है.
document_too_large	दस्तावेज़ का साइज़, तय सीमा से ज़्यादा है.
printer_busy	प्रिंटर व्यस्त है और फ़िलहाल दस्तावेज़ को प्रोसेस नहीं कर सकता. टाइम आउट होने के बाद, फिर से कोशिश करें.
printer_error	प्रिंटर में कोई गड़बड़ी है और इसे ठीक करने के लिए उपयोगकर्ता के इंटरैक्शन की ज़रूरत है. ब्यौरे में समस्या के बारे में ज़्यादा जानकारी होनी चाहिए. उदाहरण के लिए, "ट्रे 1 में पेपर फंस गया है".
invalid_params	अनुरोध में अमान्य पैरामीटर दिए गए हैं. (आने वाले समय में साथ काम करने की सुविधा के लिए, अज्ञात पैरामीटर को अनदेखा किया जाना चाहिए)
user_cancel	उपयोगकर्ता ने डिवाइस से प्रिंटिंग की प्रोसेस को साफ़ तौर पर रद्द कर दिया है.
server_error	दस्तावेज़ को Cloud Print पर पोस्ट नहीं किया जा सका.
invalid_x_privet_token	अनुरोध में X-Privet-Token अमान्य है या खाली है.

अगर डिवाइस /privet/printer/submitdoc को ऐक्सेस करने की अनुमति नहीं देता है, तो उसे एचटीटीपी 404 गड़बड़ी का मैसेज दिखाना होगा. अगर X-Privet-Token हेडर मौजूद नहीं है, तो डिवाइस को एचटीटीपी 400 गड़बड़ी का मैसेज दिखाना होगा.

ध्यान दें: /privet/printer/submitdoc API को प्रिंटर के लिए खास तौर पर हैंडल करने की ज़रूरत पड़ सकती है. ऐसा अटैच किए गए बड़े पेलोड की वजह से होता है. कुछ मामलों में (यह प्रिंटर के एचटीटीपी सर्वर के लागू होने और प्लैटफ़ॉर्म पर निर्भर करता है), प्रिंटर, एचटीटीपी गड़बड़ी का मैसेज दिखाने से पहले सॉकेट बंद कर सकता है. अन्य मामलों में, प्रिंटर Privet की गड़बड़ी के बजाय 503 गड़बड़ी दिखा सकता है. प्रिंटर को Privet को वापस लाने की पूरी कोशिश करनी चाहिए. हालांकि, Privet स्पेसिफ़िकेशन लागू करने वाले हर क्लाइंट को, /privet/printer/submitdoc API के लिए सॉकेट बंद होने (कोई एचटीटीपी गड़बड़ी नहीं) और 503 एचटीटीपी गड़बड़ी के मामलों को हैंडल करना चाहिए. इस मामले में, क्लाइंट को इसे Privet "printer_busy" गड़बड़ी के तौर पर हैंडल करना चाहिए. साथ ही, "timeout" को 15 सेकंड पर सेट करना चाहिए. अनगिनत बार फिर से कोशिश करने से बचने के लिए, क्लाइंट कुछ बार कोशिश करने के बाद (उदाहरण के लिए, तीन बार) कोशिश करना बंद कर सकता है.

5.3. /privet/printer/jobstate API

/privet/printer/jobstate API का इस्तेमाल करना ज़रूरी नहीं है. इसके बारे में ऊपर 'आसान प्रिंटिंग' सेक्शन में बताया गया है. यह एक एचटीटीपी GET अनुरोध है. /privet/printer/jobstate API को "X-Privet-Token" हेडर की पुष्टि करनी होगी. डिवाइस को इस एपीआई को "/privet/printer/jobstate" यूआरएल पर लागू करना होगा:

GET /privet/printer/jobstate HTTP/1.1

/privet/printer/jobstate API कॉल मिलने पर, प्रिंटर को अनुरोध किए गए प्रिंट जॉब की स्थिति या invalid_print_job गड़बड़ी की जानकारी देनी चाहिए.

5.3.1. इनपुट

/privet/printer/jobstate API में ये इनपुट पैरामीटर होते हैं:

नाम	मान
job_id	प्रिंट जॉब का वह आईडी जिसके लिए स्टेटस की जानकारी चाहिए.

5.3.2. वापसी का टिकट

/privet/printer/jobstate API यह डेटा दिखाता है:

वैल्यू का नाम	वैल्यू टाइप	ब्यौरा
job_id	स्ट्रिंग	प्रिंट जॉब का आईडी, जिसके स्टेटस की जानकारी दी गई है.
राज्य	स्ट्रिंग	ड्राफ़्ट - डिवाइस पर प्रिंट जॉब बनाया गया है (अभी तक कोई /privet/printer/submitdoc कॉल नहीं मिला है). कतार में है - प्रिंट जॉब मिल गया है और कतार में है, लेकिन प्रिंटिंग अब तक शुरू नहीं हुई है. in_progress - प्रिंट जॉब की प्रिंटिंग जारी है. stopped - प्रिंट जॉब को रोक दिया गया है. हालांकि, इसे मैन्युअल तरीके से या अपने-आप फिर से शुरू किया जा सकता है. done - प्रिंट जॉब पूरा हो गया है. aborted - प्रिंट जॉब पूरा नहीं हुआ.
ब्यौरा	स्ट्रिंग	(ज़रूरी नहीं) प्रिंट जॉब की स्थिति के बारे में ऐसी जानकारी जिसे कोई भी व्यक्ति आसानी से पढ़ सकता है. अगर state एट्रिब्यूट की वैल्यू stopped या aborted है, तो अतिरिक्त जानकारी शामिल करें. semantic_state फ़ील्ड, आम तौर पर क्लाइंट को बेहतर और ज़्यादा काम की जानकारी देता है.
expires_in	int	यह प्रिंट जॉब कितने सेकंड तक मान्य है.
job_type	स्ट्रिंग	(ज़रूरी नहीं) सबमिट किए गए दस्तावेज़ का कॉन्टेंट टाइप.
job_size	int 64 बिट	(ज़रूरी नहीं) प्रिंट किए जाने वाले डेटा का साइज़, बाइट में.
job_name	स्ट्रिंग	(ज़रूरी नहीं) अगर कोई इनपुट दिया गया है, तो उसमें मौजूद नौकरी का नाम.
server_job_id	स्ट्रिंग	(ज़रूरी नहीं) सर्वर से मिला जॉब आईडी (अगर जॉब को Cloud Print सेवा पर पोस्ट किया गया है). ऑफ़लाइन प्रिंटिंग के लिए शामिल नहीं किया गया.
semantic_state	JSON	(वैकल्पिक) PrintJobState फ़ॉर्मैट में जॉब की सिमैंटिक स्थिति.

उदाहरण (Cloud Print के ज़रिए रिपोर्टिंग करके प्रिंट करना):

{
        "job_id": "123",
        "state": "in_progress",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "server_job_id": "1111-2222-3333-4444"
}

उदाहरण (ऑफ़लाइन प्रिंटिंग की गड़बड़ी):

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document"
}

उदाहरण (उपयोगकर्ता ने प्रिंट जॉब रद्द कर दिया):

{
        "job_id": "123",
        "state": "aborted",
        "description": "User action",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": 123456,
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "ABORTED",
                        "user_action_cause": {"action_code": "CANCELLED"}
                },
                "pages_printed": 7
        }
}

उदाहरण (कागज़ खत्म होने की वजह से प्रिंट जॉब रुक गया). डिवाइस की स्थिति के बारे में जानकारी देखें. डिवाइस की स्थिति के बारे में ज़्यादा जानकारी पाने के लिए, क्लाइंट को /privet/info API को कॉल करना होगा:

{
        "job_id": "123",
        "state": "stopped",
        "description": "Out of paper",
        "expires_in": 100,
        "job_type": "application/pdf",
        "job_size": "123456",
        "job_name": "My PDF document",
        "semantic_state": {
                "version": "1.0",
                "state": {
                        "type": "STOPPED",
                        "device_state_cause": {"error_code": "INPUT_TRAY"}
                },
                "pages_printed": 7
        }
}

5.3.3. गड़बड़ियां

/privet/printer/jobstate API ये गड़बड़ियां दिखा सकता है. ज़्यादा जानकारी के लिए, गड़बड़ियां सेक्शन देखें:

गड़बड़ी	ब्यौरा
invalid_print_job	अनुरोध में अमान्य/समयसीमा खत्म हो चुका जॉब आईडी दिया गया है.
server_error	Cloud Print पर पोस्ट किए गए प्रिंट जॉब के लिए, प्रिंट जॉब की स्थिति पाने में समस्या हुई.
invalid_x_privet_token	अनुरोध में X-Privet-Token अमान्य है या खाली है.

अगर डिवाइस /privet/printer/jobstate को नहीं दिखा रहा है, तो उसे एचटीटीपी 404 गड़बड़ी का मैसेज दिखाना होगा. अगर X-Privet-Token हेडर मौजूद नहीं है, तो डिवाइस को एचटीटीपी 400 गड़बड़ी का मैसेज दिखाना होगा.

6. अन्य जानकारी

6.1. डिफ़ॉल्ट ऐक्शन और सेटिंग

इस सेक्शन में, हम सभी Privet-compatible डिवाइसों से मिलने वाले डिफ़ॉल्ट बर्ताव के बारे में बताएंगे.

आउट-ऑफ़-द-बॉक्स डिवाइसों पर सिर्फ़ /privet/info और /privet/register एपीआई काम करने चाहिए. अन्य सभी एपीआई (जैसे कि /privet/accesstoken, लोकल प्रिंटिंग) बंद होने चाहिए.
रजिस्ट्रेशन के लिए, डिवाइस के साथ फ़िज़िकल इंटरैक्शन करना ज़रूरी है.

डिवाइस का ऐक्सेस पाने के लिए, उपयोगकर्ता को डिवाइस पर कोई कार्रवाई करनी होगी. जैसे, बटन दबाना.
उपयोगकर्ता के ऊपर बताई गई कार्रवाई करने के बाद, प्रिंटर को /cloudprint/register अनुरोध भेजना चाहिए. जब तक कार्रवाई नहीं हो जाती, तब तक इसे यह अनुरोध नहीं भेजना चाहिए (Sequence Diagram 1 देखें).
अगर डिवाइस, /privet/register अनुरोध को प्रोसेस कर रहा है (उदाहरण के लिए, ऊपर दी गई कार्रवाई का इंतज़ार कर रहा है), तो उसे /privet/register के सभी अन्य अनुरोधों को अस्वीकार करना होगा. इस मामले में, डिवाइस को device_busy गड़बड़ी का मैसेज दिखाना होगा.
डिवाइस को ऐसे किसी भी /register अनुरोध को टाइम आउट कर देना चाहिए जिसमें 60 सेकंड के अंदर, ऊपर बताई गई कार्रवाई नहीं की गई है. इस मामले में, डिवाइस को confirmation_timeout गड़बड़ी का मैसेज दिखाना होगा.
ज़रूरी नहीं: यहां दिए गए सुझावों को लागू करना ज़रूरी नहीं है. हालांकि, इनसे उपयोगकर्ता अनुभव को बेहतर बनाया जा सकता है:

प्रिंटर पर एक लाइट फ़्लैश हो सकती है या उसकी स्क्रीन पर यह सूचना दिख सकती है कि उपयोगकर्ता को रजिस्ट्रेशन की पुष्टि करने के लिए कोई कार्रवाई करनी होगी.
प्रिंटर की स्क्रीन पर यह मैसेज दिख सकता है: ‘इसे उपयोगकर्ता ‘abc@def.com’ के लिए Google Cloud Print में रजिस्टर किया जा रहा है - जारी रखने के लिए OK दबाएं’. यहां abc@def.com, /register API कॉल से मिला उपयोगकर्ता पैरामीटर है. इससे उपयोगकर्ता को यह साफ़ तौर पर पता चलेगा कि:

यह रजिस्ट्रेशन का उनका अनुरोध है जिसकी वे पुष्टि कर रहे हैं
अगर उस व्यक्ति ने अनुरोध नहीं किया है, तो क्या हो रहा है.

प्रिंटर पर पुष्टि करने के लिए, आपको कोई कार्रवाई करनी होगी. जैसे, ‘ठीक है बटन दबाएं’), प्रिंटर, उपयोगकर्ता को अनुरोध रद्द करने का बटन भी दिखा सकता है. उदाहरण के लिए, ‘रद्द करने के लिए, रद्द करें पर क्लिक करें’). इससे जिन लोगों ने रजिस्ट्रेशन का अनुरोध नहीं किया है वे 60 सेकंड के टाइम आउट से पहले, अनुरोध को रद्द कर पाएंगे. इस मामले में, डिवाइस को user_cancel गड़बड़ी का मैसेज दिखाना होगा.

मालिकाना हक के ट्रांसफ़र:

डिवाइस को क्लाउड सेवा से मिटाया जा सकता है.

अगर डिवाइस को /cloudprint/printer (GCP के लिए) कॉल के नतीजे के तौर पर, डिवाइस की जानकारी नहीं मिलती है, तो उसे डिफ़ॉल्ट (आउट-ऑफ़-द-बॉक्स) मोड पर वापस जाना होगा.
अगर डिवाइस के क्रेडेंशियल अब काम नहीं करते हैं (खास तौर पर, सर्वर से "अमान्य क्रेडेंशियल" जवाब मिलने की वजह से), तो डिवाइस को डिफ़ॉल्ट (आउट-ऑफ़-द-बॉक्स) मोड पर वापस लाना ज़रूरी है.

लोकल फ़ैक्ट्री रीसेट करने पर, डिवाइस के क्रेडेंशियल मिट जाने चाहिए और डिवाइस डिफ़ॉल्ट स्थिति में सेट हो जाना चाहिए.
ज़रूरी नहीं: डिवाइस, क्रेडेंशियल मिटाने और उसे डिफ़ॉल्ट मोड में डालने के लिए, मेन्यू आइटम उपलब्ध करा सकता है.

XMPP सूचनाओं की सुविधा देने वाले डिवाइसों में, सर्वर को पिंग करने की सुविधा शामिल होनी चाहिए. पिंग टाइमआउट को सर्वर से कंट्रोल किया जाना चाहिए. इसके लिए, "local_settings" का इस्तेमाल करना होगा.
डिवाइस, सर्वर को दिन में एक बार (24 घंटे) से ज़्यादा बार पिंग नहीं कर सकता. ऐसा इसलिए, ताकि यह पक्का किया जा सके कि वे सिंक हैं. इसके लिए, डिवाइस /cloudprint/printer API for GCP के साथ-साथ XMPP पिंग का इस्तेमाल कर सकता है. हमारा सुझाव है कि आप 24 से 32 घंटे की विंडो में, चेक करने के समय को रैंडमाइज़ करें.
ज़रूरी नहीं: क्लाउड प्रिंट डिवाइसों के लिए, यह सुझाव दिया जाता है कि उपयोगकर्ता को डिवाइस से नए प्रिंट जॉब की जांच शुरू करने की अनुमति देने के लिए, मैन्युअल तरीका (बटन) उपलब्ध कराया जाए. कुछ प्रिंटर में यह सुविधा पहले से मौजूद है.
ज़रूरी नहीं. ऐसा हो सकता है कि एंटरप्राइज़ प्रिंटर में, स्थानीय खोज की सुविधा को पूरी तरह से बंद करने का विकल्प हो. ऐसे मामले में, डिवाइस को सर्वर पर इन स्थानीय सेटिंग को अपडेट करना होगा. नई स्थानीय सेटिंग खाली होनी चाहिए. "local_discovery" सेटिंग को "false" पर सेट करने का मतलब है कि इसे GCP सेवा से फिर से चालू किया जा सकता है.

6.1.2 डिफ़ॉल्ट रजिस्ट्रेशन डायग्राम

6.2. XSSI और XSRF हमलों से बचाव

इस सेक्शन में, डिवाइस पर XSSI और XSRF हमलों की संभावना के बारे में बताया जाएगा. साथ ही, इनसे डिवाइस को सुरक्षित रखने का तरीका बताया जाएगा. इसमें टोकन जनरेट करने की तकनीकें भी शामिल हैं.
ज़्यादा जानकारी यहां दी गई है: http://googleonlinesecurity.blogspot.com/2011/05/website-security-for-webmasters.html
आम तौर पर, XSSI और XSRF हमले तब किए जा सकते हैं, जब कोई साइट कुकी की पुष्टि करने वाले तरीकों का इस्तेमाल कर रही हो. Google, Cloud Print सेवा के साथ कुकी का इस्तेमाल नहीं करता. हालांकि, इस तरह के हमले अब भी किए जा सकते हैं. लोकल नेटवर्क का ऐक्सेस देने के लिए, अनुरोधों पर भरोसा किया जाता है.

6.2.1. XSSI

ऐसा हो सकता है कि कोई दुर्भावनापूर्ण वेबसाइट, Privet के साथ काम करने वाले डिवाइस के आईपी पते और पोर्ट नंबर का अनुमान लगाए. साथ ही, <script> टैग में"src=<api name >" का इस्तेमाल करके, Privet API को कॉल करने की कोशिश करे:

<script type="text/javascript" src="http://192.168.1.42:8080/privet/info"></script>

सुरक्षा के बिना, नुकसान पहुंचाने वाली वेबसाइटें एपीआई कॉल कर सकती हैं और नतीजों को ऐक्सेस कर सकती हैं.
इस तरह के हमले को रोकने के लिए, सभी Privet API कॉल में अनुरोध के लिए "X-Privet-Token" हेडर की ज़रूरत होती है. "src=<api>" स्क्रिप्ट टैग, हेडर नहीं जोड़ पाते. इसलिए, इस तरह के हमलों से बचाव किया जा सकता है.

6.2.2. XSRF

http://en.wikipedia.org/wiki/Cross-site_request_forgery
ऐसा हो सकता है कि कोई दुर्भावनापूर्ण वेबसाइट, Privet के साथ काम करने वाले डिवाइस के आईपी पते और पोर्ट नंबर का अनुमान लगाए. इसके बाद, <iframe>, फ़ॉर्म या वेबसाइटों के बीच डेटा लोड करने के किसी अन्य तरीके का इस्तेमाल करके, Privet API को कॉल करने की कोशिश करे. हमलावर, अनुरोध के नतीजों को ऐक्सेस नहीं कर पाएंगे. हालांकि, अगर अनुरोध से कोई कार्रवाई (जैसे कि प्रिंट करना) होती है, तो वे इसे ट्रिगर कर सकते हैं.

इस तरह के हमले को रोकने के लिए, हमें सुरक्षा से जुड़ी इन सुविधाओं की ज़रूरत होती है:

XSRF के लिए /privet/info API को खुला छोड़ दें
/privet/info API को डिवाइस पर कोई कार्रवाई नहीं करनी चाहिए
x-privet-token पाने के लिए, /privet/info API का इस्तेमाल करें
अन्य सभी एपीआई को "X-Privet-Token" हेडर में, मान्य x-privet-token की जांच करनी होगी.
x-privet-token सिर्फ़ 24 घंटे के लिए मान्य होना चाहिए.

अगर हमलावर /privet/info एपीआई को एक्ज़ीक्यूट कर पाता है, तब भी वह रिस्पॉन्स से x-privet-token को नहीं पढ़ पाएगा. इसलिए, वह किसी अन्य एपीआई को कॉल नहीं कर पाएगा.

हमारा सुझाव है कि XSRF टोकन जनरेट करने के लिए, इस एल्गोरिदम का इस्तेमाल करें:

XSRF_token = base64( SHA1(device_secret + DELIMITER + issue_timecounter) + DELIMITER + issue_timecounter )

XSRF टोकन जनरेट करने वाले एलिमेंट:

DELIMITER एक खास वर्ण होता है. आम तौर पर, यह ‘:’ होता है
issue_timecounter, किसी इवेंट (टाइमस्टैंप के लिए इपोक) या डिवाइस के बूट होने के समय (सीपीयू काउंटर के लिए) से लेकर अब तक के सेकंड की संख्या होती है. जब डिवाइस चालू होता है और काम कर रहा होता है, तब issue_timecounter लगातार बढ़ता रहता है. इसके बारे में ज़्यादा जानकारी के लिए, नीचे टोकन की पुष्टि करने से जुड़ी जानकारी देखें.
SHA1 - SHA1 एल्गोरिदम का इस्तेमाल करने वाला हैश फ़ंक्शन
base64 - base64 एन्कोडिंग
device_secret - डिवाइस के लिए खास सीक्रेट. डिवाइस सीक्रेट को हर बार रीस्टार्ट करने पर अपडेट करना ज़रूरी है.

डिवाइस सीक्रेट जनरेट करने के लिए सुझाए गए तरीके:

हर बार रीस्टार्ट करने पर नया यूयूआईडी जनरेट करता है
हर बार रीस्टार्ट होने पर, 64 बिट का रैंडम नंबर जनरेट करता है

डिवाइस के लिए, जारी किए गए सभी XSRF टोकन को सेव करना ज़रूरी नहीं है. जब डिवाइस को XSRF टोकन की पुष्टि करनी हो, तब उसे टोकन को base64-डिकोड करना चाहिए. दूसरे हाफ़ (क्लियरटेक्स्ट) से issue_timecounter पाएं. इसके बाद, device_secret + DELIMITER + issue_timecounter का SHA1 हैश जनरेट करने की कोशिश करें. यहां issue_timecounter टोकन से लिया गया है. अगर नया SHA1, टोकन में मौजूद SHA1 से मेल खाता है, तो डिवाइस को अब यह जांच करनी होगी कि issue_timecounter, मौजूदा समय के काउंटर के 24 घंटे के अंदर मान्य है या नहीं. इसके लिए, डिवाइस मौजूदा समय का काउंटर (जैसे कि सीपीयू काउंटर) लेता है और इसमें से issue_timecounter को घटाता है. नतीजा, टोकन जारी होने के बाद से लेकर अब तक के सेकंड की संख्या होनी चाहिए.

अहम जानकारी: XSRF से सुरक्षा पाने के लिए, यह तरीका इस्तेमाल करने का सुझाव दिया जाता है. Privet स्पेसिफ़िकेशन के क्लाइंट, XSRF टोकन को समझने की कोशिश नहीं करेंगे. इसके बजाय, वे इसे ब्लैकबॉक्स के तौर पर इस्तेमाल करेंगे. आंकड़ा 6.2.3, X-Privet-Token को लागू करने और सामान्य अनुरोध की पुष्टि करने का सुझाया गया तरीका दिखाता है.

6.2.3 X-Privet टोकन जनरेट करने और पुष्टि करने का क्रम दिखाने वाला डायग्राम

6.3. वर्कफ़्लो के डायग्राम

इस सेक्शन में, अलग-अलग मामलों में वर्कफ़्लो के बारे में बताया जाएगा.

6.3.1. प्रिंटर को बॉक्स से बाहर निकालने के बाद का वर्कफ़्लो

6.3.2. रजिस्टर किए गए प्रिंटर को चालू करना

6.3.3 XMPP सूचनाओं को मैनेज करने का वर्कफ़्लो

6.3.4. प्रिंटर की सेटिंग के वर्कफ़्लो की जांच करना

प्रिवेट संग्रह की मदद से व्यवस्थित रहें अपनी प्राथमिकताओं के आधार पर, कॉन्टेंट को सेव करें और कैटगरी में बांटें.

1. परिचय

2. डिस्कवरी

2.1. सेवा प्रकार

2.2. TXT रिकॉर्ड

2.2.1. txtvers

2.2.2. ty

2.2.3. note (ज़रूरी नहीं)

2.2.4. url

2.2.5. टाइप

2.2.6. id

2.2.7. cs

3. घोषणाएं

3.1. स्टार्टअप

3.2. बंद करें

3.3. अपडेट करें

4. एपीआई

4.1. एपीआई की उपलब्धता

4.1.1. रजिस्ट्रेशन

4.1.2. स्टार्टअप

4.1.3. अपडेट करें

4.1.3.1. स्थानीय सेटिंग को मंज़ूरी मिलना बाकी है

4.1.3.2. Local Settings Current

4.1.4. ऑफ़लाइन

4.1.5. डिवाइस को सेवा से मिटाना

4.2. /privet/info API

4.2.1. इनपुट

4.2.2. वापसी का टिकट

4.2.3. गड़बड़ियां

4.3. /privet/register API

4.3.1. इनपुट

4.3.2. वापसी का टिकट

4.3.3. गड़बड़ियां

4.4. /privet/accesstoken API

4.4.1. इनपुट

4.4.2. वापसी का टिकट

4.4.3. गड़बड़ियां

4.5. /privet/capabilities API

4.5.1. इनपुट

4.5.2. वापसी का टिकट

4.5.3. गड़बड़ियां

4.6. गड़बड़ियां

5. Printer API

5.1. /privet/printer/createjob API

5.1.1. इनपुट

5.1.2. वापसी का टिकट

5.1.3. गड़बड़ियां

5.2. /privet/printer/submitdoc API

5.2.1. इनपुट

5.2.2. वापसी का टिकट

5.2.3. गड़बड़ियां

5.3. /privet/printer/jobstate API

5.3.1. इनपुट

5.3.2. वापसी का टिकट

5.3.3. गड़बड़ियां

6. अन्य जानकारी

6.1. डिफ़ॉल्ट ऐक्शन और सेटिंग

6.1.2 डिफ़ॉल्ट रजिस्ट्रेशन डायग्राम

6.2. XSSI और XSRF हमलों से बचाव

6.2.1. XSSI

6.2.2. XSRF

6.2.3 X-Privet टोकन जनरेट करने और पुष्टि करने का क्रम दिखाने वाला डायग्राम

6.3. वर्कफ़्लो के डायग्राम

6.3.1. प्रिंटर को बॉक्स से बाहर निकालने के बाद का वर्कफ़्लो

6.3.2. रजिस्टर किए गए प्रिंटर को चालू करना

6.3.3 XMPP सूचनाओं को मैनेज करने का वर्कफ़्लो

6.3.4. प्रिंटर की सेटिंग के वर्कफ़्लो की जांच करना

प्रिवेट