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