##
## util.py
## Login : <uli@pu.smp.net>
## Started on  Thu Jul 29 09:39:51 2010 Uli Fouquet
## $Id$
## 
## Copyright (C) 2010 Uli Fouquet
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2 of the License, or
## (at your option) any later version.
## 
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
## 
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##
"""Little helpers for applicant specific stuff.
"""
def get_applicant_data(reg_no, ac):
    """Validate credentials and return applicant data.
    
    Returns tuple ``(<APPLICANT_ENTRY>, <ACCESSCODE>) on
    successful validation and ``None`` else.

    We expect a JAMB registration number and an access code in format
    like ``PREFIX-XXX-YYYYYYYY`` where ``PREFIX`` is something like
    ``APP`` or ``PUDE``, ``XXX`` the access code series and
    ``YYYYYYYYYY`` the real accesscode number.
    """
    site = grok.getSite()
    if reg_no not in site['applications'].keys():
        return None
    applicant_data = site['applications'][reg_no]
    entries = site['accesscodes'].search(ac, 'pin')
    if len(entries) != 1:
        # XXX: If entries > 1 then we have a problem!
        return None
    # XXX: Maybe we have to mark reg_no as used here?
    return (applicant_data, entries[0])