SMCAPISpecification0103M自助借阅语言规则.docx
- 文档编号:732846
- 上传时间:2023-04-29
- 格式:DOCX
- 页数:38
- 大小:58.26KB
SMCAPISpecification0103M自助借阅语言规则.docx
《SMCAPISpecification0103M自助借阅语言规则.docx》由会员分享,可在线阅读,更多相关《SMCAPISpecification0103M自助借阅语言规则.docx(38页珍藏版)》请在冰点文库上搜索。
SMCAPISpecification0103M自助借阅语言规则
3MLibrarySystems
Smartcard/MagneticCard(SMC)
APISpecification
Version2.02.001.0
October30,2002
SMCAPISpecification.doc
TableofContents
1OVERVIEW2
2INTENDEDAUDIENCE2
3APIdescription2
3.1CharacterSet2
3.2ChangesinVersion2.022
4FunctionCalls2
4.1smc_GetLastErrorMessage()2
4.2smc_GetCardTypes()2
4.3smc_GetInterfaceVersion()2
4.4smc_GetReaderTypes()2
4.5smc_GetSoftwareVersion()2
4.6smc_Initialize()2
4.7smc_GetReaderInfo()2
4.8smc_Shutdown()2
4.9smc_VerifyInterfaceVersion()2
4.10smc_VerifyPIN()2
5NOTIFICATIONEvents2
5.1SMC_EVT_DETECT2
5.2SMC_EVT_PATRON2
5.3SMC_EVT_TRACK2
5.4SMC_EVT_TRACE2
5.5SMC_EVT_ERROR2
6DATASTRUCTURESANDDEFINES2
6.1SMC_CALLBACK2
6.2SMC_CONFIGStructure2
6.3DefinedConstantvalues2
6.4ErrorCodeValues2
6.5EventValues2
7IMPLEMENTATIONGUIDELINES2
7.1OperatingSystems2
7.2DLLNamingConventions2
7.3VersionInformation2
7.4smc.handcallingsequence2
7.5Generallimitations2
8RevisionHistory2
1
OVERVIEW
Thisdocumentdescribes3MLibrarySystems’SmartCard/MagneticCardApplicationProgrammingInterface(SMCAPI).TheSMCAPIallows3MapplicationstointeractwithvariousSmartCardsandmagneticstripecardsinageneralizedandsimplifiedway.ThegoalistoobtainPatronIDinformationfromthecardthroughaseriesoffunctioncallsandnotificationevents.Theapplicationdoesnotneedtoknowthedetailsofthespecificcardreader/cardtypeinuse.TheapplicationsimplycallsthefunctionsprovidedbytheSMCAPI,andrespondstothenotificationeventsgeneratedbytheSMCAPI.
Inorderforthisschemetowork,theSMCAPIfunctioncallsandnotificationeventsmustbeimplementedforeachcardreaderandcardtypeforwhichsupportisdesired.AspecificimplementationoftheSMCAPIforaspecificcardreader/cardtypeiscalledan“SMCAPIimplementation”.SMCAPIimplementationsexistasDynamicLinkLibraries(DLLs)onWindowsplatforms.
Wheneversupportforanewtypeofcardreaderorcardtypeisdesired,anewSMCAPIimplementationmustbewritten.Thatis,anewDLLmustbewrittenwhichsuppliesthefunctionsspecifiedbytheSMCAPIandwhichgeneratesthenotificationeventsspecifiedbytheSMCAPI.Internally,thenewDLLmustbeabletointeractwiththenewcardreaderhardwareandanydesiredcardtypes.
AsingleSMCAPIimplementationmaysupportmorethanonetypeofcardreader,andeachcardreadermaysupportmorethanonecardtype.Therefore,itisnotstrictlynecessarytowriteanewlibraryforeachnewcardreader/cardtype–theycanbeaddedtoanexistingSMCAPIimplementation.Note,however,thatthecurrentSMCAPIspecificationdoesnotallowanapplicationtoaccessmorethanonecardreader/cardtypeatatimethroughasingleSMCAPIimplementation.
Thislibrary-basedapproachtocardreadersupportallowsanapplicationtoeasilyswitchtoanewtypeofcardreaderorcardtypesimplybyupgradingtoanewlibrary.Nocodechangeswillbenecessary.
2INTENDEDAUDIENCE
Thisdocumentisintendedtobeaguidefor3rdpartydeveloperswhowillbeprovidingimplementationsthatsupportspecificcardreaders.ItisassumedthedeveloperisexperiencedintheCprogramminglanguageintheMicrosoftWindowsenvironment,preferablywithVisualC++.ExperiencewritingDLLsandknowledgeofmulti-threadedprogrammingtechniqueswillalsobehelpful.
3
APIdescription
TheSMCAPIprovidesastandardmethodforinteractingwithSmartCardsandMagCards.TheAPIconsistsofacombinationoffunctioncallsandnotificationevents.TheAPIfunctionsprovidedirectaccesstotheSmartCards/MagCards,andthenotificationeventsindicatewhenasynchronouseventsoccur(suchastheinsertionorremovalofacard,ortheavailabilityofpatroninformation).
TheSMCAPIfunctionsallowanapplicationto:
∙determinewhatcardreadersandcardtypesaresupportedbytheimplementation
∙retrieveversionandcompatibilityinformation
∙initializetheimplementation
∙shutdowntheimplementation
ThesuccessorfailureofanSMCAPIcallisindicatedbyareturncode.
ThefollowingtableliststheSMCAPIfunctions.
APIFunction
Description
smc_GetCardTypes
Returnsalistofcardtypessupportedforagivenreadertype
smc_GetInterfaceVersion
ReturnsastringrepresentingtheSMCAPIversion
smc_GetLastErrorMessage
Returnsadescriptionofthelasterrorencounteredduringafunctioncall.
smc_GetReaderInfo
Getsinformationaboutthecardreader
smc_GetReaderTypes
Returnsalistofreadertypessupportedbytheimplementation
smc_GetSoftwareVersion
Returnsastringrepresentingthesoftwareversion
smc_Initialize
Initializestheimplementation
smc_Shutdown
Shutsdowntheimplementation
smc_VerifyInterfaceVersion
VerifiesthattheimplementationsupportsthespecifiedAPIversion
smc_VerifyPIN
VerifiesthePINvalueforthecurrentcard
OnceanSMCAPIimplementationhasbeeninitializedthroughacalltothesmc_Initializefunction,theimplementationwillmonitorthecardreaderforthepresenceofcards.Whenacardisdetected,theimplementationwillgenerateanotificationeventtoindicatethepresenceofacard.Itwillthenattempttoretrievepatroninformation(ortrackinformationformagcards),whichwillbesenttotheapplicationthroughanothernotificationevent.Whenthestatusofthecardchanges,theimplementationwillgenerateadditionalevents.Theseeventsgiveanapplicationtheopportunitytorespondtotheadditionorremovalofcardsfromthereader.Theimplementationwillalsogenerateaneventwheneveranerroroccurs.
ThefollowingtableliststhenotificationeventsdefinedbytheSMCAPI.
Event
Description
SMC_EVT_DETECT
Acardhasbeeninserted,removed,orswiped.
SMC_EVT_PATRON
PatroninformationhasbeenreadfromaSmartCard.
SMC_EVT_TRACK
Trackinformationhasbeenreadfromamagneticcard.
SMC_EVT_TRACE
Atracemessageisbeingprovided.
SMC_EVT_ERROR
Anerroroccurredwithintheimplementation.
Thefollowingdiagramshowsthegeneralflowbetweenanapplicationandanimplementation.Ingeneral,anapplicationwillfirstcallsmc_VerifyInterfaceVersion()inordertodetermineiftheimplementationsupportstheSMCAPIversiontheapplicationexpectstouse.Next,theapplicationwillcallsmc_GetReaderTypes()andsmc_GetCardTypes()togetlistsofsupportedreadersandcardtypes.Usingoneofthesereadertypesandcardtypes,theapplicationwillthencallsmc_Initialize().smc_Initialize()willinitializethespecifiedreader,begintheprocessofwatchingforcards(thiswillprobablymeanthatanindependentthreadwillbestartedtomonitorthecardreader)andthenreturn.Ascardsareinsertedorremoved,thevariousSMCeventswillbegenerated.Finally,theapplicationwillcallsmc_Shutdown()toshutdownthecardreader.
3.1CharacterSet
TheSMCAPIrestrictsthecharactersettothesingle-bytecharacterscontainedinCodePage1252.Theerrormessages,readertypeandcardtypevaluesareallrestrictedtothisrangeofcharacters.
3.2ChangesinVersion2.02
Thissectiondescribesthechangesfromversion2.00.Thenewfunctionsaredescribedinthisdocument.
Thefollowingfunctionshavebeenadded:
NewFunction
smc_GetReaderInfo
Thefollowingeventhasbeenchanged:
Event
SMC_EVT_TRACE
4FunctionCalls
ThefollowingsectiondescribestheSMCAPIfunctioncallsingreaterdetail.Eachfunctionisgivenabriefdescription,followedbyitsprototype,adescriptionofitsparameters,adescriptionofitsreturnvalues,andanygeneralremarksthatmaybehelpful.
Notethatsomeoftheerrorvalueslistedforsomeofthefunctions(inparticular,thesmc_Initializefunction)maynotbereturnedbyallimplementations.Eachimplementationwillhavesomeleewayindeterminingwhicherrorvalueswillbereturned,andtheconditionsunderwhichtheywillbereturned.Alsonotethatwhiletheerrordescriptionsprovidedinthefollowingsectionsaresimpleandgeneric,eachimplementationmusttakecaretogenerateadescriptiveerrormessagewithasmuchspecificinformationaspossibletoaidindebugging.(Theseerrormessageswillberetrievedbythesmc_GetLastErrorMessagefunction.)
AlsonotethatanimplementationmaychoosetoreturnSMC_SYSTEM_ERRORasageneralcatch-allifnoneoftheothererrorvaluesseemappropriate.
4.1smc_GetLastErrorMessage()
Thesmc_GetLastErrorMessagefunctionreturnsadescriptionofthelasterrorencounteredbyanAPIfunction.
Prototype
intsmc_GetLastErrorMessage(
char*pszBuffer,//pointertobuffertoreceiveerrormessage
unsignedshortBytes//sizeofbuffer
);
Parameters
pszBufferPointertoabufferthatwillreceivetheerrormessage.TheerrormessageisaNULL-terminatedstring.Ifthebufferisnotlargeenoughtoholdtheentireerrormessage,themessagewillbetruncatedtofitwithinthebuffer(includingtheterminatingNULL).
BytesSizeofthebufferpointedtobypszBuffer.
ReturnValue
Thefollowingtableliststhereturncodesforthisfunction.
ReturnCode
Description
SMC_SUCCESS
Thefunctioncompletedsuccessfully.
SMC_ERROR_BUFFERSIZE
Thebufferisnotlargeenoughtoholdtheentiremessage;messagehasbeentruncated.
SMC_SYSTEM_ERROR
Asystemerroroccurred
Remarks
EachfunctionintheSMCAPIwillreturnanerrorcodeifanerroroccurs.Eachfunctionisalsoresponsibleforgeneratinganerrormessagedescribingtheerrorthatoccurred.Thiserrormessagemustbestored(perhapsinaglobalerrorbufferorinaclassmember)sothatitcanberetrievedatalatertimebythesmc_GetLastErrorMessagefunction.Thesmc_GetLastErrorMessagefunctions
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- SMCAPISpecification0103M 自助 借阅 语言 规则