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