1 /********************************************************************************
2 * $Id: ClientProtocol.java 153 2009-02-05 15:33:36Z sjardine $
3 *
4 * Copyright 2005,2008 Steven Jardine, MJN Services, Inc. <steve@mjnservices.com>
5 *
6 * All rights reserved. This program and the accompanying materials are made
7 * available under the terms of the GNU Lesser Public License v2.1 which
8 * accompanies this distribution, and is available at
9 * http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
10 *
11 * For more information on the HylaFAX Fax Server please see
12 * HylaFAX - http://www.hylafax.org or
13 * Hylafax+ - http://hylafax.sourceforge.net
14 *
15 * Contributors:
16 * Steven Jardine - Initial API and implementation
17 ******************************************************************************/
18 package gnu.hylafax;
19
20 import gnu.inet.ftp.ServerResponseException;
21
22 import java.io.FileNotFoundException;
23 import java.io.IOException;
24 import java.io.InputStream;
25 import java.net.InetAddress;
26 import java.net.UnknownHostException;
27
28 /***
29 * Interface for the HylaFAX client protocol.
30 *
31 * @version $Revision: 153 $
32 * @author Steven Jardine <steve@mjnservices.com>
33 */
34 public interface ClientProtocol {
35
36 /***
37 * Notify on all job state changes. Used with the JPARM NOTIFY command.
38 */
39 public static final String NOTIFY_ALL = "DONE+REQUEUE";
40
41 /***
42 * Notify when the job is done. Used with the JPARM NOTIFY command.
43 */
44 public static final String NOTIFY_DONE = "DONE";
45
46 /***
47 * Do not notify when the job is done or requeued. Used with the JPARM
48 * NOTIFY command.
49 */
50 public static final String NOTIFY_NONE = "NONE";
51
52 /***
53 * Notify when the job is requeued. Used with the JPARM NOTIFY command.
54 */
55 public static final String NOTIFY_REQUEUE = "REQUEUE";
56
57 /***
58 * use the GMT timezone for date fields.
59 */
60 public static final String TZONE_GMT = "GMT";
61
62 /***
63 * use the local timezone for date fields.
64 */
65 public static final String TZONE_LOCAL = "LOCAL";
66
67 /***
68 * establish administrator privileges given password
69 *
70 * @param password
71 * administrator password
72 * @exception IOException
73 * io error occurred
74 * @exception ServerResponseException
75 * server replied with an error code
76 */
77 public void admin(String password) throws IOException,
78 ServerResponseException;
79
80 /***
81 * Asks the HylaFAX server to answer the call to the specified modem. <br>
82 * Works only with established administrator priviledges.
83 *
84 * @param modem
85 * @throws IOException
86 * @throws ServerResponseException
87 */
88 public void answer(String modem) throws IOException,
89 ServerResponseException;
90
91 /***
92 * get site config parameters of the current client.
93 *
94 * @param parm
95 * the name of the site parameter to change
96 * @param value
97 * the value of the given parameter
98 * @exception IOException
99 * io error occurred
100 * @exception ServerResponseException
101 * server replied with an error code
102 */
103 public void config(String parm, int value) throws IOException,
104 ServerResponseException;
105
106 /***
107 * get site config parameters of the current client.
108 *
109 * @param parm
110 * the name of the site parameter to change
111 * @param value
112 * the value of the given parameter
113 * @exception IOException
114 * io error occurred
115 * @exception ServerResponseException
116 * server replied with an error code
117 */
118 public void config(String parm, long value) throws IOException,
119 ServerResponseException;
120
121 /***
122 * get site config parameters of the current client.
123 *
124 * @param parm
125 * the name of the site parameter to change
126 * @param value
127 * the value of the given parameter as an Object
128 * @exception IOException
129 * io error occurred
130 * @exception ServerResponseException
131 * server replied with an error code
132 */
133 public void config(String parm, Object value) throws IOException,
134 ServerResponseException;
135
136 /***
137 * get site config parameters of the current client.
138 *
139 * @param parm
140 * the name of the site parameter to change
141 * @param value
142 * the value of the given parameter
143 * @exception IOException
144 * io error occurred
145 * @exception ServerResponseException
146 * server replied with an error code
147 */
148 public void config(String parm, String value) throws IOException,
149 ServerResponseException;
150
151 /***
152 * get the FILEFMT string value. The FILEFMT string specifies how file
153 * status information is formatted when returned by the LIST and STAT
154 * commands. Refer to the HylaFAX man pages, hfaxd(8c), for information on
155 * the formatting codes that can be used in this string.
156 *
157 * @exception IOException
158 * a socket IO error occurred
159 * @exception ServerResponseException
160 * the server replied with an error code
161 * @return the current FILEFMT value
162 */
163 public String filefmt() throws IOException, ServerResponseException;
164
165 /***
166 * set the FILEFMT string value. the FILEFMT string specifies how file
167 * status information is returned when the LIST and STAT commands are used.
168 * Refer to the HylaFAX man pages, hfaxd(8c), for the formatting codes.
169 *
170 * @param value
171 * the new value of the FILEFMT string
172 * @exception IOException
173 * a socket IO error occurred
174 * @exception ServerResponseException
175 * the server replied with an error code
176 */
177 public void filefmt(String value) throws IOException,
178 ServerResponseException;
179
180 /***
181 * specify data transfer format
182 *
183 * @param value
184 * the data transfer format.
185 * @exception IOException
186 * a socket IO error occurred
187 * @exception ServerResponseException
188 * the server responded with an error code
189 */
190 public void form(String value) throws IOException, ServerResponseException;
191
192 /***
193 * get the current idle timeout in seconds
194 *
195 * @exception IOException
196 * io error occurred
197 * @exception ServerResponseException
198 * server replied with an error code
199 * @return server's idle timeout in seconds
200 */
201 public long idle() throws IOException, ServerResponseException;
202
203 /***
204 * set the idle timeout value to the given number of seconds
205 *
206 * @param timeout
207 * new timeout value in seconds (MAX = 7200)
208 * @exception IOException
209 * io error occurred
210 * @exception ServerResponseException
211 * server replied with an error code
212 */
213 public void idle(long timeout) throws IOException, ServerResponseException;
214
215 /***
216 * delete the given job this can be called on a suspended or done job.
217 *
218 * @param jobid
219 * id of the job to delete
220 * @exception IOException
221 * a socket IO error occurred
222 * @exception ServerResponseException
223 * server replied with error code
224 */
225 public void jdele(long jobid) throws IOException, ServerResponseException;
226
227 /***
228 * interrupt the given job id
229 *
230 * @param jobid
231 * id of the job to interrupt
232 * @exception IOException
233 * a socket IO error occurred
234 * @exception ServerResponseException
235 * the server replied with an error code
236 */
237 public void jintr(long jobid) throws IOException, ServerResponseException;
238
239 /***
240 * kill the job with the given job id
241 *
242 * @param jobid
243 * the id of the job to kill
244 * @exception IOException
245 * a socket IO error occurred
246 * @exception ServerResponseException
247 * the server replied with an error code
248 */
249 public void jkill(long jobid) throws IOException, ServerResponseException;
250
251 /***
252 * create a new job. get the new job id using the job() method. The new job
253 * is the current job.
254 *
255 * @exception IOException
256 * a socket IO error occurred
257 * @exception ServerResponseException
258 * the server replied with an error code
259 */
260 public void jnew() throws IOException, ServerResponseException;
261
262 /***
263 * create a new job. get the new job id using the job() method. The new job
264 * is the current job.
265 *
266 * @param useDefaultJob
267 * if true the default job is selected prior to the jnew call. If
268 * false the job inherits parameters from the last job selected.
269 * This functionality may change if the default parameters from
270 * the hfaxd server is changed.
271 * @exception IOException
272 * a socket IO error occurred
273 * @exception ServerResponseException
274 * the server replied with an error code
275 */
276 public void jnew(boolean useDefaultJob) throws IOException,
277 ServerResponseException;
278
279 /***
280 * get the current job id 0 indicates the current job id is "default" value
281 *
282 * @exception IOException
283 * io error occurred
284 * @exception ServerResponseException
285 * server replied with an error code
286 */
287 public long job() throws IOException, ServerResponseException;
288
289 /***
290 * set the current job id
291 *
292 * @param value
293 * new current job id
294 * @exception IOException
295 * io error occurred
296 * @exception ServerResponseException
297 * server replied with an error code
298 */
299 public void job(long value) throws IOException, ServerResponseException;
300
301 /***
302 * get the job format string. read the HylaFAX man pages, hfaxd(8c), for
303 * format codes.
304 *
305 * @exception IOException
306 * a socket IO error occurred.
307 * @exception ServerResponseException
308 * the server responded with an error code
309 */
310 public String jobfmt() throws IOException, ServerResponseException;
311
312 /***
313 * set the job format string. read the HylaFAX man pages, hfaxd(8c), for
314 * format codes.
315 *
316 * @param value
317 * new job format string
318 * @exception IOException
319 * a socket IO error occurred.
320 * @exception ServerResponseException
321 * the server responded with an error
322 */
323 public void jobfmt(String value) throws IOException,
324 ServerResponseException;
325
326 /***
327 * get job parameters of the current job
328 *
329 * @param parm
330 * the name of the job parameter to change
331 * @exception IOException
332 * io error occurred
333 * @exception ServerResponseException
334 * server replied with an error code
335 * @return value of the named job parameter
336 */
337 public String jparm(String parm) throws IOException,
338 ServerResponseException;
339
340 /***
341 * set job parameters on the current job
342 *
343 * @param parm
344 * the name of the job parameter to change
345 * @param value
346 * the value of the given parameter
347 * @exception IOException
348 * io error occurred
349 * @exception ServerResponseException
350 * server replied with an error code
351 */
352 public void jparm(String parm, int value) throws IOException,
353 ServerResponseException;
354
355 /***
356 * set job parameters on the current job
357 *
358 * @param parm
359 * the name of the job parameter to change
360 * @param value
361 * the value of the given parameter
362 * @exception IOException
363 * io error occurred
364 * @exception ServerResponseException
365 * server replied with an error code
366 */
367 public void jparm(String parm, long value) throws IOException,
368 ServerResponseException;
369
370 /***
371 * set job parameters on the current job
372 *
373 * @param parm
374 * the name of the job parameter to change
375 * @param value
376 * the value of the given parameter as an Object
377 * @exception IOException
378 * io error occurred
379 * @exception ServerResponseException
380 * server replied with an error code
381 */
382 public void jparm(String parm, Object value) throws IOException,
383 ServerResponseException;
384
385 /***
386 * set job parameters on the current job
387 *
388 * @param parm
389 * the name of the job parameter to change
390 * @param value
391 * the value of the given parameter
392 * @exception IOException
393 * io error occurred
394 * @exception ServerResponseException
395 * server replied with an error code
396 */
397 public void jparm(String parm, String value) throws IOException,
398 ServerResponseException;
399
400 /***
401 * reset the state of the current job. get/set the current job id via the
402 * 'job' method
403 *
404 * @exception IOException
405 * an IO error occurred
406 * @exception ServerResponseException
407 * the server replied with an error code
408 */
409 public void jrest() throws IOException, ServerResponseException;
410
411 /***
412 * submit the current job to the scheduler
413 *
414 * @return the job id
415 * @exception IOException
416 * io error occurred
417 * @exception ServerResponseException
418 * server replied with an error code
419 */
420 public long jsubm() throws IOException, ServerResponseException;
421
422 /***
423 * submit the given job to the scheduler
424 *
425 * @param jobid
426 * the id of the job to submit
427 * @exception IOException
428 * io error occurred
429 * @exception ServerResponseException
430 * server replied with an error code
431 * @return the submitted job id, should match jobid passed in
432 */
433 public int jsubm(long jobid) throws IOException, ServerResponseException;
434
435 /***
436 * Suspend the job with the given job id.
437 *
438 * @param jobid
439 * id of the job to suspend
440 * @exception IOException
441 * io error occurred
442 * @exception ServerResponseException
443 * server replied with an error code
444 */
445 public void jsusp(long jobid) throws IOException, ServerResponseException;
446
447 /***
448 * Wait for the job with the given job id to complete.
449 *
450 * @param jobid
451 * id of the job to wait for
452 * @exception IOException
453 * io error occurred
454 * @exception ServerResponseException
455 * server replied with an error code
456 */
457 public void jwait(long jobid) throws IOException, ServerResponseException;
458
459 /***
460 * get the modem format string value. the modem format string specifies how
461 * modem status information should be displayed. refer to the HylaFAX man
462 * pages, hfaxd(8c), for the format string codes.
463 *
464 * @exception IOException
465 * a socket IO error occurred
466 * @exception ServerResponseException
467 * the server responded with an error code
468 */
469 public String mdmfmt() throws IOException, ServerResponseException;
470
471 /***
472 * set the modem format string. the modem format string is used to format
473 * the modem status information. Refer to the HylaFAX man pages, hfaxd(8c),
474 * for formatting codes.
475 *
476 * @param value
477 * the new modem format string to use
478 * @exception IOException
479 * a socket IO error occurred
480 * @exception ServerResponseException
481 * the server responded with an error code
482 */
483 public void mdmfmt(String value) throws IOException,
484 ServerResponseException;
485
486 /***
487 * perform server No Operation could be used as a keep-alive
488 *
489 * @exception IOException
490 * io error occurred
491 * @exception ServerResponseException
492 * server replied with an error code
493 */
494 public void noop() throws IOException, ServerResponseException;
495
496 /***
497 * open a connection to the localhost on the default port
498 *
499 * @exception UnknownHostException
500 * cannot resolve the given hostname
501 * @exception IOException
502 * IO error occurred
503 * @exception ServerResponseException
504 * the server replied with an error code
505 */
506 public void open() throws UnknownHostException, IOException,
507 ServerResponseException;
508
509 /***
510 * open a connection to a given server at default port this is an alias for
511 * connect()
512 *
513 * @param host
514 * the hostname of the HylaFAX server
515 * @exception UnknownHostException
516 * cannot resolve the given hostname
517 * @exception IOException
518 * IO error occurred
519 * @exception ServerResponseException
520 * the server replied with an error code
521 */
522 public void open(String host) throws UnknownHostException, IOException,
523 ServerResponseException;
524
525 /***
526 * send the password for this username and session
527 *
528 * @param password
529 * the password to login with
530 * @exception IOException
531 * io error occurred
532 * @exception ServerResponseException
533 * server replied with an error code
534 */
535 public void pass(String password) throws IOException,
536 ServerResponseException;
537
538 /***
539 * end session
540 *
541 * @exception IOException
542 * io error occurred
543 * @exception ServerResponseException
544 * server replied with an error code
545 */
546 public void quit() throws IOException, ServerResponseException;
547
548 /***
549 * get the received file output format string. The rcvfmt string specifies
550 * how received faxes (files in the rcvq directory) are displayed. Refer to
551 * the HylaFAX man pages, hfaxd(8c), for the format string codes.
552 *
553 * @exception IOException
554 * a socket IO error occurred
555 * @exception ServerResponseException
556 * the server responded with an error code
557 */
558 public String rcvfmt() throws IOException, ServerResponseException;
559
560 /***
561 * set the receive file output format string. The rcvfmt string specifies
562 * how received faxes (files in the rcvq directory) are displayed. refer to
563 * the HylaFAX man pages, hfaxd(8c), for the format string codes.
564 *
565 * @param value
566 * the new format string
567 * @exception IOException
568 * a socket IO error occurred
569 * @exception ServerResponseException
570 * the server responded with an error code
571 */
572 public void rcvfmt(String value) throws IOException,
573 ServerResponseException;
574
575 /***
576 * set site parameters on the current client.
577 *
578 * @param parm
579 * the name of the site parameter to change
580 * @param value
581 * the value of the given parameter
582 * @exception IOException
583 * io error occurred
584 * @exception ServerResponseException
585 * server replied with an error code
586 */
587 public void site(String parm, int value) throws IOException,
588 ServerResponseException;
589
590 /***
591 * set site parameters on the current client.
592 *
593 * @param parm
594 * the name of the site parameter to change
595 * @param value
596 * the value of the given parameter
597 * @exception IOException
598 * io error occurred
599 * @exception ServerResponseException
600 * server replied with an error code
601 */
602 public void site(String parm, long value) throws IOException,
603 ServerResponseException;
604
605 /***
606 * set site parameters on the current client.
607 *
608 * @param parm
609 * the name of the site parameter to change
610 * @param value
611 * the value of the given parameter as an Object
612 * @exception IOException
613 * io error occurred
614 * @exception ServerResponseException
615 * server replied with an error code
616 */
617 public void site(String parm, Object value) throws IOException,
618 ServerResponseException;
619
620 /***
621 * set site parameters on the current client.
622 *
623 * @param parm
624 * the name of the site parameter to change
625 * @param value
626 * the value of the given parameter
627 * @exception IOException
628 * io error occurred
629 * @exception ServerResponseException
630 * server replied with an error code
631 */
632 public void site(String parm, String value) throws IOException,
633 ServerResponseException;
634
635 /***
636 * Returns the size (in bytes) of the given regular file. This is the size
637 * on the server and may not accurately represent the file size once the
638 * file has been transferred (particularly via ASCII mode)
639 *
640 * @param pathname
641 * the name of the file to get the size for
642 * @exception IOException
643 * caused by a socket IO error
644 * @exception ServerResponseException
645 * caused by a server response indicating an error
646 * @exception FileNotFoundException
647 * the given path does not exist
648 */
649 public long size(String pathname) throws IOException,
650 FileNotFoundException, ServerResponseException;
651
652 /***
653 * store temp file, the file is stored in a uniquely named file on the
654 * server. The remote temp file is deleted when the connection is closed.
655 *
656 * @exception IOException
657 * io error occurred talking to the server
658 * @exception ServerResponseException
659 * server replied with error code
660 * @return the filename of the temp file
661 */
662 public String stot(InputStream data) throws IOException,
663 ServerResponseException;
664
665 /***
666 * set the timezone display format valid tzone values are TZONE_GMT and
667 * TZONE_LOCAL
668 *
669 * @param value
670 * new timezone display setting
671 * @exception IOException
672 * io error occurred
673 * @exception ServerResponseException
674 * server replied with an error code
675 */
676 public void tzone(String value) throws IOException, ServerResponseException;
677
678 /***
679 * send the user name for this session
680 *
681 * @param username
682 * name of the user to login as
683 * @exception IOException
684 * io error occurred
685 * @exception ServerResponseException
686 * server replied with an error code
687 * @return true if a password is required, false if no password is required
688 */
689 public boolean user(String username) throws IOException,
690 ServerResponseException;
691
692 /***
693 * verify dialstring handling and/or least-cost routing.
694 *
695 * @param dialstring
696 * the dialstring to verify
697 * @exception IOException
698 * a socket IO error occurred
699 * @exception ServerResponseException
700 * the server replied with an error code
701 * @return the InetAddress of the server that will handle the given
702 * dialstring
703 */
704 public InetAddress vrfy(String dialstring) throws IOException,
705 ServerResponseException;
706
707 }