1*TODO(dchest): Add example images and audio.*
  2
  3Package captcha
  4=====================
  5
  6	import "github.com/dchest/captcha"
  7
  8Package captcha implements generation and verification of image and audio
  9CAPTCHAs.
 10
 11
 12Constants
 13---------
 14
 15	const (
 16		// Standard number of digits in captcha.
 17		StdLength = 6
 18		// The number of captchas created that triggers garbage collection used
 19		// by default store.
 20		CollectNum = 100
 21		// Expiration time of captchas used by default store.
 22		Expiration = 10 * 60 // 10 minutes
 23
 24	)
 25
 26
 27	const (
 28	    // Standard width and height of a captcha image.
 29	    StdWidth  = 300
 30	    StdHeight = 80
 31	)
 32
 33
 34
 35Variables
 36---------
 37
 38	var ErrNotFound = os.NewError("captcha with the given id not found")
 39
 40
 41
 42Functions
 43---------
 44
 45### func Collect
 46
 47	func Collect()
 48	
 49Collect deletes expired or used captchas from the internal storage. It is
 50called automatically by New function every CollectNum generated captchas,
 51but still exported to enable freeing memory manually if needed.
 52
 53Collection is launched in a new goroutine.
 54
 55### func New
 56
 57	func New(length int) (id string)
 58	
 59New creates a new captcha of the given length, saves it in the internal
 60storage, and returns its id.
 61
 62### func RandomDigits
 63
 64	func RandomDigits(length int) []byte
 65	
 66RandomDigits returns a byte slice of the given length containing random
 67digits in range 0-9.
 68
 69### func Reload
 70
 71	func Reload(id string) bool
 72	
 73Reload generates and remembers new digits for the given captcha id.  This
 74function returns false if there is no captcha with the given id.
 75
 76After calling this function, the image or audio presented to a user must be
 77refreshed to show the new captcha representation (WriteImage and WriteAudio
 78will write the new one).
 79
 80### func Server
 81
 82	func Server(w, h int) http.Handler
 83	
 84Server returns a handler that serves HTTP requests with image or
 85audio representations of captchas. Image dimensions are accepted as
 86arguments. The server decides which captcha to serve based on the last URL
 87path component: file name part must contain a captcha id, file extension —
 88its format (PNG or WAV).
 89
 90For example, for file name "B9QTvDV1RXbVJ3Ac.png" it serves an image captcha
 91with id "B9QTvDV1RXbVJ3Ac", and for "B9QTvDV1RXbVJ3Ac.wav" it serves the
 92same captcha in audio format.
 93
 94To serve an audio captcha as downloadable file, append "?get" to URL.
 95
 96To reload captcha (get a different solution for the same captcha id), append
 97"?reload=x" to URL, where x may be anything (for example, current time or a
 98random number to make browsers refetch an image instead of loading it from
 99cache).
100
101### func SetCustomStore
102
103	func SetCustomStore(s Store)
104	
105SetCustomStore sets custom storage for captchas, replacing the default
106memory store. This function must be called before generating any captchas.
107
108### func Verify
109
110	func Verify(id string, digits []byte) bool
111	
112Verify returns true if the given digits are the ones that were used to
113create the given captcha id.
114
115The function deletes the captcha with the given id from the internal
116storage, so that the same captcha can't be verified anymore.
117
118### func VerifyString
119
120	func VerifyString(id string, digits string) bool
121	
122VerifyString is like Verify, but accepts a string of digits.  It removes
123spaces and commas from the string, but any other characters, apart from
124digits and listed above, will cause the function to return false.
125
126### func WriteAudio
127
128	func WriteAudio(w io.Writer, id string) os.Error
129	
130WriteAudio writes WAV-encoded audio representation of the captcha with the
131given id.
132
133### func WriteImage
134
135	func WriteImage(w io.Writer, id string, width, height int) os.Error
136	
137WriteImage writes PNG-encoded image representation of the captcha with the
138given id. The image will have the given width and height.
139
140
141Types
142-----
143
144	type Audio struct {
145    // contains unexported fields
146}
147	
148
149### func NewAudio
150
151	func NewAudio(digits []byte) *Audio
152	
153NewImage returns a new audio captcha with the given digits, where each digit
154must be in range 0-9.
155
156### func (*Audio) EncodedLen
157
158	func (a *Audio) EncodedLen() int
159	
160EncodedLen returns the length of WAV-encoded audio captcha.
161
162### func (*Audio) WriteTo
163
164	func (a *Audio) WriteTo(w io.Writer) (n int64, err os.Error)
165	
166WriteTo writes captcha audio in WAVE format into the given io.Writer, and
167returns the number of bytes written and an error if any.
168
169	type Image struct {
170	    *image.NRGBA
171	    // contains unexported fields
172	}
173	
174
175### func NewImage
176
177	func NewImage(digits []byte, width, height int) *Image
178	
179NewImage returns a new captcha image of the given width and height with the
180given digits, where each digit must be in range 0-9.
181
182### func (*Image) WriteTo
183
184	func (img *Image) WriteTo(w io.Writer) (int64, os.Error)
185	
186WriteTo writes captcha image in PNG format into the given writer.
187
188	type Store interface {
189	    // Set sets the digits for the captcha id.
190	    Set(id string, digits []byte)
191
192	    // Get returns stored digits for the captcha id. Clear indicates
193	    // whether the captcha must be deleted from the store.
194	    Get(id string, clear bool) (digits []byte)
195
196	    // Collect deletes expired captchas from the store.  For custom stores
197	    // this method is not called automatically, it is only wired to the
198	    // package's Collect function.  Custom stores must implement their own
199	    // procedure for calling Collect, for example, in Set method.
200	    Collect()
201	}
202	
203An object implementing Store interface can be registered with SetCustomStore
204function to handle storage and retrieval of captcha ids and solutions for
205them, replacing the default memory store.
206
207### func NewMemoryStore
208
209	func NewMemoryStore(collectNum int, expiration int64) Store
210	
211NewMemoryStore returns a new standard memory store for captchas with the
212given collection threshold and expiration time in seconds. The returned
213store must be registered with SetCustomStore to replace the default one.
214
215
216Bugs
217----
218
219[Not our bug] Google Chrome 10 plays unsigned 8-bit PCM WAVE
220audio on Mac with horrible distortions.  Issue:
221http://code.google.com/p/chromium/issues/detail?id=70730.
222This has been fixed, and version 12 will play them properly.
223
224While Image conforms to io.WriterTo interface, its WriteTo
225method returns 0 instead of the actual bytes written because png.Encode
226doesn't report this.